Universal Tool Calling Protocol (utcp Client)

UTCP-MCP Bridge

你最后需要的 MCP 服务。

一款通用的一体化 MCP 服务，将 Universal Tool Calling Protocol（UTCP）的全部能力带入 MCP 生态系统。

🚀 快速开始

将此配置添加到你的 MCP 客户端（Claude Desktop 等）：

{
  "mcpServers": {
    "utcp": {
      "command": "npx",
      "args": ["@utcp/mcp-bridge"],
      "env": {
        "UTCP_CONFIG_FILE": "/path/to/your/.utcp_config.json"
      }
    }
  }
}

就这么简单！ 无需安装。Bridge 将自动：

• 通过 npx 下载并运行最新版本
• 从指定路径加载你的 UTCP 配置
• 将所有 UTCP 手册注册为 MCP 工具
• 提供统一界面来管理你的工具生态系统

🔧 配置

创建 .utcp_config.json 文件来配置你的工具和服务：

{
    "load_variables_from": [
      {
        "variable_loader_type": "dotenv",
        "env_file_path": ".env"
      }
    ],
    "manual_call_templates": [
      {
          "name": "openlibrary",
          "call_template_type": "http",
          "http_method": "GET", 
          "url": "https://openlibrary.org/static/openapi.json",
          "content_type": "application/json"
      }
    ],
    "post_processing": [
      {
          "tool_post_processor_type": "filter_dict",
          "only_include_keys": ["name", "description"],
          "only_include_tools": ["openlibrary.*"]
      }
    ],
    "tool_repository": {
      "tool_repository_type": "in_memory"
    },
    "tool_search_strategy": {
      "tool_search_strategy_type": "tag_and_description_word_match"
    }
}

Claude Code（CLI）

对于 Claude Code（命令行 / IDE 扩展），将 Bridge 注册为用户范围的 MCP 服务：

claude mcp add-json --scope user utcp '{"type":"stdio","command":"npx","args":["@utcp/mcp-bridge"],"env":{"UTCP_CONFIG_FILE":"/absolute/path/to/.utcp_config.json"}}'

然后重启 Claude Code。使用 claude mcp list 验证。使用 claude mcp remove utcp --scope user 移除。

🧪 针对 Bridge 进行本地开发

如果你正在开发 @utcp/sdk 或任何其他 typescript-utcp 包，并想通过 Claude Code 进行测试，请使用开发脚本：

cd utcp-mcp
npm install
npm run dev:register     # builds typescript-utcp packages, overlays each into the bridge's node_modules, builds the bridge, and registers it as 'utcp-dev' in Claude Code
# restart Claude Code

# After every edit:
npm run dev:register     # rebuilds, re-registers; restart Claude Code

# When done:
npm run dev:unregister   # removes the MCP entry and restores registry node_modules

两个脚本都是幂等的，且不会修改 package.json。覆盖策略避免使用 npm link；在现代 npm 中，unlink 会被别名为 uninstall --save，从而悄无声息地移除该依赖。

脚本预期 typescript-utcp 检出目录位于此仓库旁边（../typescript-utcp）。若不在此处，可使用标志指定：

• --lib-dir <path> — 指定其他 typescript-utcp 检出目录，或传入 none 完全跳过覆盖步骤（仅修改 Bridge 时很有用）
• --name <mcp-name>（默认值为 utcp-dev）— 如果想让开发 Bridge 与已发布版本并存，此选项很有用
• --config <path>（默认值为 ./.utcp_config.json）— 指定其他 UTCP 配置

🛠️ 可用的 MCP 工具

Bridge 提供以下 MCP 工具，用于管理你的 UTCP 生态系统：

• register_manual - 注册新的 UTCP 手册 / API
• deregister_manual - 移除已注册的手册
• call_tool - 执行任意已注册的 UTCP 工具
• search_tools - 按描述查找工具
• list_tools - 列出所有已注册的工具名称
• get_required_keys_for_tool - 获取必需的环境变量
• tool_info - 获取完整的工具信息和架构

📁 什么是 UTCP？

Universal Tool Calling Protocol（UTCP）允许你：

• 连接任意 API：通过 HTTP、OpenAPI 规范或自定义格式
• 使用命令行工具：自动解析参数
• 处理文本和文件：使用内置工具
• 串联和组合：无缝使用多个工具

通过此 MCP Bridge，你的所有 UTCP 工具都可在 Claude Desktop 和其他 MCP 客户端中使用。

🌟 功能

• ✅ 零安装 - 通过 npx 运行
• ✅ 通用兼容性 - 适用于任何 MCP 客户端
• ✅ 动态配置 - 无需重启即可更新工具
• ✅ 环境隔离 - 每个项目都可以有自己的配置
• ✅ 全面的工具管理 - 注册、搜索、调用和检查工具
• ✅ 提供 Web 界面 - 参见 web_ui_utcp_mcp_bridge/

🐍 Python 版本

Python 用户请参阅 python_mcp_bridge/ 中的独立 Python 实现。

🌐 Web 界面

如需通过 Web UI 进行高级管理，请查看 web_ui_utcp_mcp_bridge/。

---