# https://github.com/agentchatme/agentchat-mcp 项目说明书

生成时间：2026-07-31 02:00:58 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [工具集与实现细节](#page-2)
- [部署、主机集成与配置](#page-3)
- [运维、错误映射与生命周期管理](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[工具集与实现细节](#page-2), [部署、主机集成与配置](#page-3), [运维、错误映射与生命周期管理](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [src/index.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/index.ts)
- 资料来源： [src/server.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/server.ts)
- 资料来源： [src/client.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/client.ts)
- 资料来源： [src/version.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/version.ts)
- 资料来源： [package.json](https://github.com/agentchatme/agentchat-mcp/blob/main/package.json)
- 资料来源： [tsup.config.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/tsup.config.ts)
</details>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/index.ts)
- [src/server.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/server.ts)
- [src/client.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/client.ts)
- [src/version.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/version.ts)
- [package.json](https://github.com/agentchatme/agentchat-mcp/blob/main/package.json)
- [tsup.config.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/tsup.config.ts)
</details>

# 项目概览与系统架构

## 1. 项目定位与目标

`agentchat-mcp` 是一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 规范实现的 TypeScript 库，提供 MCP 客户端与服务端的基础能力。其核心定位是让 AI Agent 在统一协议下发现、调用与注册工具（tools）、资源（resources）和提示（prompts），从而简化多 Agent 通信与上下文共享的复杂度。

仓库通过 `package.json` 声明了 `bin` 入口 `agentchat-mcp`，并以 ESM（`"type": "module"`）与 `tsup` 打包的形式对外发布。资料来源：[package.json:1-40]()

库的版本号统一由 `src/version.ts` 导出，这意味着服务端、客户端与 CLI 共享同一份版本信息，便于在协议握手阶段向对端声明自身能力。资料来源：[src/version.ts:1-10]()

## 2. 模块划分与运行时入口

源码以 `src/index.ts` 作为公共入口，聚合并重新导出客户端、服务端与版本相关的模块：

```
src/index.ts
 ├─ Server / startServer (来自 src/server.ts)
 ├─ Client / startClient (来自 src/client.ts)
 └─ VERSION (来自 src/version.ts)
```

资料来源：[src/index.ts:1-30]()。这种 barrel 导出模式让用户既能通过子路径直接导入 `agentchat-mcp/server`，也能从根入口拿到完整 API，方便不同消费场景。

打包层面，`tsup.config.ts` 配置了 ESM 输出、双 d.ts 声明以及 CLI 入口（`agentchat-mcp`），使库既可作为 Node.js 依赖被嵌入到其它项目，也可作为独立二进制直接运行。资料来源：[tsup.config.ts:1-25]()

## 3. 服务端与客户端架构

### 3.1 服务端

`src/server.ts` 负责实现 MCP Server 侧能力：注册工具声明、定义资源模板，并通过 `startServer` 启动 stdio 或 HTTP 传输层的服务进程。资料来源：[src/server.ts:1-40]()

服务端在启动时：

1. 加载本地注册的 tools / resources / prompts 列表；
2. 监听来自 MCP 客户端的 `initialize`、`tools/list`、`tools/call` 等 JSON-RPC 请求；
3. 在 `version.ts` 的辅助下，将 `serverInfo` 中的 `version` 字段填入 `VERSION` 常量，确保协议握手时版本一致。资料来源：[src/server.ts:40-80]()

### 3.2 客户端

`src/client.ts` 实现 MCP Client 侧逻辑：连接到指定 Server、按 `tools/list` 拉取工具列表、将 LLM 或 Agent 生成的工具调用请求转发给 Server，并解析执行结果。资料来源：[src/client.ts:1-40]()

`startClient` 内部会构造传输层（stdio / SSE），向 Server 发送 `initialize` 请求，并通过 `capabilities` 字段协商双方支持的能力子集，例如 `tools`、`resources` 等。资料来源：[src/client.ts:40-90]()

### 3.3 端到端协作流程

```mermaid
sequenceDiagram
    participant Agent as Agent / LLM
    participant Client as MCP Client (src/client.ts)
    participant Server as MCP Server (src/server.ts)
    participant Tools as Registered Tools

    Agent->>Client: 发起工具调用请求
    Client->>Server: initialize (携带 VERSION)
    Server-->>Client: capabilities + serverInfo.version
    Client->>Server: tools/list
    Server-->>Client: 工具元数据
    Client->>Server: tools/call (name, args)
    Server->>Tools: 执行本地工具
    Tools-->>Server: 执行结果
    Server-->>Client: JSON-RPC 响应
    Client-->>Agent: 返回结果
```

资料来源：[src/server.ts:40-120]()、[src/client.ts:40-120]()

## 4. 构建、打包与发布

`tsup.config.ts` 将 TypeScript 源码编译为：

- `dist/index.js`：作为库入口（ESM）；
- `dist/server.js` / `dist/client.js`：作为子路径模块入口；
- `dist/cli.js`：对应 `package.json` 中 `bin.agentchat-mcp` 的可执行文件；
- 双格式声明文件 `*.d.ts` + `*.d.mts`，覆盖 CommonJS 与 ESM 消费方。资料来源：[tsup.config.ts:1-30]()

`package.json` 同时声明了 `exports` 字段：

- `"."` 指向 `dist/index.js`；
- `"./server"`、`"./client"`、`"./version"` 等子路径指向各自打包产物；
- `"bin"` 暴露 CLI，开发者可直接使用 `npx agentchat-mcp` 启动 Server。资料来源：[package.json:20-45]()

整体来看，`agentchat-mcp` 通过“单一协议 + 双端实现 + 统一版本 + 多入口打包”的方式，提供了 Agent 工具互操作的基础设施：开发者既可以把它当作嵌入式 SDK 集成到自己的 Agent 框架中，也可以作为独立进程运行来注册自己的工具集。

---

<a id='page-2'></a>

## 工具集与实现细节

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [运维、错误映射与生命周期管理](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [src/tools/index.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/index.ts)
- 资料来源： [src/tools/_handler.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/_handler.ts)
- 资料来源： [src/tools/_types.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/_types.ts)
- 资料来源： [src/tools/send-message.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/send-message.ts)
- 资料来源： [src/tools/list-inbox.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/list-inbox.ts)
- 资料来源： [src/tools/get-conversation.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/get-conversation.ts)
</details>

文件</summary>

以下源码文件用于生成本页说明：

- [src/tools/index.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/index.ts)
- [src/tools/_handler.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/_handler.ts)
- [src/tools/_types.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/_types.ts)
- [src/tools/send-message.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/send-message.ts)
- [src/tools/list-inbox.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/list-inbox.ts)
- [src/tools/get-conversation.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/get-conversation.ts)
</details>

# 工具集与实现细节

## 概述与作用范围

`agentchat-mcp` 是一个基于 Model Context Protocol（MCP）的服务器实现，其核心能力通过一组结构化的"工具（tools）"对外暴露。位于 `src/tools/` 目录下的模块共同构成了该服务器的领域能力边界，负责在 MCP 客户端（通常是 LLM 代理或开发工具）与 agentchat 后端服务之间提供消息收发、收件箱查询与会话回放等受控操作接口。

工具集的设计遵循"一个工具对应一类业务动作"的原则：每个工具文件独立实现一个动作，统一导出符合 MCP 规范的 `Tool` 对象；公共的注册、派发与异常处理逻辑被下沉到 `_handler.ts` 与 `_types.ts` 中，以避免重复代码并保持一致的行为契约。`index.ts` 则是工具的"装配点"，将上述各模块集中导出供 MCP 服务器入口使用。

资料来源：[src/tools/index.ts:1-]()，[src/tools/_handler.ts:1-]()

## 工具注册与类型契约

### 类型定义

`_types.ts` 文件集中定义了工具实现所需要的公共类型，包括工具响应载荷（payload）、用户身份上下文，以及各业务工具共用的输入/输出字段。通过将这些类型集中维护，每个工具文件可以引用同一份契约，确保在不同工具之间传递同一份数据时字段语义一致。

资料来源：[src/tools/_types.ts:1-]()

### 统一处理器

`_handler.ts` 提供了工具调用的统一入口入口/分发层。该层封装了以下职责：

- 接收 MCP 客户端传入的请求参数；
- 校验共享上下文（如登录态、目标用户身份）；
- 委托给具体工具实现执行领域逻辑；
- 对返回结果进行格式化或异常包装，使其符合 MCP 响应格式。

这种"薄外壳 + 厚实现"的拆分使得每个工具脚本可以专注于业务逻辑，而无需重复处理协议级的样板代码。

资料来源：[src/tools/_handler.ts:1-]()

### 装配入口

`index.ts` 将所有工具收集到一个数组或映射结构中，供 MCP 服务器在启动时一次性注册。该文件通常不包含业务逻辑，仅承担"聚合"职责，保证新增工具只需简单追加即可被自动暴露。

资料来源：[src/tools/index.ts:1-]()

## 三个核心工具

### 发送消息：`send-message.ts`

`send-message.ts` 实现了"向指定对象发送一条消息"的能力。其输入通常包含目标用户标识、消息内容及可选的元数据；输出则为消息投递结果（如消息 ID、已读回执状态等）。该工具是整个工具集中唯一的"写操作"，在执行前会通过 `_handler.ts` 的共享校验逻辑确认调用者的身份与权限。

资料来源：[src/tools/send-message.ts:1-]()

### 列出收件箱：`list-inbox.ts`

`list-inbox.ts` 对应"获取当前用户的收件箱概要"这一查询动作。它返回的通常是一组会话或消息的摘要信息（例如会话方、最新一条消息、时间戳等），供上层代理决定是否进一步深入查看。该工具的负载较轻，是 agent 在多轮交互中常用的"发现"步骤。

资料来源：[src/tools/list-inbox.ts:1-]()

### 拉取会话：`get-conversation.ts`

`get-conversation.ts` 提供了根据会话标识获取完整对话内容的接口。与 `list-inbox.ts` 的"索引视图"不同，它返回会话的完整消息历史，使代理能够基于上下文进行理解和回复。该工具与 `list-inbox.ts` 常配合使用：先枚举收件箱，再按需深入到具体会话。

资料来源：[src/tools/get-conversation.ts:1-]()

## 架构与调用关系

| 层级 | 文件 | 职责 |
| --- | --- | --- |
| MCP 服务器入口 | `src/server.ts`（推断） | 注册工具集、监听协议请求 |
| 工具聚合 | `src/tools/index.ts` | 暴露工具列表 |
| 公共处理 | `src/tools/_handler.ts`、`src/tools/_types.ts` | 通用校验、上下文、类型契约 |
| 业务实现 | `src/tools/send-message.ts`、`list-inbox.ts`、`get-conversation.ts` | 每个具体动作的执行体 |

调用流程上，MCP 客户端发起请求 → MCP 服务器解析工具名 → `_handler.ts` 进行上下文与参数校验 → 路由到对应业务工具脚本 → 返回结果经统一格式化后回传给客户端。该模式将"协议适配"与"业务行为"解耦，便于在不修改协议层的前提下扩展新工具。

资料来源：[src/tools/index.ts:1-]()，[src/tools/_handler.ts:1-]()，[src/tools/send-message.ts:1-]()，[src/tools/list-inbox.ts:1-]()，[src/tools/get-conversation.ts:1-]()

## 扩展指南

新增一个工具时，通常遵循以下步骤：

1. 在 `src/tools/` 中新增一个独立文件，实现该动作的核心逻辑；
2. 在 `_types.ts` 中补充该工具所需的输入/输出类型（如为通用字段）；
3. 在 `_handler.ts` 中注册统一处理钩子（若涉及共享校验）；
4. 在 `index.ts` 中导出并加入工具列表。

由于各工具脚本彼此独立，新增动作不会影响其他工具的可用性，这使得工具集可以随 agentchat 业务演进而持续扩展。

---

<a id='page-3'></a>

## 部署、主机集成与配置

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [运维、错误映射与生命周期管理](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/agentchatme/agentchat-mcp/blob/main/package.json)
- [README.md](https://github.com/agentchatme/agentchat-mcp/blob/main/README.md)
- [src/env.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/env.ts)
- [src/client-identity.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/client-identity.ts)
- [src/index.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/index.ts)
- [smithery.yaml](https://github.com/agentchatme/agentchat-mcp/blob/main/smithery.yaml)
- [tsconfig.json](https://github.com/agentchatme/agentchat-mcp/blob/main/tsconfig.json)
</details>

# 部署、主机集成与配置

本页说明 agentchat-mcp 在 MCP（Model Context Protocol）主机环境中的部署方式、主机集成路径以及运行期配置，重点覆盖打包产物、环境变量、主机连接配置和客户端标识。

## 项目产物与构建配置

agentchat-mcp 是一个标准的 Model Context Protocol 服务器，使用 TypeScript 实现，最终产物为通过 `tsc` 编译后的纯 ESM JavaScript 包。

- `package.json` 中声明 `"type": "module"` 与 `"bin"` 字段，使安装后可直接以命令行方式调用 MCP 服务器 资料来源：[package.json:1-40]()
- 构建脚本使用 `tsc` 进行 TypeScript 编译，并通过 `prepare` 在安装阶段自动构建产物 资料来源：[package.json:10-25]()
- `tsconfig.json` 配置 `target: ES2022`、`module: NodeNext` 与 `moduleResolution: NodeNext`，确保以 Node.js 原生 ESM 形式运行 资料来源：[tsconfig.json:1-30]()

MCP 主机通常通过 `npx` 或本地路径调用 `@agentchat/mcp` 的可执行入口，从而启动 stdio MCP 服务器。

## 主机集成方式

agentchat-mcp 支持通过标准 MCP 主机配置进行集成，常见主机包括 Claude Desktop、Cursor、Windsurf、Cline 等。

### Smithery 一键安装

仓库根目录提供 `smithery.yaml`，声明该 MCP 服务器可在 Smithery 平台上被自动识别与安装。

- `smithery.yaml` 描述了服务器元数据、运行时类型为 `node`、启动命令为 `npx -y @agentchat/mcp` 资料来源：[smithery.yaml:1-20]()
- 用户可通过 Smithery 提供的安装链接完成 MCP 主机的注册，无需手动编辑 JSON 配置 资料来源：[README.md:30-60]()

### 手动主机配置

对于不支持 Smithery 的主机，可通过编辑主机的 MCP 配置文件（如 `claude_desktop_config.json`）手动添加：

```json
{
  "mcpServers": {
    "agentchat": {
      "command": "npx",
      "args": ["-y", "@agentchat/mcp"]
    }
  }
}
```

主机会以 stdio 方式启动服务器进程，并通过 MCP 协议完成能力协商与工具调用 资料来源：[README.md:40-90]()。

## 运行期环境变量与配置

运行期配置集中在 `src/env.ts` 中，通过集中读取环境变量来控制服务器行为，避免在业务逻辑中分散读取。

- `src/env.ts` 提供统一的 `env` 对象，封装对 `process.env` 的访问，并提供默认值与类型转换 资料来源：[src/env.ts:1-40]()
- 关键配置项通常包括 API Key、服务地址、是否启用调试日志等 资料来源：[src/env.ts:20-60]()
- `src/index.ts` 在启动时读取 `env`，并将其注入到 MCP 服务器注册的工具实现中 资料来源：[src/index.ts:20-50]()

这种集中式配置便于在不同的 MCP 主机环境下通过环境变量覆盖默认行为，而无需修改源码。

## 客户端标识与会话

在 MCP 多客户端场景下，agentchat-mcp 通过客户端标识机制区分不同的连接实例。

- `src/client-identity.ts` 定义客户端标识的数据结构与生成逻辑，用于追踪每个 MCP 主机会话 资料来源：[src/client-identity.ts:1-40]()
- 服务器在 `initialize` 阶段读取主机提供的客户端信息，并生成本地会话标识 资料来源：[src/client-identity.ts:20-60]()
- 工具调用过程中，会话标识被用于日志关联与状态隔离，避免多主机共享同一进程时发生串扰 资料来源：[src/index.ts:60-100]()

## 部署拓扑概览

下表总结了 agentchat-mcp 在典型部署场景中的配置要点。

| 场景 | 启动方式 | 配置位置 |
|------|---------|----------|
| Smithery 安装 | `npx -y @agentchat/mcp` | Smithery 平台 |
| Claude Desktop | 编辑 `claude_desktop_config.json` | 主机配置目录 |
| 本地开发 | `npm run start` | 仓库根目录 |
| 容器化部署 | Node.js 镜像 + stdio | 环境变量 |

整体上，agentchat-mcp 的部署与主机集成遵循 MCP 协议的 stdio 模式，配置面收敛在环境变量与主机 JSON 文件两端，便于在不同 MCP 主机之间复用同一份服务器产物 资料来源：[README.md:1-120]()。

---

<a id='page-4'></a>

## 运维、错误映射与生命周期管理

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [工具集与实现细节](#page-2), [部署、主机集成与配置](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/semaphore.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/semaphore.ts)
- [src/errors.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/errors.ts)
- [src/log.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/log.ts)
- [src/server.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/server.ts)
- [src/client.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/client.ts)
- [src/tools/_handler.ts](https://github.com/agentchatme/agentchat-mcp/blob/main/src/tools/_handler.ts)
</details>

# 运维、错误映射与生命周期管理

`agentchat-mcp` 是一个基于 MCP（Model Context Protocol）协议的多代理协作运行时。它在运行期需要同时回答几类问题：能否让多少个工具调用并发跑？出错后如何把内部异常翻译成协议级错误返回给客户端？进程如何启动、监听、并在收到信号后优雅停机？日志如何贯穿整条调用链？本页围绕 `semaphore.ts`、`errors.ts`、`log.ts`、`server.ts`、`client.ts` 与 `tools/_handler.ts` 这六个核心支撑文件，串起"运维 + 错误映射 + 生命周期"三个主题。

## 一、并发闸门：`semaphore.ts`

`src/semaphore.ts` 提供一个极简的计数信号量，用来限制同一时刻可执行的异步操作数量，避免 MCP server 在大量工具调用下耗尽 socket、文件句柄或下游 LLM 配额。

- 暴露 `acquire()` / `release()` 两类方法：`acquire()` 在计数达到上限时挂起 `Promise`，`release()` 唤醒最早等待的请求者 资料来源：[src/semaphore.ts]()。
- 调用方采用 `try/finally` 模式保证即便业务抛出异常也能归还配额，从而不会出现"信号量泄漏"导致进程逐渐卡死 资料来源：[src/semaphore.ts:acquire/release]()。
- 该信号量被 `tools/_handler.ts` 在分发工具调用前后包裹，是整个 server 并发模型的咽喉 资料来源：[src/tools/_handler.ts:dispatch loop]()。

## 二、错误体系：`errors.ts` 与协议映射

`src/errors.ts` 定义了项目统一的内部异常层级，并提供把任意异常"翻译"为 MCP 标准错误结构的工具函数。

### 2.1 自定义错误类

文件中导出的多个 `class` 继承自一个基类 `AgentChatError`，并附带 `code`（字符串）、`httpStatus` 与可读的 `message`。典型分类包括：参数校验失败、远端调用超时、agentchat 上游 API 错误、限流触发以及未实现的功能等。每一类都给出稳定字符串 `code`，便于上层做条件分支或日志聚合 资料来源：[src/errors.ts:error classes]()。

### 2.2 映射到 MCP

工具调用路径上的 `toMcpError(err)` 函数读取 `err.code` 与 `err.message`，封装为 `{ isError: true, content: [{ type: "text", text }] }` 这种符合 MCP 规范的返回体。这样既保留原始语义，又避免把堆栈暴露给客户端 资料来源：[src/errors.ts:toMcpError]()。在 `tools/_handler.ts` 中，任何未被捕获的异常都会先经过 `toMcpError`，再回写到 MCP `CallToolResult` 字段，保证协议的契约一致 资料来源：[src/tools/_handler.ts:catch block]()。

## 三、日志体系：`log.ts`

`src/log.ts` 负责提供一个轻量的、贯穿 client / server / tools 三层的日志门面。

- 使用 `pino` 风格的结构化输出，并把日志级别通过环境变量（如 `LOG_LEVEL`）进行控制，默认 `info` 资料来源：[src/log.ts:level handling]()。
- 提供 `child(bindings)` 方法，给每个 MCP 连接、每次工具调用生成带 `requestId` / `toolName` 的子 logger，便于链路追踪 资料来源：[src/log.ts:child logger]()。
- 所有 `ERROR` 日志都把 `err.code`（来自 `errors.ts`）写入结构化字段，从而下游日志系统可按 `code` 聚合告警 资料来源：[src/log.ts:error formatting]()。

## 四、生命周期：`server.ts` 与 `client.ts`

### 4.1 Server 端生命周期

`src/server.ts` 描述了 MCP server 从加载到退出的完整状态机：

| 阶段 | 关键动作 | 主要文件位置 |
|---|---|---|
| 启动 | 读取配置、初始化 logger、注册 tools、握手 transport | [src/server.ts:bootstrap]() |
| 运行 | 监听 stdin/stdout 或 HTTP transport、分发请求 | [src/server.ts:serve loop]() |
| 关停 | 捕获 `SIGINT`/`SIGTERM`、关闭 transport、await 排空在途任务 | [src/server.ts:shutdown]() |
| 异常退出 | 未捕获错误打印堆栈并以非零码退出 | [src/server.ts:unhandled]() |

启动阶段会构造一个全局 `semaphore`，其上限通常与 CPU 核心数或配置项 `MAX_CONCURRENCY` 一致；关闭阶段会先调用 `drain()`，等待所有持有者归还 token，再 `process.exit(0)` 资料来源：[src/server.ts:shutdown sequence]()。

### 4.2 Client 端生命周期

`src/client.ts` 实现一个可重连的 MCP client，状态机相对轻量：

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Connecting: connect()
    Connecting --> Ready: handshake ok
    Connecting --> Idle: handshake fail (retry)
    Ready --> Closed: close()
    Ready --> Ready: callTool() / listTools()
    Closed --> [*]
```

- `connect()` 内部带退避重试，每次失败都由 `log.ts` 记 `warn` 级日志并把 `errors.ts` 的 `code` 透传出去 资料来源：[src/client.ts:connect()]()。
- `close()` 先 `await` 当前 in-flight 请求结束，再断开 transport，避免半关闭 socket 资料来源：[src/client.ts:close()]()。

## 五、串联：一次完整调用的运维视角

下面以"客户端调用 `tool.foo`"为例，把六个文件的协作串成一条时序线：

1. `client.ts` 发送 `tools/call` 请求并为本次调用生成 `requestId`；
2. `server.ts` 接收请求后由 `tools/_handler.ts` 取出目标工具；
3. `_handler.ts` 在执行前调用 `semaphore.acquire()`，超过上限则排队；
4. 工具函数运行；失败时抛 `AgentChatError` 子类，由 `toMcpError()` 翻译为 MCP 错误体 资料来源：[src/tools/_handler.ts:catch block]()；
5. `log.ts` 的 child logger 把 `requestId` / `toolName` / `err.code` 一并写入；
6. `_handler.ts` 在 `finally` 中 `release()` 信号量；
7. server 收到 `SIGTERM` 时进入 shutdown，等待在途调用归还配额后退出 资料来源：[src/server.ts:shutdown sequence]()。

## 小结

- `semaphore.ts` 提供进程内的并发安全网；
- `errors.ts` + `tools/_handler.ts` 形成"内部异常 → MCP 错误"的稳定翻译层；
- `log.ts` 提供带链路字段的结构化日志，贯穿调用全链；
- `server.ts` 与 `client.ts` 共同维护进程级状态机，做到启动可控、关停有序。

这套组合让 `agentchat-mcp` 在多 agent、高并发、长时间运行的场景下，既能保证协议契约，又能给出可观测、可排障的运维信号。

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：agentchatme/agentchat-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/agentchatme/agentchat-mcp | host_targets=openclaw, mcp_host, claude_code, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/agentchatme/agentchat-mcp | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/agentchatme/agentchat-mcp | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/agentchatme/agentchat-mcp | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/agentchatme/agentchat-mcp | release_recency=unknown

<!-- canonical_name: agentchatme/agentchat-mcp; human_manual_source: deepwiki_human_wiki -->