Related Pages

Related topics: System Architecture and Code Organization, MCP Tools Reference, Deployment, Configuration, and Operations

Project Overview and Use Cases

Purpose and Scope

agentchat-mcp is a Model Context Protocol (MCP) server implementation packaged as an npm module that exposes agent-based chat capabilities to MCP-compatible clients (such as Claude Desktop, IDEs, or other AI agent runtimes). The package is distributed under the name @agentchatme/mcp and is configured as a standard Node.js executable MCP server that other tools can spawn over stdio. Source: package.json:1-40.

The project is written in TypeScript and ships as both a CommonJS bundle (dist/index.js) and an ES module (dist/index.js with "type": "module"), making it consumable from a wide range of JavaScript runtimes. Source: package.json:15-25. Its primary purpose is to provide a thin, declarative bridge between an MCP host and an underlying "agentchat" service, surfacing conversation-oriented tools and resources without forcing the host to implement transport, authentication, or message framing.

High-Level Architecture

The runtime entry point is src/index.ts, which wires the MCP server together, registers the available tools, and hands control to the standard input/output transport layer. Source: src/index.ts:1-120. The server re-exports a small, focused surface area so that downstream packages can either embed it programmatically or invoke it as a subprocess via the bin field declared in package.json. Source: package.json:30-38.

Build-time metadata such as the exported version constant lives in src/version.ts, which is imported by the entry point to populate the MCP server's serverInfo payload. This lets clients negotiate capabilities and display accurate identification information. Source: src/version.ts:1-10.

The compile configuration is intentionally minimal, relying on tsconfig.json with the modern NodeNext module resolution and a strict TypeScript setup so that the compiled output is consumable by both ESM and CJS toolchains. Source: tsconfig.json:1-30.

┌──────────────┐   stdio/JSON-RPC   ┌────────────────────┐   HTTPS/WS   ┌──────────────────┐
│  MCP Host    │ ◄────────────────► │  agentchat-mcp     │ ◄──────────► │  AgentChat API   │
│ (e.g. IDE)   │                    │  (this package)    │              │  (remote agent)  │
└──────────────┘                    └────────────────────┘              └──────────────────┘

Core Features and Tools

The MCP server registers a set of tools that allow an MCP host to send messages to agents, retrieve conversation state, and stream or poll for replies. Each tool is declared with a JSON Schema for its inputs and is described in plain language so that the host's language model can decide when to invoke it. Source: src/index.ts:40-100.

Typical capabilities exposed by the server include:

• Send a message to a named agent or conversation thread, returning the agent's reply or an asynchronous handle for later polling.
• List available agents or rooms, allowing the host UI to render a picker without hard-coding identifiers.
• Fetch conversation history, which is useful for resuming multi-turn sessions.
• Subscribe to updates via MCP resource notifications, so the host can react when the agent finishes a long-running task.

Because every tool is declared declaratively, the host's model can plan multi-step interactions (for example, "list rooms → send message → read history") without the package needing to embed its own orchestration logic. Source: README.md:1-60.

Use Cases

1. IDE-Integrated Agent Assistance

A developer running an MCP-aware IDE can install @agentchatme/mcp as an MCP server, configure it once via the IDE's MCP settings, and then ask the in-editor assistant to delegate tasks to a remote agent. The IDE receives typed tool definitions, validates arguments, and renders the agent's reply inline. Source: README.md:20-80.

2. Chat from Claude Desktop or Similar Hosts

Users running desktop chat clients that speak MCP (for example, Claude Desktop) can register agentchat-mcp so that natural-language prompts automatically trigger agent conversations through the same Model Context Protocol. This avoids copy-pasting between a browser and the chat app. Source: package.json:30-38.

3. Programmatic Embedding in Larger Agent Runtimes

Other agent frameworks can import @agentchatme/mcp as a library, instantiate the exported server class, and attach their own transport. This is useful when a product wants to ship its own MCP host while still reusing the curated set of AgentChat tools. Source: src/index.ts:1-40.

4. CI and Automation Hooks

Because the server speaks plain JSON-RPC over stdio, it can be driven from shell scripts, CI pipelines, or short-lived Node processes to send structured prompts to agents as part of automated workflows such as code review bots or release-note generators. Source: package.json:8-14.

Getting Started Summary

To run the server locally, a user typically installs the package, points their MCP host at the bin entry declared in package.json, and supplies any required credentials through environment variables that the entry script forwards. Source: package.json:30-38. Development proceeds by editing the TypeScript sources under src/, rebuilding with the standard tsc configuration, and iterating against a local MCP host. Source: tsconfig.json:1-30.

Boundaries and Non-Goals

The package deliberately does not implement a chat UI, persistence layer, or authentication scheme of its own; those concerns are delegated to the upstream AgentChat service and to the MCP host. It also does not attempt to be a general-purpose agent framework — its role is strictly to be a well-behaved MCP server for the AgentChat ecosystem. Source: README.md:1-40.

Related Pages

Related topics: Project Overview and Use Cases, MCP Tools Reference, Deployment, Configuration, and Operations

System Architecture and Code Organization

Overview and Scope

The agentchat-mcp project implements a Model Context Protocol (MCP) server and client pair designed to coordinate agent-to-agent communication over the protocol. The repository is organized as a TypeScript codebase under src/, where each module has a single, well-scoped responsibility: transport, identity, error mapping, configuration, logging, and the symmetric server/client pair. The architecture favors small, composable units that can be tested and replaced independently, with shared infrastructure (errors, env, log) consumed by both server.ts and client.ts Source: src/server.ts:1-30, src/client.ts:1-30.

The high-level role of the system is to expose MCP-compatible endpoints that allow agents to negotiate context, exchange structured messages, and authenticate peers via a stable identity abstraction. Because MCP itself is transport-agnostic, the project keeps transport concerns narrow and delegates higher-level policy (retry, logging, environment overrides) to dedicated helpers.

Module Layout and Responsibilities

The codebase follows a flat src/ layout. Each file owns one concern, which keeps the dependency graph shallow and makes the boundary between protocol logic and supporting utilities explicit.

The supporting modules (errors.ts, env.ts, log.ts) are intentionally stateless and side-effect-free at import time, which lets the server and client bootstrap them lazily once a session begins Source: src/env.ts:1-40, src/log.ts:1-25.

Core Component Interactions

The server and client share a symmetrical design: both accept a configuration object derived from env.ts, attach a logger from log.ts, and route failures through errors.ts. Identity is handled separately so that the protocol layer never directly touches key material — instead, it delegates to client-identity.ts which exposes a narrow API (sign, verify, identifier) Source: src/client-identity.ts:1-50.

A simplified data flow between modules looks like this:

flowchart LR
    Env[env.ts] --> Server[server.ts]
    Env --> Client[client.ts]
    Log[log.ts] --> Server
    Log --> Client
    Errors[errors.ts] --> Server
    Errors --> Client
    Identity[client-identity.ts] --> Client
    Identity --> Server

The arrows above reflect import direction, not runtime calls: utility modules are leaves, while server.ts and client.ts are the only orchestration roots. This means adding a new transport (for example, switching from stdio to HTTP) only requires editing the orchestration layer; identity, errors, env, and log remain untouched Source: src/server.ts:30-80, src/client.ts:30-80.

Cross-Cutting Concerns

Three concerns cut across both the server and the client and are factored out for that reason:

• Configuration. env.ts reads and validates environment variables once, exposing a typed configuration object. The server and client consume this object instead of touching process.env directly, which prevents divergent defaults and centralizes documentation of supported keys Source: src/env.ts:20-60.
• Logging. log.ts provides a single logger factory used everywhere in the project. Routing all log lines through one module makes it trivial to swap implementations (for example, to a structured JSON logger) without touching call sites Source: src/log.ts:10-40.
• Error handling. errors.ts defines protocol-specific error types and helpers that translate low-level exceptions into MCP-shaped error responses. By isolating this translation, the server and client handlers stay focused on happy-path logic Source: src/errors.ts:1-50.

Identity is a fourth concern, but unlike the three above it is asymmetric: only the client produces identity material, while the server verifies it. The split is enforced by placing identity in its own module (client-identity.ts) and importing it on both sides, so the server's verification path and the client's signing path share the same canonical implementation Source: src/client-identity.ts:30-90.

Extension Points and Design Boundaries

The architecture is deliberately modular to support three categories of extension without changing protocol code:

1. New transports. Because server.ts and client.ts only deal with MCP semantics, swapping the underlying transport (stdio, WebSocket, HTTP) is localized to those files.
2. New identity schemes. Adding a new signature algorithm or key format is contained within client-identity.ts; the rest of the system only depends on its abstract API.
3. New configuration sources. Replacing environment variables with a config file or remote config server only affects env.ts, since downstream modules import the typed object rather than the source.

Each extension point therefore respects the dependency direction shown in the diagram: utility leaves change independently, and the orchestration roots absorb the variation. This keeps refactors safe and reviewable, and it makes the repository approachable for new contributors who only need to understand one file at a time Source: src/server.ts:1-120, src/client.ts:1-120, src/errors.ts:1-80, src/env.ts:1-80, src/log.ts:1-60, src/client-identity.ts:1-120.

Related Pages

Related topics: Project Overview and Use Cases, System Architecture and Code Organization

MCP Tools Reference

Purpose and Scope

The src/tools/ module defines the public surface of the agentchat MCP server: the set of callable tools an MCP-compatible client (such as a Claude-based agent) can invoke to interact with agentchat inboxes and conversations. Each tool is a self-contained module that exports a name, description, JSON Schema for its inputs, and an async handler. Together they form the contract between the agent runtime and the agentchat backend.

The module is intentionally narrow: it does not implement transport, authentication, or session management. Those concerns live in other parts of the repository. The tools module only describes *what* each operation does and *how* it is dispatched. Source: src/tools/index.ts:1-30

Module Architecture

The tools layer follows a small, consistent pattern across every file. A shared AgentChatTool type enumerates the common shape every tool must satisfy, and a generic handler factory wires that descriptor to an executor. Individual tool files then implement the three pieces (name, input schema, handler) and are aggregated into a single allTools array that the server registers at startup.

Source: src/tools/index.ts:1-50, src/tools/_types.ts:1-40, src/tools/_handler.ts:1-60

Tool Catalog

Three tools are currently exposed by the registry:

• send-message — Posts a new message into an agentchat conversation, addressed to one or more recipients. Accepts the conversation identifier, a text body, and optional attachment metadata. Returns the created message identifier and timestamp. Source: src/tools/send-message.ts:1-45
• list-inbox — Returns the recent messages addressed to the authenticated agent, optionally filtered by unread status, conversation, or time window. Output is a paginated array of inbox entries. Source: src/tools/list-inbox.ts:1-50
• get-conversation — Retrieves the full transcript (or a window of it) for a single conversation, including participant identifiers and message order. Source: src/tools/get-conversation.ts:1-45

Each tool file follows the same skeleton: export a name constant, an inputSchema JSON Schema object, and a handler async function. The handler is the only place where business logic differs; everything else is structural and reusable. Source: src/tools/send-message.ts:10-40, src/tools/list-inbox.ts:8-42, src/tools/get-conversation.ts:8-40

Request Lifecycle

When a client invokes a tool, the server routes the call through createHandler in _handler.ts, which:

1. Validates the input against the tool's inputSchema and rejects malformed payloads with a structured error.
2. Resolves a ToolContext (carrying the request id and agent identity) from the surrounding MCP request.
3. Invokes the tool's handler(context, input) and awaits its result.
4. Wraps the return value in the standard MCP result envelope so the client receives a consistent response shape regardless of which tool produced it.

flowchart LR
    A[MCP Client] -->|tool call| B[server dispatcher]
    B --> C[_handler.ts<br/>createHandler]
    C --> D{validate<br/>inputSchema}
    D -- invalid --> E[error envelope]
    D -- valid --> F[tool.handler]
    F --> G[send-message /<br/>list-inbox /<br/>get-conversation]
    G --> H[result envelope]
    H --> A

Source: src/tools/_handler.ts:10-55, src/tools/_types.ts:15-35

Adding or Modifying Tools

To expose a new operation, create a file under src/tools/ exporting the standard descriptor and append it to the allTools array in index.ts. The shared types in _types.ts make sure every entry is structurally compatible, and the generic dispatcher in _handler.ts requires no changes. This convention keeps the surface easy to audit: a reviewer can confirm the entire public API by reading one short file plus the per-tool implementations. Source: src/tools/index.ts:5-30, src/tools/_types.ts:1-25, src/tools/_handler.ts:1-30

Related Pages

Related topics: Project Overview and Use Cases, System Architecture and Code Organization

Deployment, Configuration, and Operations

The agentchat-mcp project ships a Model Context Protocol (MCP) server that lets MCP-aware agents interact with AgentChat services. Deployment, configuration, and operations are the concerns that determine *how* that server is installed, *how* it is parameterized for a given environment, and *how* it behaves at runtime when communicating with peers, resolving identity, and surfacing errors.

1. Project Layout and Build Surface

The repository is a Node.js / TypeScript package. Its public build surface is defined by package.json, which exposes the entry points, dependencies, and the script set used for development, building, and publishing the MCP server.

Typical operational scripts (build, start, dev, prepare) live alongside the package metadata so that a deployer can install, compile, and launch the server with conventional npm commands. The main / bin entries in package.json point at the compiled entry that boots the MCP transport layer.

Source: package.json:1-40

2. Environment Configuration

Runtime configuration is centralized in src/env.ts. This module is responsible for:

• Reading environment variables that control endpoints, credentials, transport selection, and feature flags.
• Validating that required variables are present and well-formed before the server starts.
• Exposing a single, typed configuration object to the rest of the application, so downstream modules (client.ts, client-identity.ts) do not read process.env directly.

The separation between raw environment access (in env.ts) and consumers (in client.ts) keeps deployment concerns isolated: an operator can change behavior by setting variables without touching application code, and the validation in env.ts fails fast with a clear error if the deployment is misconfigured.

Source: src/env.ts:1-60

Configuration Domains

Source: src/env.ts:10-55

3. Client Identity and Connection Lifecycle

When the server starts, it must present itself to AgentChat and persist a stable identity across restarts. src/client-identity.ts encapsulates this concern: it loads or generates a client identifier, persists it locally (so reconnects after restart keep the same identity), and hands it to the client.

src/client.ts then uses that identity to authenticate against AgentChat, open the MCP-side session, and forward tool calls and resources between the MCP transport and the AgentChat backend. The client module is the operational boundary where configuration (env.ts) and identity (client-identity.ts) meet.

Source: src/client.ts:1-80 Source: src/client-identity.ts:1-60

4. Error Handling and Operational Signals

Robust deployment requires that failures are observable and recoverable. src/errors.ts defines the typed error hierarchy used across the server, including categories for configuration errors (thrown by env.ts), identity errors (thrown by client-identity.ts), and transport / API errors (thrown by client.ts).

Centralizing errors has two operational benefits:

1. The MCP transport can map them to consistent JSON-RPC error codes, so MCP clients receive structured, actionable responses rather than raw stack traces.
2. Operators tailing logs can distinguish between *deployment* errors (misconfiguration), *identity* errors (stale or missing client), and *runtime* errors (upstream AgentChat failures), which makes incident triage faster.

Source: src/errors.ts:1-50

5. Deployment Workflow

A typical deployment follows this sequence:

1. Install — npm install resolves dependencies declared in package.json.
2. Build — npm run build compiles TypeScript sources (including env.ts, client.ts, client-identity.ts, errors.ts) into the distributable entry.
3. Configure — Set the environment variables documented in src/env.ts for the target environment (dev, staging, production).
4. Launch — npm start boots the MCP server. On startup, env.ts validates configuration, client-identity.ts loads or creates the client identity, and client.ts opens the upstream connection.
5. Operate — Errors flow through errors.ts into structured logs; the MCP transport remains available for connected agents until shutdown.

Source: README.md:1-80 Source: package.json:1-40 Source: src/env.ts:1-60 Source: src/client-identity.ts:1-60 Source: src/client.ts:1-80 Source: src/errors.ts:1-50

Operators integrating agentchat-mcp into a host (Claude Desktop, an MCP-aware agent runner, or a container platform) should treat env.ts as the authoritative source of supported configuration, client-identity.ts as the owner of long-lived credentials, and errors.ts as the contract for failure reporting. Together, these modules define the complete deployment, configuration, and operations surface of the server.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/agentchatme/agentchat-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/agentchatme/agentchat-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/agentchatme/agentchat-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/agentchatme/agentchat-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agentchat-mcp with real data or production workflows.

• Configuration risk requires verification - GitHub / issue