my-cool-proxy

My Cool Proxy

My Cool Proxy 是一个 Model Context Protocol (MCP) 服务网关，旨在解决当前 MCP 面临的许多问题。以下问题不分先后：

• 工具描述会占用大量上下文窗口： 这是大多数 Agent 集成 MCP 时存在的问题。大多数应用会一次性将所有 MCP 工具塞进上下文，而不是实现按需加载工具的抽象机制。为缓解这一问题，My Cool Proxy 将工具封装在 Lua 解释器中，并提供用于渐进式发现工具的更高层级工具。详情请参阅渐进式披露。
• 工具结果会占用大量上下文窗口，为什么不使用 Bash？ Agent 可以不使用 MCP 工具，而是直接执行终端命令并使用 bash 过滤结果；但这意味着 Agent 将更频繁地执行高风险操作。例如，你可以允许 Agent 使用 gh CLI 与 GitHub 交互，但它也可以使用 gh CLI 执行修改或破坏性操作。使用 GitHub MCP Server，则可以轻松将工具限制为只读。MCP 允许你严格控制 Agent 可以访问哪些工具。为此，My Cool Proxy 允许你对向 Agent 暴露的工具进行进一步筛选。
• 大多数 MCP 功能都不受支持： 遗憾的是，大多数应用只向 Agent 暴露 MCP 工具，而忽略了协议提供的其他客户端和服务端功能。My Cool Proxy 旨在为尽可能多的协议功能提供通用抽象层，让开发者能够在任何兼容 MCP 的应用中使用 MCP 的全部功能。目前仍在开发中——更多详情请查看功能支持表。
• 为多个 Agent 管理配置文件很麻烦： 如果你使用不止一个兼容 MCP 的应用，很快就会遇到难以在这些应用间同步 MCP 服务配置的问题。My Cool Proxy 通过充当你所用每个服务的统一集成点来解决这一问题，将需要保持同步的服务数量减少到一个。

快速开始

0. 安装

全局安装，以将其用作 CLI 工具：

npm install -g @karashiiro/my-cool-proxy

或者通过 npx 直接运行：

npx @karashiiro/my-cool-proxy

1. 配置

网关会在首次运行时自动创建默认配置。只需运行一次即可生成配置文件：

my-cool-proxy  # Creates config and starts (with no servers)

# Find your config location
my-cool-proxy --config-path

然后编辑配置，添加你的 MCP 服务。

配置结构示例：

{
  "port": 3000,
  "host": "localhost",
  "mcpClients": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

或者，复制示例配置，以获得更完整的起始配置。

2. 运行

# If installed globally
my-cool-proxy

# If running via npx
npx @karashiiro/my-cool-proxy

3. 连接

将其添加到你的 MCP 客户端配置中，例如 Claude Desktop：

{
  "mcpServers": {
    "my-cool-proxy": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

4. 使用

让你的 Agent 执行一项配置的 MCP 服务可以协助完成的任务，然后观察它运行！

渐进式披露

此代理充当 Agent 与多个 MCP（模型上下文协议）服务之间的网关。Agent 无需分别连接每个 MCP 服务，只需连接到此代理，即可通过统一接口访问所有已配置的服务。

Agent 一开始对有哪些服务或工具可用知之甚少。它们会逐步构建上下文：

1. 查看服务说明——My Cool Proxy 会预加载一小段提示词，其中简要摘录了已配置的服务和工具，以引导 Agent 使用它们。
2. 调用 list-servers——Agent 的上下文现在包含所有可用 MCP 服务的名称和说明（例如，“github”、“slack”、“database”）
3. 调用 list-server-tools(server_name)——Agent 的上下文会扩展，包含该特定服务的所有工具名称和说明
4. 调用 tool-details(server_name, tool_name)——Agent 的上下文现在包含特定工具完整的参数模式、返回类型（如果有）和使用示例
5. 调用 execute(lua_script)——掌握完整上下文后，Agent 可以编写 Lua 脚本来调用已发现的工具

这种方式不会一开始就将所有工具及其说明加载到上下文中，而是等 Agent 确定需要哪些工具后再加载。

使用 Lua 链式调用工具： 知道有哪些工具后，Agent 可以在一次 execute() 调用中组合复杂的多步工作流，从而节省中间工具结果带来的上下文开销。Lua 运行时可以通过全局变量访问所有已发现的服务，并将其工具作为异步函数调用。

顺序链式调用工具：

local raw_data = api_server.fetch({ id = 123 }):await()
local processed = processor.transform({ input = raw_data }):await()
result(processed)

条件逻辑：

local status = checker.validate({}):await()
if status.ok then
  result(processor.run({}):await())
else
  result(error_handler.notify({ error = status.message }):await())
end

使用循环进行迭代：

local results = {}
for i = 1, 5 do
  results[i] = worker.process({ index = i }):await()
end
result({ total = #results, data = results })

网关技能

网关技能是 My Cool Proxy 对 Agent Skills 的实现——可供 Agent 加载为 MCP 资源的可复用上下文文档。启用后，Agent 可以：

• 通过自动注入到网关服务说明中的提示词发现技能（或通过 _gateway.list_resources() Lua 内置函数发现；查找 gw-skill:// URI）
• 通过 _gateway.read_resource() Lua 内置函数读取技能内容
• 通过 _gateway.invoke_skill_script() Lua 内置函数执行技能脚本

许多 Agent 已经实现了自己的技能系统，但这些系统高度分散，很难在多个独立的 Agent 应用之间复用相同的技能。虽然 skills.sh 等系统通过在应用之间显式复制技能来解决此问题，但 My Cool Proxy 通过将所有技能集中到自己的技能管理系统中，并通过 MCP 对外提供，解决了这一问题。为将这些技能与现有技能系统区分开来，My Cool Proxy 将其称为“网关技能”。

网关技能默认处于禁用状态，因为它们可能与 Agent 内置的现有技能系统冲突。请参阅配置指南了解设置选项。

如需深入了解以这种方式实现网关技能的设计原因，请参阅设计文档中的此部分。

Web 仪表板

My Cool Proxy 提供可选的 Web 仪表板，用于监控网关活动。启用后，它将在单独的端口上运行，并提供：

• 执行历史记录 — 浏览所有 Lua 脚本执行记录，查看带语法高亮的脚本和结果
• 工具调用日志 — 查看每次执行期间调用了哪些 MCP 工具
• 会话监控 — 查看活跃会话、已连接的服务和功能
• 实时更新 — 新执行记录通过 WebSocket 推送到仪表板

在配置中添加 dashboard 部分即可启用：

{
  "dashboard": {
    "port": 3100,
    "host": "localhost"
  }
}

然后在浏览器中访问 http://localhost:3100。详情请参阅配置指南。

配置

完整的配置参考请参阅配置指南。

MCP 功能支持表

功能	是否支持	详情
工具	✅	My Cool Proxy 至少要求支持工具。幸运的是，所有支持 MCP 的产品都支持工具。
提示词	✅	My Cool Proxy 会将 MCP 服务中的提示词转发给已连接的客户端，并提供 _gateway.get_prompt() 和 _gateway.list_prompts() Lua 内置函数，供 Agent 在脚本中加载这些提示词。
资源	✅	My Cool Proxy 会将 MCP 服务中的资源转发给已连接的客户端，并提供 _gateway.read_resource() 和 _gateway.list_resources() Lua 内置函数，供 Agent 在脚本中加载这些资源。
服务端指令	✅	My Cool Proxy 会将已连接的 MCP 服务的指令摘录加载到自身的服务端指令中，并在调用 list-servers 工具时发送完整副本。
发现通知	✅	My Cool Proxy 会监听已连接的 MCP 服务发出的工具／提示词／资源变更通知，自动更新自身的内部注册表，并在后续工具调用中体现这些更新。
补全	✅	上游服务的提示词参数和资源模板变量补全会转发给已连接的客户端。Agent 也可以在 Lua 脚本中调用 _gateway.complete()，以发现资源模板变量和提示词参数的有效值。
日志记录	✅	My Cool Proxy 会将日志通知转发给已连接的客户端，也会自行记录这些日志。
根目录	✅	roots/list 请求会从上游服务转发给下游客户端。下游客户端发出的 notifications/roots/list_changed 通知会分发给所有上游服务。当采样垫片处于活动状态时，会将第一个有效的本地根目录用作 ACP Agent 的工作目录。
采样	✅	My Cool Proxy 支持通过 ACP为采样提供垫片，不过默认禁用。详情请参阅配置文档。
征询	⚠️	征询请求（表单和 URL 模式）会从上游服务代理到已连接的客户端。目前，对于原生不支持征询的客户端，尚无可用垫片（与可通过 ACP 提供垫片的采样不同）。(目前)
进度	✅	上游服务发出的进度通知会转发给已连接的客户端。当 Lua 脚本并发调用多个工具时，它们的进度会汇总（相加）到单个流中。
任务	⚠️	支持调用支持任务的工具，但不会利用状态更新实现任何特别功能。目前不支持采样／征询任务。
OAuth 2.0	❌	尚不支持 OAuth 2.0 身份验证质询（但将会支持）。
MCP Apps	❌	尚不支持 MCP Apps（但将会支持）。