Claude Agent SDK MCP 服务端扩展

关键词

Claude工具执行扩展AI SDK流式输出

使用说明

项目简介

  • 该仓库实现了一个在宿主应用中内置的 MCP 服务器扩展，名为 custom-tools。通过 Claude Agent SDK 将 pi 的工具暴露给 Claude Code 等 MCP 客户端，使得 LLM 客户端可以请求执行工具、读取/写入资源、以及获取自定义工具的能力。工具执行在 pi 端完成，Claude Code 端仅负责请求与展示，工具执行权限在客户端被明确拒绝以确保安全。

主要功能点

  • 内置 MCP 服务器：在进程内以名为 custom-tools 的 MCP 服务器暴露工具集合。
  • 工具映射：将 Claude Code 请求的工具名称映射到 pi 的实际工具实现（内置工具如 Read、Write、Edit、Bash、Grep、Glob，以及自定义工具）。
  • 自定义工具支持：可以通过 in-process MCP 服务器暴露额外工具，支持输入/输出描述。
  • 流式对话支持：通过流式接口将 LLM 的内容块、工具调用和结果分段推送给客户端。
  • 安全策略：在 Claude Code 端禁止工具执行，实际执行由 pi 侧完成。
  • 配置与上下文拼接：支持将系统提示、技能、代理信息等拼接到 Claude Code 的系统提示中，且可通过全局/项目设置进行控制。
  • MCP 配置控制：在需要时可通过设置指定清单来禁用 MCP 自动加载等行为，减少 token 开销。

安装步骤

  • 通过 pi 全局扩展安装（npm 作为主要来源）：
    • pi install npm:claude-agent-sdk-pi@latest
  • 认证方式（任选其一）：
    • 使用 Claude Code 登录（Pro/Max）：npx @anthropic-ai/claude-code
    • 使用 API Key：导出 ANTHROPIC_API_KEY=your_key
  • 重新加载 pi：
    • /reload

服务器配置（MCP 客户端需要的连接信息）

说明：该 MCP 服务器在本扩展中是内嵌在宿主应用中的，不依赖外部独立进程启动。因此 MCP 客户端无需启动外部服务器进程，而是通过插件/扩展在宿主应用中连接和使用。

  • serverName（服务器名称）: custom-tools
  • command（启动命令）: null
  • args（启动参数）: []

注释说明：

  • serverName 对应代码中定义的 MCP 服务器名称，用于客户端识别要连接的服务器。
  • 由于该 MCP 服务器是“在进程内加载”的扩展，不需要外部进程启动，因此 command 与 args 为空或 null，表示“就地加载”的嵌入式服务器。
  • 客户端连接该 MCP 服务器时，可以配置要使用的工具集合（由代码中 mapping 和自定义工具决定），不需要再启动外部服务。

基本使用方法

  1. 确认扩展已安装并在 pi 中正确注册（CLAUDE 提供方：claude-agent-sdk）。
  2. 选择 Claude Code 作为 LLM 客户端，或使用 API Key 对接 Claude Agent。
  3. 在对话中发送带有工具调用的上下文，系统将由 pi 端执行自定义工具并将结果通过 MCP 流式返回给客户端。
  4. 如需自定义工具，按照代码中定义的 in-process MCP 服务器进行注册与映射；工具调用将以标准化的格式返回工具结果，用户可在对话中看到 TOOL RESULT 的输出。

重要注意

  • 本实现通过 Claude Agent SDK 的 MCP 支持实现工具暴露与调用，核心逻辑与协议处理由外部依赖（@anthropic-ai/claude-agent-sdk）提供，仓库提供的是服务器端/扩展端的组合实现。
  • MCP 客户端的实际启动是嵌入在宿主应用中的，无需额外的外部进程。若需在其他环境进行复现实验，请确保在扩展初始化阶段将 custom-tools MCP 服务器加载到 Claude Code 的工具体系中。

服务器信息

访问项目