Skip to content

MCP.zh-CN.md

Latest commit

 

History

History
293 lines (212 loc) · 20.1 KB

MCP.zh-CN.md

File metadata and controls

293 lines (212 loc) · 20.1 KB
Raw

MCP

English | 简体中文

WebCodex 通过 MCP endpoint，让 ChatGPT、Claude 与其他 MCP client 使用持有仓库机器上的 Runner。普通用户先选择完整使用还是临时试用即可；protocol surface、scope、credential taxonomy 都属于 reference，不是 onboarding 前置知识。

ChatGPT：推荐的完整使用方式

日常使用推荐普通 Server + Runner。按照完整使用指南完成一次性登录和项目注册，并在同一次 webcodex login 中使用 --print-mcp-config 获取普通 HTTPS MCP 连接信息。公网 HTTPS、Cloudflare Tunnel 或 OpenAI Secure MCP Tunnel 只负责到达 Server，不改变这条完整开发路径本身的能力。

如果只是临时试用一个仓库，再使用下面的 share 路径。

ChatGPT：临时 share

显式 share 支持 Linux、macOS 与 Windows，并由当前前台进程持有临时单项目环境。Windows x64 可直接使用 managed 默认 Cloudflare Quick Tunnel；固定版本 Cloudflare 没有官方 Windows ARM64 artifact，因此 ARM64 需要受信任的显式/PATH cloudflared。managed OpenAI tunnel-client 支持 Windows x64/arm64。

默认临时公网路径会复用显式指定/PATH 中的 cloudflared，否则由 WebCodex 自动下载并校验固定的 managed 副本，然后执行：

npm install -g @yyjeqhc/webcodex
cd /path/to/your/repository
webcodex share

CLI 显示 WebCodex ready 后：

  1. 在 ChatGPT Developer Mode 创建基于 MCP 的 custom app。
  2. 填入输出的 MCP URL。
  3. 默认 share 选择 Access token / API key（Bearer token）。
  4. 填入输出的临时 Credential。
  5. 点击 Scan Tools。
  6. 第一条可先说：检查这个仓库并总结它的结构。先不要做任何修改。

share 自己会完成 project setup。Hosted ChatGPT 无法访问 loopback-only 的 webcodex run，因此 setup、doctor、run 都不是 share 之前的必经步骤。ChatGPT UI 文案可能随 rollout 变化；URL 与认证以 CLI 输出为准。Developer Mode、custom MCP app 和 write/modify action 是否可用，还分别受 ChatGPT 套餐、workspace 与管理员设置控制； WebCodex scope 不会扩大这些客户端侧权限。

Claude 与其他 MCP client

使用同一份输出的 /mcp URL 与认证值。Claude 中添加 custom connector 并粘贴 MCP URL； 其他 MCP client 同样使用 CLI 报告的 endpoint 与认证方式。仅本地 client 可用 webcodex share --tunnel none，不需要 cloudflared。

如果 client 无法设置 Bearer header，可显式使用 webcodex share --auth query-token： 粘贴输出的敏感 /mcp?token=... URL，并选择 No authentication。这个 query 只接受当前 share 的 Project Credential，并不是 PAT/OAuth/shared-key 的通用 query auth。整条 URL 都必须当作 secret，因为 URL query 可能进入日志。

如果只需要 OpenAI 产品的私有 transport，创建/选择 Secure MCP Tunnel，导出 CONTROL_PLANE_TUNNEL_ID 与只授予 Tunnels Read + Use 的 Restricted CONTROL_PLANE_API_KEY，然后运行 webcodex share --tunnel openai。ChatGPT 使用 Connection: Tunnel + No authentication；临时 WebCodex Bearer 留在本机，由固定且经过校验的 OpenAI tunnel-client 注入。

对于通过 OpenAI Secure Tunnel 访问的长期 loopback-only Server，可以设置 WEBCODEX_MCP_TRUST_LOOPBACK_API_TOKEN_FILE_IMPORT=true，从而信任由本机 user API token 认证的 ChatGPT host-file rewrite。WebCodex Desktop 自 v0.4.2 起会为它自己管理的本机 loopback Server 默认写入该值；已有显式配置不会被覆盖。该例外仅在 WEBCODEX_ADDR 解析为 loopback 且当前 credential 是普通 user API token 时生效。独立/network-accessible Server 仍默认关闭，不应使用它替代 OAuth。

如果在 Windows 上使用普通独立 Server + Runner 并通过 OpenAI Tunnel 接入，或排查“本地 /readyz 正常但 ChatGPT Connector 创建失败”的情况，见 Windows + OpenAI Secure MCP Tunnel 深入实操。它是深入配置/排障文档，不是普通用户第一次必须阅读的教程。

已有 Server

对于已经明确配置为 shared-key client 接入的 hosted Server，使用 operator 提供的 credential 走长期 shared-key 路径：

webcodex connect https://webcodex.example --key-file /private/path/shared-key

connect 会启动/复用本地 Runner，并在连接验证完成后输出 MCP URL 与 credential source。 这与刚完成 Docker bootstrap 的自托管 Server enrollment 不同：bootstrap administrator token 保留在 Server 机器上，由 Server 创建短期 pairing code，再在仓库机器上执行 webcodex login。 自托管见部署指南。

Bearer/shared-key 是最简单的路径。客户端要求 OAuth 时，使用 share --auth oauth 或 connect --auth oauth 并传入该客户端的精确 callback URL，然后按 CLI 输出配置。managed-user OAuth 仍是独立的高级身份路径。

Advanced / reference

Adaptive Runtime routing

WebCodex 只有一个 model-facing MCP runtime contract：Adaptive Runtime。Canonical ToolDefinition rank 决定 direct tools；普通 model-visible long-tail tools 通过 call_runtime_tool 调用；server-owned protocol capability 与 MCP App admission 可以为对应请求加入 hidden extension。启动时不再选择 model surface。tool_manifest(tool_name=...) 只负责 discovery，不会动态向 Host 注册一个新 tool。exact manifest 的 route.primary 给出首选 callable；普通 direct tool 还会给出经 call_runtime_tool 的 route.fallback，用于 Host 当前没有该 direct callable 的情况；显式 MCP App presentation tool 会标明 Apps enabled 时该 fallback 被禁止。direct/gateway 只改变 presentation，不会绕过目标工具的 authentication、Project authority、permission、Runner capability、Session 或 safety checks。

Tool result framing

MCP tool 的 machine-readable 结果位于 structuredContent；content 只保留简短的人类可读或 protocol-native fallback。需要结构化字段的 client 应读取 structuredContent，不要解析文本。

普通 client 保持标准 MCP isError 语义。对于 _meta["io.modelcontextprotocol/clientInfo"].name 精确等于 openai-mcp（不限版本）的请求，MCP adapter 会对 WebCodex-owned canonical ToolResult failure 应用 OpenAI structured-failure compatibility projection：presentation 使用 isError=false，但 structuredContent.success=false 仍是业务结果的 authoritative truth，完整 output/error 也继续保留。当前 OpenAI Host 会把 isError=true 提升成异常而不暴露 structuredContent；该兼容层用于保留 machine-actionable failure/recovery data，Host 行为修复后即可移除。JSON-RPC/protocol error 仍然是真错误，第三方 MCP/Plugin passthrough result 也继续保留 provider 自己的语义。

部分 MCP host 不会把 structuredContent 暴露给模型；Claude Custom Connector 已观察到这种情况，即使 WebCodex 已成功执行工具并返回完整结构化结果。为这类 host 提供服务的 operator 可以显式设置 WEBCODEX_MCP_TEXT_JSON_COMPAT=true。开启后，普通 runtime tool result 仍以 structuredContent 为 canonical，同时把同一 JSON 值序列化到 content[0].text。该选项默认关闭，因为重复表示会增加 response/model-context 大小；protocol-native image/resource framing 与现有 App-only compatibility path 不受影响。

Result 中的 recovery 字段只描述下一次显式调用的安全建议，不授予 authority，也不会触发 hidden retry。尤其是 uncertain outcome，必须先 reconcile，再决定是否重复 effect。

内建 local MCP gateway

hosted Server 可以通过同一个 /mcp 暴露 Runner-owned 本地 stdio MCP provider。有权限的 caller 使用单一 mcp_tool 来 list、describe、call 已配置 provider；provider process/instance identity 与 schema-revision state 都留在内部。

在 Runner 的 [mcp] 中配置 provider。访问需要显式 mcp:local permission；hosted OAuth client 通过 webcodex connect ... --oauth-local-mcp opt in。Provider compatibility 细节见 Runner。

Managed SSH resource 接入

ssh_resource 工具提供一条窄化的 Runner-local 命名 SSH resource 接入路径。list 观察安全逻辑名称并返回 opaque exact-Runner/revision binding；register 与 remove 消费该 binding，只修改 durable desired state。它们不会把旧 mutation 静默重定向到 replacement Runner，也不会在 uncertain outcome 后自动 replay。Raw SSH target 不会出现在 工具结果或 normal/full trace body 中。返回 restart_required=true 时，应先重启 Runner， 再重新 list，之后才能在 Workflow Session 中选择该资源。

该 surface 需要可选 ssh:local permission，不属于普通 hosted OAuth baseline；通过 webcodex connect ... --oauth-local-ssh 显式 opt in。Static/managed 语义与 PersistentShell 边界见 Runner。

OAuth2

启用 OAuth 后，MCP client 可以使用 authorization-code flow，而不是静态 token。注册 client 实际要求的精确 callback URL；host 要求 refresh-token support 时保留 offline_access；连接参数以 share --auth oauth 或 connect --auth oauth 的输出为准。Server 配置见部署指南。

普通 hosted connect --auth oauth 中，Runner 保持原 hosted credential，MCP client 获得独立 OAuth credential。只有真正需要额外能力时才增加 --oauth-computer-permissions、--oauth-local-mcp 或 --oauth-local-ssh。已有 client 不会被静默扩权；真实权限变化要求重新授权。

Project-first share --auth oauth 仍绑定本次临时 share 环境。Managed-user OAuth 是另一条高级流程（connect --auth managed-oauth）。OAuth credential 永远不能用于 Runner transport。

Credential 与 scope 模型见认证。

Grok Custom Connector（OAuth）

Grok 支持自定义 MCP Connector，并可完成 MCP Server 要求的 OAuth 流程。对于 自托管 WebCodex Server，先通过公网 HTTPS 暴露 https://your-domain.example/mcp，并启用 OAuth：

WEBCODEX_OAUTH2_ENABLED=true
WEBCODEX_OAUTH2_ISSUER=https://your-domain.example
WEBCODEX_PUBLIC_URL=https://your-domain.example

当前 Grok Web Connector 流程（2026 年 8 月已验证）使用以下 redirect URI，注册时 必须精确匹配：

https://grok.com/connectors-oauth-exchange-code/

如果后续 Grok 展示或实际使用了不同 callback，应改为注册 Grok 当时提供的精确值。 为 Grok 单独创建 OAuth client；client_secret 只会返回一次：

curl -fsS -X POST https://your-domain.example/api/oauth/clients/create \
  -H "Authorization: Bearer $WEBCODEX_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Grok MCP","redirect_uris":["https://grok.com/connectors-oauth-exchange-code/"],"allowed_scopes":["runtime:read","project:read","project:write","job:run"]}'

在 Grok 的 Custom Connector 表单中填写：

字段 值
MCP server URL https://your-domain.example/mcp
Client ID 创建 client 时返回的 wc_client_*
Client Secret 只返回一次的 wc_csec_*
Authorization Endpoint https://your-domain.example/oauth/authorize
Token Endpoint https://your-domain.example/oauth/token
Scopes runtime:read、project:read、project:write、job:run、offline_access
Token Auth Method client_secret_post

WebCodex 会公布 PKCE S256；Grok 可以同时使用 PKCE 与 client_secret_post。对于已经注册 client secret 的 WebCodex OAuth client，不要选 none (PKCE only)。offline_access 是用于 refresh token 的协议级 scope，不会写进 OAuth client 的 allowed_scopes 权限列表。MCP Protected Resource Metadata 会省略 scopes_supported，因为不同的预注册 client 可能有不同的 scope 上限。通用 MCP 客户端 因此可以省略 scope，由 WebCodex 把授权请求默认到该 client 已注册的 allowed_scopes。

打开 WebCodex Authorization 页面后，用希望 Grok 代表的用户当前有效 PAT （wc_pat_*）登录。Runner token（wc_agent_*）不是用户登录 token。最终签发的 OAuth access token 会绑定到该用户，同时继续受 client 注册权限和本次请求 scopes 约束。

常见错误：

  • Save & Connect 为灰色： Grok 在启动 OAuth 前要求 Client ID 已填写。
  • invalid token： PAT 必须能在当前这台 WebCodex Server 的数据库中通过认证； 不要使用 Runner token，也不要使用旧 Server/旧数据库遗留的 stale PAT。
  • invalid scope： 每个 WebCodex permission scope 都必须包含在该 OAuth client 的 allowed_scopes 中。普通 Grok MCP 接入不需要 account:manage； offline_access 作为协议级 scope 单独接受。
  • redirect mismatch： redirect URI 必须与注册值逐字一致，包括路径和末尾 /。

Grok Custom MCP UI 与可用范围以 xAI 的 Connector 文档为准。

Project-scoped ordinary runtime

webcodex run 与 webcodex share 绑定一个已配置仓库，启动本地 Server + Runner，并暴露普通 Adaptive Runtime。临时或持久的 Project Credential 是 authentication / ProjectGrant 边界，不会选择第二套 capability surface。

典型 coding 流程是：

work_on_project
→ read_files / search_project_texts / 按需语义导航
→ apply_text_edits 或其它 canonical edit 工具
→ 按需 run_process / run_shell / focused validation
→ show_changes
→ finish_coding_task

work_on_project 在普通 registered Project 上启动或精确恢复 Workflow Session。用户要求隔离时，work_on_project(mode=worktree) 才让 Runner 创建 canonical managed worktree，并把该 worktree 注册为另一个普通 Project；没有隔离要求时，本地 share / run 直接使用 setup 已注册的那一个 Project。

Adaptive Runtime 可以把常用工具直接暴露，把 long-tail 工具通过 call_runtime_tool 暴露。direct/gateway 只影响 model exposure，不改变 schema validation、OAuth scope、Project authority、permission policy、Runner capability、Session fence 或 tool effects。

已删除的 ProjectConnector capability 名称（task_start、files_read、edits_apply、task_finish 等）不会作为 runtime 工具的 compatibility alias 保留。请使用当前 tools/list / tool_manifest 返回的 ToolRuntime 名称。

长任务使用 Job lifecycle

长时间 command 与 validation 使用 canonical WebCodex Job。发起调用返回 exact Job 后，用 observe_jobs 观察同一个 Job；只有 Job identity 确实丢失时才用 list_jobs 恢复，不要重复启动。Jobs 不再包装成 MCP Tasks，WebCodex 也不再 advertise 原 Connector-specific MCP Tasks extension。

第一个安全 prompt

Use the configured WebCodex project. Inspect README.md and summarize the
project structure. Do not edit files or run commands.

这个 prompt 里不需要项目发现或 runtime 标识符。

读取与搜索边界

  • read_files 是 canonical 有界范围读取工具，一次支持 1 到 8 个文件；单条目 batch 就是单范围读取路径。每个成功条目返回完整文件 SHA-256 与有界行元数据；partial 条目返回可直接执行的单条目 read_files continuation，且读取并非 snapshot-stable。
  • search_project_texts 是 canonical 有界搜索面，一次支持 1 到 8 个独立查询（优先 ripgrep，并保留现有有界 fallback）；单查询直接使用 one-query batch。

只有已识别的 backend 明确报告搜索正常完成且无匹配时，空搜索结果才是肯定的 “无匹配”证据。backend 标识缺失或畸形、完成状态缺失、状态与输出不一致、 backend 失败、Runner 失败、超时、请求丢失及 provider 失败都会返回失败。 搜索失败保留兼容的 code，并增加有界的 failure_stage 与具体 reason_code。批量失败条目保留宽泛的 reason_code，同时通过 failure_stage 和 detail_code 保留单项搜索 provenance；成功条目仍保持 稀疏投影。

失败返回只含项目相对路径的小型结构化错误——绝不包含绝对路径、命令或 Runner stderr、provider stderr 或任意 provider prose。

常见错误

错误码 含义 处理
project_not_configured 没有 canonical setup 运行 webcodex setup
project_credential_invalid 私有 Project Credential 缺失或不匹配 恢复两个匹配的私有文件或重建 profile
project_credential_rejected 可达 server 拒绝了该凭据 恢复与 server 匹配的凭据
workspace_unavailable 配置的 Git 工作区不可用 恢复工作区，再运行 doctor
server_unreachable / agent_offline 项目 Runner/runtime 不可用 运行 webcodex run / webcodex doctor
required_capability_unavailable 当前 Runner/runtime 缺少所需 coding capability 升级所有二进制
project_registry_scope_denied Project-scoped credential 尝试扩张或修改其授权可见范围之外的 Project registry 使用已可见的 Project，或使用 work_on_project(mode=worktree)

Adaptive Runtime extensions

同一个 ToolRuntime 通过一套 Adaptive Runtime contract 服务单项目、project-scoped 的本地 share / run 和多项目 hosted Server。project-scoped credential 改变可见性与 authority，不改变 model-facing runtime shape。特定 protocol capability 与 MCP App 可以 admission 额外的 hidden presentation/resource operation，但不会形成第二套 runtime surface。

ChatGPT 文件桥接

当当前 MCP protocol/host admission 允许 artifact capability 时，WebCodex 支持双向的 host-native 文件传输，不需要把完整二进制经由模型文本搬运：

  • import_conversation_files_to_project 通过 ChatGPT host 的 openai/fileParams 导入 1..10 个文件。它既适用于用户选择的当前会话附件，也 适用于 host 能绑定为 file parameter 的本轮新生成文件。Control 端负责下载原始 bytes，并通过现有有界 artifact write 路径提交；调用方不应自行构造下载 URL， 也不应手工 Base64 转运这些文件。
  • project_artifact 是首选的 Project → Model / Host 读取入口： action=metadata 用于 existence/size/MIME/digest/image/archive metadata； action=inspect 只读取一个有 snapshot fence 的有界 Base64 segment； action=image 通过 MCP native image delivery 给模型查看图片； action=export 用于把完整 artifact 交付给 host/user。不要循环 inspect chunk 来完成整文件传输。
  • action=export 继续复用现有 artifact export authority，创建短期、受认证的 MCP ResourceLink 并返回 metadata。tools/call 不包含完整二进制；host 通过 resources/read 取得 binary resource。读取时会再次检查认证与当前 project-read authority，并在返回 bytes 前重新验证 artifact metadata。Resource URI 本身不是独立 bearer authority；export handle 只是短期、process-local 的 presentation state，现有大小、MIME、路径与 authorization 边界继续生效。

底层 read_project_artifact_metadata 与 read_project_artifact 继续作为 operator/gateway primitive 保留。旧的 export_project_artifact compatibility tool 已 删除；完整 host 交付统一通过 project_artifact(action=export) 暴露。DOCX/PPTX/XLSX 等 Office artifact 与 PDF 仍复用同一底层 artifact transport，因此在支持这些 host 能力的 ChatGPT 中，可以在 project 与 host 之间直接传递，而不需要模型手工搬运 Base64。

请阅读 Coding 工作流，使用 canonical work_on_project bootstrap / behavioral role 心智模型，并遵循其中的 validation/closeout guidance。运维工具见 架构 与 webcodex CLI。