Skip to content

janspoerer/mcp_agent_messenging

BranchesTags

Repository files navigation

MCP Agent Messaging Server

A Model Context Protocol (MCP) server that enables agent-to-agent communication through project-based chat rooms. Each agent receives a unique German name and can communicate with other agents working in the same project directory.

Getting Started

  1. Install dependencies: 
    npm install

Quick Start

  1. Build the server:

    npm run build

  2. Run the server:

    npm start

  3. Send a message: Use the send_message tool with your desired message content.

    {
  "message": "Hello from my agent!"
}

  4. Read messages: Use the read_messages tool to see the conversation.

    {
  "count": 10
}

Features

Core Features

  • Project-based Chat Rooms: Separate chat rooms for each project path/directory
  • Persistent Storage: Chat history saved to JSON files (one file per project)
  • Automatic Agent Naming: Each agent receives a unique German name (Hans, Friedrich, Greta, etc.)
  • Real-time Messaging: Agents can send and receive messages within their project chat
  • Agent Discovery: See which agents are active in your project
  • System Notifications: Automatic notifications when agents join or leave

Tier 2 Advanced Features

  • Structured Messages: Rich message types (text, system, command, notification) with metadata
  • Message IDs: Unique identifiers for each message enabling tracking and acknowledgment
  • Timestamps: ISO 8601 timestamps on all messages for precise timing
  • Advanced Filtering: Filter messages by timestamp or time range (last N seconds)
  • Message Pruning: Automatic cleanup - keeps last 1000 messages (configurable)
  • Compression: Gzip compression for 80% storage savings
  • Cross-Process Safety: Atomic operations and file locking prevent race conditions

Architecture

The server is built with a clean, modular architecture:

src/
├── types.ts           # TypeScript type definitions
├── agent-namer.ts     # German name assignment system
├── persistence.ts     # JSON file persistence layer
├── chat-manager.ts    # Chat room and message management
└── index.ts           # MCP server implementation

data/                  # Chat history (one JSON file per project)
└── <sanitized_path>.json

Components

  • AgentNamer: Manages the pool of German names and assigns unique names to agents
  • PersistenceManager: Handles saving/loading chat rooms to/from JSON files
  • ChatManager: Handles chat room creation, message storage, and agent connections
  • MCP Server: Exposes three tools for agent communication

Installation

# Build the project
npm run build

# Run the server
npm start

API Reference

The server provides four tools for agent communication.

read_messages

Read messages from other agents in your project's shared chat room. Use this to catch up on the conversation and see what other agents are working on.

  • Parameters:
    • count (optional, number): Number of recent messages to retrieve (1-100).
    • project_path (optional, string): Project directory path. Defaults to the current working directory.
    • since_timestamp (optional, string): ISO 8601 timestamp to retrieve messages after this time.
    • last_seconds (optional, number): Retrieve messages from the last N seconds.
  • Returns:
    • Your agent's name.
    • A list of messages in chronological order.
  • Examples:
    • Get the last 10 messages: 
      { "count": 10 }
    • Get messages from the last 5 minutes: 
      { "last_seconds": 300 }

send_message

Send a message to other agents in your project's shared chat room. Use this to coordinate tasks, share status updates, or ask for help.

  • Parameters:
    • message (required, string): The message content.
    • project_path (optional, string): Project directory path.
    • message_type (optional, string): Type of message ('text', 'command', 'notification', 'system'). Defaults to 'text'.
    • metadata (optional, object): Additional structured data.
  • Returns:
    • Confirmation with your agent's name and the message ID.
  • Example: 
    {
  "message": "Deploying version 1.2.3 to production.",
  "message_type": "command",
  "metadata": { "version": "1.2.3" }
}

search_messages

Search the shared chat history for messages from any agent that match a specific query. Useful for finding past conversations or specific information.

  • Parameters:
    • query (required, string): The text to search for in the message content.
    • project_path (optional, string): Project directory path.
  • Returns:
    • Your agent's name.
    • A list of messages that match the search query.
  • Example: 
    {
  "query": "deployment"
}

get_agent_names

See which other agents are currently active in your project's chat room. This helps you know who you can collaborate with.

  • Parameters:
    • project_path (optional, string): Project directory path.
  • Returns:
    • Your agent's name.
    • A list of active agent names.
  • Example: 
    { "project_path": "/path/to/project" }

heartbeat

Signal your presence to other agents in the chat room. Use this during long-running tasks to let others know you are still online and active.

  • Parameters:
    • project_path (optional, string): Project directory path.
  • Returns:
    • Confirmation with your agent's name.
  • Example: 
    { "project_path": "/path/to/project" }

Message Pruning & Retention

The system automatically manages message history to prevent unbounded disk growth:

Default Behavior

  • Limit: Keeps the last 1000 messages per chat room
  • Pruning: Oldest messages are automatically removed when the limit is exceeded
  • Timing: Pruning happens automatically when sending messages

Configurable Retention

You can customize the retention limit using an environment variable:

# Keep last 500 messages (smaller footprint)
export MCP_MESSAGE_RETENTION_LIMIT=500

# Keep last 5000 messages (larger history)
export MCP_MESSAGE_RETENTION_LIMIT=5000

# Run the server
npm start

Configuration Rules:

  • Minimum: 100 messages
  • Maximum: 50000 messages
  • Default: 1000 messages
  • Invalid values fall back to default with a warning

Example Configuration

# For a small team with frequent messages
MCP_MESSAGE_RETENTION_LIMIT=500 npm start

# For a large project with important history
MCP_MESSAGE_RETENTION_LIMIT=10000 npm start

Storage & Performance

Compression

  • Messages are stored with Gzip compression
  • Achieves ~80% storage savings on typical chat files
  • Transparent - compression/decompression happens automatically

Storage Location

  • Chat history: ./data/<project_hash>.json.gz
  • Agent identity: ./.mcp-identities/.agent-identity-<PID>-<timestamp>.json
  • All relative to the project directory

Performance Characteristics

  • Disk I/O: Each operation reloads from disk for consistency
  • File Locking: Cross-process safe with atomic operations
  • Scalability: Suitable for ~200 messages/second per chat room

Key Concepts

This messaging system is built on a few simple but powerful concepts:

  1. File-Based Communication: Agents communicate by reading and writing to a shared JSON file in the data/ directory. There is one file per project, and the file is named after a sanitized version of the project path. This approach requires no central server or network connection.

  2. Agent Identity: Each agent instance is given a unique German name (e.g., "Hans", "Greta") when it first starts. This identity is stored in a .agent-identity.json file in the agent's working directory and is reused across restarts.

  3. Data Persistence: All messages are stored in the project's JSON file. The chat history is loaded from this file before each operation and saved back immediately after, ensuring that all agents have a consistent view of the conversation.

  4. Agent Discovery: The list of "active" agents is derived from the sender field of recent messages in the chat history. The heartbeat tool allows agents to signal their presence, which adds a "system" message to the chat and keeps them in the active list.

Example Usage Scenario

// Agent 1 (Hans) in /project/frontend
send_message({ message: "Starting work on the login page" })

// Agent 2 (Friedrich) joins /project/frontend
// System: "Friedrich has joined the chat"

read_messages({ count: 5 })
// Output:
// You are: Friedrich
// Last 5 message(s):
// [10:30:15] System: Hans has joined the chat
// [10:31:22] Hans: Starting work on the login page
// [10:32:10] System: Friedrich has joined the chat

get_agent_names()
// Output:
// You are: Friedrich
// Agents in this chat room:
// Hans, Friedrich

// Friedrich sends a message
send_message({ message: "I'll handle the backend API" })

German Names

The server includes 50 traditional German names (25 male, 25 female):

Male names: Hans, Friedrich, Karl, Wilhelm, Otto, Heinrich, Hermann, Ernst, Paul, Werner, Walter, Franz, Josef, Ludwig, Georg, Klaus, Günter, Dieter, Helmut, Jürgen, Gerhard, Wolfgang, Horst, Manfred, Bernd

Female names: Greta, Frieda, Margarete, Emma, Anna, Liesel, Helga, Gertrud, Ingrid, Monika, Ursula, Brigitte, Christa, Renate, Petra, Sabine, Heike, Katrin, Claudia, Stefanie, Anke, Ute, Beate, Karin, Martina

If more than 50 agents are active, names will be suffixed with numbers (e.g., Hans2, Friedrich2).

Configuration for Claude Code

This messaging server is designed to be used with Claude Code, an experimental AI coding assistant from Anthropic.

Important: Multi-Instance Architecture

Each Claude Code agent runs its own instance of this MCP server. Agents communicate by reading/writing shared JSON files in the data/ directory.

How it works:

  1. Agent 1 (Hans) runs instance A → writes to data/project_x.json
  2. Agent 2 (Friedrich) runs instance B → reads from data/project_x.json
  3. They see each other's messages through the shared file

Setup Instructions

  1. Build the project (if you haven't already):

    cd /Users/janspoerer/code/miscellaneous/mcp_agent_messenging
npm install
npm run build

  2. Add to Claude Code settings:

    • Open Claude Code settings
    • Add the MCP server configuration:
{
  "mcpServers": {
    "agent-messaging": {
      "command": "node",
      "args": [
        "/Users/janspoerer/code/miscellaneous/mcp_agent_messenging/dist/index.js"
      ]
    }
  }
}
  1. Start using it:
    • Each Claude Code instance will get a unique German name
    • The name persists in .agent-identity.json
    • All agents in the same project path share messages via data/ folder

Multiple Agents Example

# Agent 1 terminal
claude-code
# Gets name "Hans", can use send_message

# Agent 2 terminal (same data/ folder)
claude-code
# Gets name "Friedrich", can use read_messages to see Hans's messages

Multiple Projects with Separate Agent Groups

The system supports complete isolation between different projects. Each project path gets its own isolated chat room with separate message history.

Example: Three Independent Projects

Project A: /path/to/frontend
├─ Agents: Hans, Friedrich, Greta
├─ Messages: Frontend development discussions
└─ Chat file: data/hash-frontend.json.gz

Project B: /path/to/backend
├─ Agents: Emma, Wilhelm, Sabine
├─ Messages: Backend API discussions
└─ Chat file: data/hash-backend.json.gz

Project C: /path/to/infrastructure
├─ Agents: Karl, Liesel, Georg
├─ Messages: DevOps and infrastructure
└─ Chat file: data/hash-infrastructure.json.gz

Key Features:

  • ✅ Complete message isolation - Project A messages never appear in Project B
  • ✅ Independent chat histories - Each project maintains its own message history
  • ✅ Separate agent groups - Different teams can work without interference
  • ✅ Cross-project agent work - Same agent can work in multiple projects (messages stay isolated per project)
  • ✅ Scalable to many projects - No limit on number of concurrent projects

Example: Agent Working in Multiple Projects

// Same agent (Hans) working in multiple projects
// All messages are properly isolated by project

// Working on Frontend
send_message({
  message: "Fixed login form validation",
  project_path: "/path/to/frontend"
})

// Later, working on Backend
send_message({
  message: "Implemented new API endpoint",
  project_path: "/path/to/backend"
})

// Query each project independently
read_messages({ project_path: "/path/to/frontend" })
// Returns: Only frontend messages

read_messages({ project_path: "/path/to/backend" })
// Returns: Only backend messages (no frontend messages)

How Project Isolation Works:

  1. Project path is hashed using SHA256 → generates unique filename
  2. /path/to/frontend → data/a1b2c3.json.gz
  3. /path/to/backend → data/d4e5f6.json.gz
  4. Different files = completely isolated data
  5. Atomic file locking ensures thread-safety per project

Verified by Tests:

  • ✅ 4 comprehensive multi-project isolation tests
  • ✅ Message isolation between 2+ projects confirmed
  • ✅ Filtering works correctly per-project
  • ✅ No cross-project contamination possible

Development

# Install dependencies
npm install

# Build and run
npm run dev

TypeScript Types

All core types are defined in src/types.ts:

  • Message: Individual chat messages with sender, content, and timestamp
  • ChatRoom: Chat room data including agents and message history
  • AgentConnection: Agent connection metadata

The src/persistence.ts module handles all file I/O operations with automatic serialization/deserialization.

Error Handling

The server handles common error cases:

  • Agent not connected: Automatically connects on first tool call
  • Empty messages: Rejected with error message
  • Invalid message count: Must be between 1-100
  • Chat room not found: Returns empty arrays/lists

Testing

The system includes a comprehensive test suite with 33 unit tests covering all functionality:

Running Tests

# Run all tests
npm test

# Run tests in watch mode (auto-rerun on file changes)
npm run test:watch

# Generate coverage report
npm run test:coverage

Test Coverage

Tests cover the following components:

  • Agent Naming (5 tests): Unique name assignment, collision prevention, pool management
  • Persistence Layer (5+ tests): File I/O, compression, atomic operations, file locking
  • Chat Manager (10+ tests): Message operations, filtering, pruning, agent discovery
  • Message Filtering (5 tests): Timestamp filtering, time ranges, combined filters
  • Message Pruning (7 tests): Retention limits, FIFO removal, boundary conditions
  • Multi-Project Isolation (4 tests): NEW! Separate chat histories, filtering isolation, 3+ concurrent projects, cross-project agent work

Test Results

✅ Test Suites: 3 passed, 3 total
✅ Tests: 33 passed, 33 total
✅ Execution Time: ~2.1 seconds

New Multi-Project Tests (Verified):

  • ✅ Separate chat histories for different projects
  • ✅ Filtering results isolated between projects
  • ✅ Support for 3+ simultaneous independent projects
  • ✅ Agent can work in multiple projects without interference

All tests pass with zero failures, ensuring production readiness for multi-project scenarios.

Troubleshooting

"No such file or directory" error when running the server

This error usually means that you have not built the project yet. Run the following command to build the server:

npm run build

Not seeing messages from other agents

This can happen if you are not in the same project directory as the other agents. Make sure that you are in the same directory as the other agents, and that you have the correct permissions to read and write to the data directory.

License

MIT

Contributing

Contributions are welcome! Please follow these steps to contribute:

  1. Report Bugs: Use the issue tracker to report any bugs.
  2. Submit Pull Requests:
    • Fork the repository.
    • Create a new branch for your feature or bug fix.
    • Make your changes and commit them with a clear message.
    • Run npm test to ensure all tests pass.
    • Push your changes and open a pull request.

About

Lets your agents talk to each other via MCP.

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages