Aalis.

外观

plugin-mcp-client — MCP 协议客户端桥 ​

包名: @aalis/plugin-mcp-client源码: packages/plugin-mcp-client/src/index.ts

概述 ​

作为 MCP (Model Context Protocol) client，通过 stdio 连接外部 MCP server（如 @modelcontextprotocol/server-github、server-filesystem、server-playwright 等），把这些 server 暴露的 tools 注册进 Aalis 的 ToolService，供 agent 直接调用外部工具。

总体架构与定位见 docs/plugins/mcp.md。

插件声明 ​

ts
name = '@aalis/plugin-mcp-client'
inject = { required: ['tools'] }

配置 ​

yaml
plugins:
  "@aalis/plugin-mcp-client":
    servers:
      - id: github
        command: npx
        args: ["-y", "@modelcontextprotocol/server-github"]
        env:
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
        enabled: true            # 可省略，默认 true
        visibility: auto         # auto | public | sensitive | restricted（默认 auto，按工具注解分档）

      - id: fs
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
        visibility: restricted   # 文件系统访问视为受限，须被 owner/委托授予
字段类型默认值说明
serversarray[]MCP 服务器列表：通过 stdio 连接的 MCP 服务器。每条目至少需要 id 与 command；安全级别按需调整。

行为 ​

  • 每个 server 是一个独立子进程，stdio 传输。
  • 工具名映射为 mcp_<server-id>_<tool-name>：[a-zA-Z0-9_-] 以外的字符替换为 _，连续下划线合并为一个，超过 64 字符截断（OpenAI 工具名限制）。
  • 工具分组：mcp:<server-id> —— 可在 platform 配置中按需启用/禁用。
  • inputSchema 顶层非 type: 'object' 时自动包装为 { input: schema }。
  • 每个 server 连接成功后，经 ctx.onDispose 注册 client.close()；插件 dispose 时关闭所有已连接的 server，关闭时抛出的错误被忽略，仅记 debug 日志。
  • 远端工具的返回文本经 wrapUntrustedContent 套上不可信内容边界；返回 isError 时不套边界，加 MCP 工具返回错误: 前缀返回。
  • 插件另外注册 mcp:_meta 分组下的两个自服务工具：mcp_list_servers（public，只读列出已配置 server 的 id / command / enabled / visibility）和 mcp_set_server_enabled（restricted，切换已有条目的 enabled 并持久化，插件经 bounce 后生效）。不提供新增 server 的工具；未配置任何有效 server 时只注册这两个。

安全注意事项 ​

  • 外部 server 是不受信任的第三方进程。默认 auto 按注解分档、未知即 restricted（失败关闭）； 只有确认全部工具都只读的 server，才应显式放宽为 public（最低等级 0）。
  • Aalis 自身的能力闸仍然生效：restricted 工具默认要求触发者等级 >= 2，sensitive 工具默认要求等级 >= 1，owner 不受等级限制；等级不足时，须有临时能力委托才能放行。

依赖 ​

  • @modelcontextprotocol/sdk ^1.0.4
  • inject.required: tools

已知限制 ​

  • 仅支持 stdio transport，SSE / HTTP client 暂未实现。
  • 单个 server 连接失败不会阻止插件或 Aalis 启动，也不影响其它 server：错误只写进日志（连接 MCP server "<id>" 失败: …），该 server 的工具不会注册。