feat(mcp): add MCP runtime configuration

[GatewayJ]

Summary

• Add shared MCP config support across agent profile and hub resource flows.
• Wire MCP config generation into OpenClaw, PicoClaw, and Codex runtime adapters, including remote/stdio server payload handling.
• Improve MCP runtime observability with tool progress handling and timeout behavior.
• Add UI for managing MCP configs, including JSON highlighting and inline JSON validation for MCP resource config editing.
• Document the OpenClaw MCP restart/configuration plan.

Validation

• pnpm vitest run tests/components/HubDetailPane.test.tsx tests/models/mcpHub.test.ts tests/components/AgentActions.test.tsx
• pnpm exec eslint web/app/src/pages/HubPage/components/HubDetailPane/HubDetailPane.tsx web/app/src/pages/HubPage/components/HubDetailPane/HubDetailPane.css web/app/src/models/mcpHub.ts web/app/src/shared/i18n/messages.ts tests/components/HubDetailPane.test.tsx tests/models/mcpHub.test.ts tests/components/AgentActions.test.tsx tests/setup.ts
• pnpm exec prettier --check web/app/src/pages/HubPage/components/HubDetailPane/HubDetailPane.tsx web/app/src/pages/HubPage/components/HubDetailPane/HubDetailPane.css web/app/src/models/mcpHub.ts web/app/src/shared/i18n/messages.ts tests/components/HubDetailPane.test.tsx tests/models/mcpHub.test.ts tests/components/AgentActions.test.tsx tests/setup.ts package.json pnpm-lock.yaml
• pnpm exec tsc --noEmit
• git diff --check
• GitHub check: validate-pr-message

Notes

• Updated the PR head from the older fork branch state to the current local branch with --force-with-lease.
• The previous merge conflict was resolved by updating the PR branch onto the current upstream main history.

[GatewayJ]

MCP light-theme screenshots

Captured from the local CSGClaw service at http://127.0.0.1:18080/ using Playwright MCP. For each screenshot I verified the page state before capture:

• light theme: document.documentElement.dataset.theme === "light"
• Chinese: document.documentElement.lang === "zh-CN"
• English: document.documentElement.lang === "en"

Page	中文 / Light	English / Light
Resources MCP
Agent Profile MCP

[RussellLuo]

MCP 相关命名现在有点分散：agent 状态里叫 mcp_config，配置对象内部又叫 mcpServers，Hub 资源路径叫 /mcp-servers，agent 从 Hub 添加时也用了 /mcp-servers，前端还有 mcps 变量名。这个功能还在当前 PR 内，尚未发布给用户，建议现在统一命名，避免之后 API 和代码长期维护多套语义。

建议统一成“agent 拥有 MCP servers，Hub 管理 MCP servers”的模型。

Agent 字段 / API payload

• agent 新增字段统一叫 mcpServers，不要叫 mcp_config。
• mcp_config -> mcpServers
• Agent.MCPConfig -> Agent.MCPServers
• CreateAgentSpec.MCPConfig -> CreateAgentSpec.MCPServers
• UpdateRequest.MCPConfig -> UpdateRequest.MCPServers
• MCPConfigSet -> MCPServersSet
• MCPConfigView -> MCPServersView
• response 里的 desired / actual 可以直接表示 server map，而不是 { "mcpServers": ... } wrapper。

也就是 agent payload 从：

{
  "mcp_config": {
    "mcpServers": {
      "context7": { "command": "npx" }
    }
  }
}

收敛成：

{
  "mcpServers": {
    "context7": { "command": "npx" }
  }
}

如果 runtime adapter 内部仍需要 { "mcpServers": ... } 这种配置形态，可以在 runtime 边界临时包装，不要让 agent state/API 再存一层 wrapper。

URL path

• GET /api/v1/agents/{id}/mcp -> GET /api/v1/agents/{id}/mcp-servers
• PUT /api/v1/agents/{id}/mcp -> PUT /api/v1/agents/{id}/mcp-servers
• POST /api/v1/agents/{id}/mcp-servers -> POST /api/v1/agents/{id}/mcp-servers:batchAdd
• Hub catalog 保持：
  • GET /api/v1/mcp-servers
  • POST /api/v1/mcp-servers
  • PUT /api/v1/mcp-servers/{name}
  • DELETE /api/v1/mcp-servers/{name}

这样 path 上可以区分：

• /agents/{id}/mcp-servers：agent 当前拥有的 MCP servers。
• /agents/{id}/mcp-servers:batchAdd：把 Hub 中的 MCP servers 按名称批量添加到 agent。
• /mcp-servers：Hub MCP server catalog。

Handler / service 命名

• handleAgentMCPByID -> handleAgentMCPServersByID
• handleAgentMCPServersByID -> handleAgentMCPServersBatchAdd
• decodeAgentMCPConfigRequest -> decodeAgentMCPServersRequest
• addAgentMCPServersRequest -> batchAddAgentMCPServersRequest
• AddMCPServers -> AddMCPServersFromHub
• MCPConfigView / MCPConfigView(...) -> MCPServersView / MCPServersView(...)
• writeAgentMCPMutationError 可以保留，或改成 writeAgentMCPServersMutationError。

Runtime / internal helper 命名

如果 runtime 层还想保留“配置对象”的抽象，可以保留 MCPConfigController；但 agent/service/API 层建议用 servers 语义：

• agent/service/API 层：MCPServers
• runtime adapter 边界：需要 wrapper 时再转成 MCPConfigSnapshot{Config: {"mcpServers": ...}}

这样可以减少 agent API 暴露内部 config wrapper 的感觉。

前端命名

• agent.mcp_config -> agent.mcpServers
• AgentLike.mcp_config -> AgentLike.mcpServers
• AgentDraft.mcp_config -> AgentDraft.mcpServers
• agentMCPConfig() -> agentMCPServers()
• draftMCPConfigForSave() -> draftMCPServersForSave()
• fetchAgentMCPConfig() -> fetchAgentMCPServers()
• updateAgentMCPConfigRequest() -> updateAgentMCPServersRequest()
• addAgentMCPServersRequest() -> batchAddAgentMCPServersRequest()
• agentMCPConfigQuery -> agentMCPServersQuery
• mcpConfigWithServers() -> mcpServersPayload() 或 mcpServersWithUpdates()
• mcps -> mcpServers
• hub.mcps -> hub.mcpServers
• selectedMCP -> selectedMCPServer
• selectedMCPName -> selectedMCPServerName

整体目标是让文档和代码都能用一句话解释清楚：Hub 管理 MCP servers，agent 保存 MCP servers，:batchAdd 是把 Hub MCP servers 按名称添加到 agent。这样就不需要同时解释 mcp_config、mcpServers、mcp-servers、mcps 这几套相近但不完全一致的命名。