Claude Agent MCP

克劳德代理MCP服务器

模型上下文协议（MCP）服务器，用于连接 claude-agent-sdk-ts 为Claude Code CLI及其他AI工具提供流式会话功能。

英语 • 中文 • 日语 • 韩语

______________________________________________________________________

概述

Claude Agent MCP 是一个基于 Node.js 的模型上下文协议（MCP）服务器，它起到了桥梁的作用 claude-agent-sdk-ts 库，为Claude Code CLI和其他AI开发工具提供流式对话功能。

特点/功能

• 符合标准的MCP服务器建立在 @modelcontextprotocol/sdk 具备完整的日志记录支持和优雅的关闭处理功能。
• 模块化运行时: src/core/ 这些房屋（或可理解为系统/框架）集成了用于会话存储、消息泵、模式定义和日志辅助功能的专用模块。
• 会话工具:

- claude_session_create / claude_session_close - claude_session_list / claude_session_status - claude_direct_query 对于无需手动生命周期管理的一次性提示

• 聊天控制：

- claude_chat_query， claude_chat_interrupt - claude_chat_model， claude_chat_mode - claude_server_config 更新运行时参数（例如，模型更新超时）

• 实时反馈（或流式反馈）消息泵消耗 receiveMessages() 并且发射出结构化的（数据/信号） info， debug，和 error 每MCP规格的记录数。
• 实时反馈（或流式反馈）消息泵消耗 receiveMessages() 并发射出结构化的（数据/信号等） info， debug，以及 error 根据MCP规范的日志。服务器宣告MCP logging 能力，因此客户可以订阅 notifications/message 并且可选地调用 logging/setLevel （例如 client.setLoggingLevel('debug')) 以控制输出的详细程度。

快速入门

安装

npm install --save claude-agent-mcp

运行服务器

# Build TypeScript (pre-built in npm package, optional)
npm run build

# Start the server
npx claude-agent-mcp

# Or run directly with Node
node dist/cli.js

需求设定 ANTHROPIC_API_KEY 设置环境变量并安装 Claude CLI。

集成示例

Claude 命令行接口（CLI）

# 1. Install the package
npm install --save claude-agent-mcp

# 2. Register the MCP server
claude mcp add claude-agent-mcp \
  --command npx \
  --args claude-agent-mcp

# 3. Verify
claude mcp list

Cursor 集成开发环境（IDE）

添加到 ~/.cursor/mcp.config.json：

{
  "servers": [
    {
      "name": "claude-agent-mcp",
      "command": "npx",
      "args": ["claude-agent-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  ]
}

Cline（VS Code 扩展）

通过 VS Code 命令面板：“Cline: 打开设置（JSON）”

{
  "mcp.servers": [
    {
      "name": "claude-agent-mcp",
      "command": "npx",
      "args": ["claude-agent-mcp"],
      "cwd": "${workspaceFolder}"
    }
  ]
}

Codex CLI（注：Codex 通常指某种编译器或代码生成工具，CLI 指命令行界面，所以这里可以翻译为“Codex 命令行界面”或根据具体上下文简化为“Codex CLI 工具”）

在（某处）进行配置 $CODEX_HOME/config.toml：

[mcp_servers.claude-agent-mcp]
command = "npx"
args = ["claude-agent-mcp"]

测试

针对的单元测试验证了模块化运行时，而无需实际运行Claude CLI：

• tests/message-pump.test.ts 练习流式聚合、模型等待者和错误清理。
• tests/session-store.test.ts 涵盖了会话生命周期辅助工具和安全边界。

辅助脚本（例如 scripts/real-integration-test.ts) 假设已完全配置的Claude CLI环境，并保持选择加入状态。

运行测试

npm test

项目结构

├── src/
│   ├── core/
│   │   ├── logger.ts          # Safe logging wrapper
│   │   ├── message-pump.ts    # Streaming message consumer
│   │   ├── schemas.ts         # Shared Zod schemas
│   │   ├── session-store.ts   # In-memory session registry
│   │   └── types.ts           # Shared type definitions
│   ├── server.ts              # Tool registration & runtime wiring
│   └── cli.ts                 # CLI entry point
├── scripts/
│   └── real-integration-test.ts
├── tests/
│   ├── message-pump.test.ts   # Streaming behaviour & cleanup
│   ├── session-store.test.ts  # SessionStore guard rails
│   └── TEST_GUIDE.md          # Test plan and coverage notes
├── jest.config.js
├── package.json
├── tsconfig.json
├── CLAUDE.md
├── AGENTS.md
└── README.md

发展

# Install dependencies
npm install

# Development mode (ts-node)
npm run dev

# Build TypeScript
npm run build

# Run all tests
npm test

# Watch mode for tests
npm run test:watch

# Generate coverage report
npm run test:coverage

# Clean build artifacts
npm run clean

出版

# Update version
npm version patch  # or minor/major

# Build for publication
npm run build

# Publish to npm
npm publish

# Users can then use:
npx claude-agent-mcp              # Auto-download and run
npm install -g claude-agent-mcp   # Global installation

工具参考

claude_session_create

创建一个新的Claude会话，或恢复之前保存的Claude CLI对话。

参数：

• sessionId （可选）：要继续的 Claude CLI 对话 ID（映射到 --resume); 忽略以开始一个新会话
• cwd （可选）：工作目录
• model （可选）：模型名称（opus | sonnet | haiku)
• permissionMode （可选）：权限模式（默认|接受编辑|计划|绕过权限）
• systemPrompt （可选）：自定义系统提示

返回值：

{
  "sessionId": "uuid",
  "model": "model-name",
  "cwd": "working-directory",
  "permissionMode": "default",
  "systemPrompt": "prompt",
  "active": true,
  "createdAt": "timestamp",
  "resumed": false,
  "resumedFrom": null
}

如果 sessionId 当提供（相关信息/参数）时，SDK 会调用 Claude CLI 并 --resume，和 resumed/resumedFrom 反映尝试恢复的情况。

claude_chat_query

向Claude发送提示并接收回复。

参数：

• sessionId （必填）：会话ID
• prompt （必填）：用户提示
• closeAfter （可选）：查询后自动关闭会话
• includeThinking （可选）：包含克劳德的思考过程

返回值：

{
  "finalText": "Claude's response",
  "thinking": ["thinking chunks..."],
  "toolInvocations": [
    {
      "id": "tool-id",
      "name": "tool-name",
      "input": {},
      "output": {},
      "success": true
    }
  ],
  "metadata": {
    "usage": { "input_tokens": 100, "output_tokens": 50 },
    "durationMs": 1500,
    "totalCostUsd": 0.001
  }
}

claude_chat_model

为当前会话切换模型。

参数：

• sessionId （必填）：会话ID
• model （必填）：目标模型（opus | sonnet | haiku)

返回值：

{
  "requestedModel": "requested-model",
  "resolvedModel": "actual-model-used"
}

claude_chat_mode

更改权限模式。

参数：

• sessionId （必需）：会话ID
• permissionMode （必填）：以下选项之一：默认|接受编辑|计划|绕过权限

返回值：

{
  "permissionMode": "new-mode"
}

claude_chat_interrupt

中断当前查询。

参数：

• sessionId （必需）：会话ID

返回值：

{
  "interrupted": true
}

claude_session_close

结束并清理会话。

参数：

• sessionId （必需）：会话ID

返回值：

{
  "sessionId": "session-id",
  "activeSessions": 0
}

建筑

Claude Agent MCP 采用了一种简洁、模块化的架构：

1. MCP服务器层 (server.ts): 使用（某种技术或方法）实现MCP协议 @modelcontextprotocol/sdk
2. 会话管理维护会话状态并管理生命周期
3. 消息流处理与Claude CLI的双向通信
4. 错误处理全面的错误处理和日志记录

如需详细的架构信息，请参阅 CLAUDE.md（文件名，可译为“克劳德文档”或保持原样，具体取决于上下文和使用场景）。

文档

• CLAUDE.md（可译为“克劳德文档”或根据具体上下文调整，如“关于克劳德的文档”等） - 架构和设计决策
• tests/TEST_GUIDE.md 翻译为中文是：tests/测试指南.md - 完整的测试指南，包含83+个示例
• \AGENTS.md\ 翻译为中文是：“代理列表/说明文件.md” - 人工智能合作公约与指南

可用语言

此README文件提供多种语言版本：

许可证

麻省理工学院（MIT）

做出贡献

我们欢迎投稿！请确保：

• 所有测试均通过： npm test
• 代码构建无错误： npm run build
• 文档已更新

支持

如果您遇到任何问题，请：

1. 检查一下 TEST_GUIDE.md 翻译为中文是：“测试指南.md” 用于故障排除
2. 审查/回顾 CLAUDE.md（文件名，可译为“克劳德.md”或保持原样，具体取决于上下文是否需要翻译文件名） 对于建筑细节
3. 提交一个问题，并提供有关您问题的详细信息

______________________________________________________________________

最后更新时间2025年10月24日

版本1.3.0