MCP 服务器

将 OpenCorvus agent 接入本地或远程 MCP server。

MCP 是 Anthropic 主导、社区维护的开放协议，定义 LLM 应用与外部工具服务器的标准通信接口。协议规范：modelcontextprotocol.io。

OpenCorvus 是 MCP Client：连接外部 MCP Server，并把其工具、提示词和资源投影进当前专家团 runtime。

源码：packages/opencorvus/src/mcp/index.ts

1. 消费外部 MCP Server

连接时序

服务启动读 config mcp 字段（src/mcp/index.ts）
按 type 创建 transport：
- "local" → StdioClientTransport（子进程 stdin/stdout）
- "remote" → 必须显式配置 transport：标准远程 MCP endpoint 使用 streamable-http，仅支持 SSE 的 server 使用 sse
连接后 client.listTools()
工具名经 sanitize（非字母数字 → _）后以 {clientName}_{toolName} 注册到 session 工具集

Agent 调用 MCP 工具时通过 client.callTool() 转发（src/mcp/index.ts）。

2. 配置 MCP Server

本地进程（stdio）

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["node", "/path/to/server/index.js"],
      "environment": { "API_KEY": "sk-..." },
      "enabled": true,
      "timeout": 30000,
    },
  },
}

字段（src/config/config.ts）：

字段	说明
`type`	`"local"`
`command`	命令 + 参数数组
`environment`	子进程额外 env（叠加 `process.env`）
`enabled`	`false` 跳过连接
`timeout`	请求超时 ms（默认 30000）

远程 OAuth Server

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "transport": "streamable-http",
      "url": "https://mcp.example.com/api",
      "enabled": true,
      "timeout": 30000,
    },
  },
}

字段（src/config/config.ts）：

字段	说明
`url`	MCP Server HTTP(S) 地址
`transport`	远程 MCP transport；只能是 `streamable-http` 或 `sse`
`headers`	Server 要求的非认证路由或租户请求头
`oauth`	`McpOAuth \| false`；远程 server 默认启用 OAuth
`oauth.clientId`	静态 client ID（跳过动态注册）
`oauth.clientSecret`	client secret
`oauth.scope`	OAuth scope

3. 已支持的 MCP 能力

能力	状态
Tools (`listTools` + `callTool`)	完整
Prompts (`listPrompts` + `getPrompt`)	完整
Resources (`listResources` + `readResource`)	完整
`ToolListChanged` 通知	支持
StreamableHTTP / SSE / stdio transports	通过显式配置支持
OAuth 2.0 + PKCE	远程默认开启
动态 client 注册 (RFC 7591)	支持

4. OAuth 认证流程

远程服务器返回 UnauthorizedError → 标记 needs_auth。执行：

opencorvus mcp auth <server-name>

OpenCorvus 本地启 callback server，打开浏览器跳转授权，code 交换 token 后持久化到解析后的 OpenCorvus data 目录下的 mcp-auth.json。

查询状态：

opencorvus mcp list

清除认证：

opencorvus mcp logout <server-name>

5. 典型配置示例

本地 Filesystem Server：

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
    },
  },
}

远程 OAuth Server：

{
  "mcp": {
    "remote-tools": {
      "type": "remote",
      "transport": "streamable-http",
      "url": "https://mcp.example.com/rpc",
    },
  },
}

禁用某个已配置的 Server：

{ "mcp": { "github": { "type": "remote", "transport": "streamable-http", "url": "...", "enabled": false } } }

Parallel Search（可选，无需 API 密钥）

Parallel Search MCP 提供用于网页搜索的 web_search 和提取网页内容的 web_fetch。需要时，将下面的条目合并到项目 .opencorvus/opencorvus.jsonc 的 mcp 对象中，保留其他已有条目：

{
  "mcp": {
    "parallel": {
      "type": "remote",
      "transport": "streamable-http",
      "url": "https://search.parallel.ai/mcp",
      "oauth": false,
      "enabled": true,
    },
  },
}

该端点支持匿名访问，无需 Parallel 账户或 API（Application Programming Interface，应用程序接口）密钥。 oauth: false 关闭此连接的 OAuth 探测。匿名搜索使用 Fast 模式，限流比认证访问更严格；具体限制和认证方式以服务商当前说明为准。若服务提示免费档限流，请等待后再试，避免反复重连；更高额度需要向 Parallel 认证。添加此服务不会替换内置搜索工具或其他已配置的服务器。

在该项目目录运行 opencorvus mcp list，确认 parallel 已连接。然后在新会话中，要求 agent 使用 Parallel 的 web_search 搜索一个公开主题，再用 web_fetch 读取搜索结果中的一个 URL。检查两个工具是否都返回有用内容；仅显示已连接不能证明搜索与网页抓取均可用。不需要此服务时不添加该配置，或将其 enabled 设为 false。

6. 连接状态

状态	含义
`connected`	连接成功
`disabled`	`enabled: false` 或手动断开
`failed`	连接失败（详见 `error`）
`needs_auth`	需要 OAuth
`needs_client_registration`	服务器不支持动态注册，需提供 `clientId`

默认超时 30000ms（src/mcp/index.ts）；可由 timeout 字段或全局 experimental.mcp_timeout 调整。