cloudflare-mcp-smart-proxy

v1.5.23

Published

8 days ago

Smart proxy for Cloudflare MCP - routes tools to cloud or local execution

Downloads

441

0High
0Medium
0Low

jobssteve164

mcp cloudflare proxy local filesystem

CLOUDMCP Local Proxy

local-proxy 是 CLOUDMCP 当前主线的参考连接器实现。

它包含两层能力：

index.js
- stdio MCP server，负责把本地工具和云端 CLOUDMCP 工具统一暴露给宿主生态
connector-cli.js
- 参考连接器安装器，负责把这条 stdio 入口写进目标生态的原生配置文件

自 A3 起，官方优先支持两个生态：

codex
claude_code

当前入口

查找工具与准备授权

连接器初始工具 connector_discover_tools 使用现有目录读取权限，无需先申请业务工具，也不会创建审批卡或执行业务动作。先按能力关键词搜索，例如 {"query":"trends"}；再把选中的名称一起放进 toolNames，获取公开参数、当前精确授权、资源要求及待申请清单。

返回的 authorizationRequests 沿用 request_project_tool_authorization。只有 ready: true 的条目可原样提交其 arguments；缺少资源时，从 resourceChoices 选择后通过 resourceSelections 再次准备。用 offset 翻工具页、resourceOffset 翻资源页。资源不会因为唯一候选而自动扩大授权，已生效授权直接复用；创建动作所需的前置项目授权也会列入同一份准备结果。批准后用 get_project_tool_authorization 读取完整申请 ID，再调用原工具。

查询按需执行，不加入启动同步。尚未绑定项目时仍可搜索目录，项目申请继续使用既有项目注册和连接器审批流程。全局能力仍由现有连接器全局授权治理。原始 /mcp/tools 目录响应保持兼容；连接器使用其 discovery=true 查询模式准备授权。

若目录因工具重名而生成了与 Provider 合同不一致的名称，查询会返回 catalog_name_conflict，不生成可提交申请；Provider 修正唯一工具名后才能申请，不能去掉前缀后套用别的工具授权。

1. 作为 MCP stdio server 运行

cd /home/coder/project/CLOUDMCP/local-proxy
export CLOUDFLARE_MCP_URL="https://your-cloudmcp.example.com"
export CLOUDFLARE_MCP_API_KEY="your_api_key"
export CLOUDMCP_CLIENT_PROFILE_ID="client_profile.codex.default"
node index.js

正式 IDE 安装默认不会把仓库内 index.js 路径写进用户配置，而是写入已发布包入口：

{
  "command": "npx",
  "args": ["-y", "-p", "cloudflare-mcp-smart-proxy", "cloudflare-mcp-proxy"]
}

当前已发布包名与可执行名不同，因此正式入口需要显式指定包与命令。仓库内入口只保留给本地开发调试，通过 --runtime local 显式选择。

2. 经过审批后自动安装（正式主线）

npx -y -p cloudflare-mcp-smart-proxy cloudmcp-connector activate codex \
  --cloud-url https://your-cloudmcp.example.com

第一次运行会生成设备密钥并发起接入申请，不会取得任何租户配置或凭证。管理员在 CloudMCP 后台“生态连接中心”的专用审批表单中核对申请者，勾选一个或多个环境空间和原子能力并批准后，将一次性审批密令回传给智能体。智能体随后运行：

printf '请输入一次性审批密令：'
read -s CLOUDMCP_APPROVAL_CODE
printf '\n'
export CLOUDMCP_APPROVAL_CODE
npx -y -p cloudflare-mcp-smart-proxy cloudmcp-connector activate codex \
  --cloud-url https://your-cloudmcp.example.com
unset CLOUDMCP_APPROVAL_CODE

审批密令 10 分钟内有效、只能成功领取一次，并且只能由原申请设备签名领取。连接凭证写入权限为 0600 的独立文件，IDE 配置只保存该文件路径。CloudMCP 的机器可发现入口为 /.well-known/cloudmcp。

如果本机申请已被拒绝或过期，直接再次运行无审批密令的 activate 命令会复用原设备身份并自动创建新申请。也可显式要求重新申请：

npx -y -p cloudflare-mcp-smart-proxy cloudmcp-connector activate codex \
  --cloud-url https://your-cloudmcp.example.com \
  --reapply

该操作不会删除或重建设备身份，也不会在新申请创建成功前改写现有凭证。若设备连接仍处于有效状态，后台会拒绝重复申请；管理员应先撤销该连接，再运行上述命令。

目标配置文件

Codex

配置文件：~/.codex/config.toml
设备身份：~/.codex/cloudmcp/device-identity.json
写入方式：managed block 原子写入，不覆盖用户其他配置
激活方式：安装完成后自动调用 Codex app-server 官方配置热加载，并确认 cloudmcp 已发现工具；无需重启对话或人工结束进程
兼容迁移：首次安装会把已有 ~/.cloudmcp/device-identity.json 安全迁移到 Codex 共享目录，避免不同运行视图生成不同设备身份

Claude Code

项目级：<workspace>/.mcp.json
用户级：~/.claude.json
写入方式：JSON merge，不覆盖其他 mcpServers

默认注入环境变量

CLOUDMCP_CREDENTIAL_PATH
WORKSPACE_ROOT
CLOUDMCP_CLIENT_PROFILE_ID
CLOUDMCP_CONNECTOR_ID
CLOUDMCP_CONNECTOR_TYPE
CLOUDMCP_WORKSPACE_ID
CLOUDMCP_DEVICE_IDENTITY_PATH

凭证文件保存服务 URL、设备绑定 API Key 和批准后的精确范围；这些字段会让连接器启动后直接进入：

PUT /connectors/workspace-binding
GET /connectors/install-plan
POST /connectors/status-reports
POST /connectors/project-probes
GET /connectors/project-variables
POST /connectors/project-variables/pull
PUT /connectors/project-variables
DELETE /connectors/project-variables

项目变量不会作为云端 MCP 明文读取工具暴露。Connector 提供四个本地工具：

connector_get_project_env_status
connector_plan_project_env_sync
connector_plan_project_env_delete
connector_apply_project_env_plan

Agent 只看到变量名、差异和计划 ID；值只在已绑定 Connector 与 CloudMCP 私有合同之间移动。完整语义见项目环境变量同步设计。

对应的正式协议定义见：

本地记忆目标

原有 cloudflare-mcp-smart-proxy 包同时提供以下本地工具：

configure_local_memory_target：显式配置一个本地 JSON 记忆目录，并从当前连接器获授权的云端 scope 初始化有效条目。
get_local_memory_target：读取当前连接器工作空间的本机目标契约。
verify_local_memory_target：回读验证目标契约或一个精确条目。
capture_memory：以同一事务写入受治理的 CloudMCP memory plane 和已配置本地目标，双端回读一致后才返回成功。
invalidate_memory：以 revision、原因和证据软失效一个精确条目，并把同一 canonical JSON 提交到本地与云端。
close_session：把简洁交接转换为 working + handoff，复用与 capture_memory 相同的双端事务。

capture_memory / invalidate_memory / close_session 只有在当前连接器通过云端鉴权、对应工具能力授权及精确 memory_scope 资源授权后才会被本地协调器暴露。它们仍复用原代理的 API Key、设备签名和 CloudMCP 请求路由，不存在匿名云端写入口。search_memory / get_memory_entry / load_context 保持受治理云端只读工具，由同一授权链提供。

本地目录不是硬编码的。以 SoloMap 为目标时，用户或 Agent 可把其记忆根目录显式传给配置工具；未安装 CloudMCP 的 SoloMap 用户继续使用原有 Markdown 机制，公共 SoloMap 插件不会默认依赖这些工具。

常用命令

Dry-run 渲染配置

node connector-cli.js print codex \
  --cloud-url https://cloudmcp.example.com \
  --api-key test-key \
  --client-profile-id client_profile.codex.default

本地 smoke

npm run smoke:connectors

重新激活现有 Codex 配置

node connector-cli.js reload codex

该命令不需要再次传入凭据。若 Codex app-server 正在运行，它会执行官方热加载并检查工具数量；若 app-server 尚未运行，配置会在下次启动时直接生效。运行中的 app-server 若加载失败或没有发现任何云端治理工具，命令会明确失败，不再把空工具集误报为安装成功。

验证

连接器启动默认不自动同步 Skill。需要更新时调用已有 connector_sync_skills 工具，它会完成受管版本校验、下载和本机激活后返回结果；未同步时继续使用本地已安装版本。

如显式设置 CLOUDMCP_AUTO_SYNC_SKILLS=true，同步会在后台执行，不阻塞 MCP 握手和工具目录加载。connector_bridge_status.state.lastSkillSync.status 可查看 running、succeeded 或 failed；后台同步进行中调用手动同步会等待同一次工作，不重复下载或激活。同步失败可再次手动调用重试，不影响工具使用。

node --test /home/coder/project/CLOUDMCP/tests/reference-connector-a3.test.js \
  /home/coder/project/CLOUDMCP/tests/codex-app-server-reload.test.js \
  /home/coder/project/CLOUDMCP/tests/local-proxy-device-identity.test.js \
  /home/coder/project/CLOUDMCP/tests/local-proxy-memory.test.js \
  /home/coder/project/CLOUDMCP/tests/local-proxy-tool-discovery.test.js

备注

install --api-key 只保留给已经绑定设备的旧连接器迁移；未绑定 API Key 无法注册新设备。
旧的 Cursor / Claude Desktop 入口仍保留兼容，但它们不再是 A3 主线。
A3 没有把 systemPrompt 直接写进项目根级 AGENTS.md 或 CLAUDE.md，以避免覆盖用户已有 agent 规范文件。