MCP 集成

通过 Model Context Protocol (MCP) 服务器扩展 Alma 功能。

什么是 MCP？

MCP（Model Context Protocol）是一个开放协议，允许 AI 应用与外部服务和数据源交互。通过 MCP 服务器，Alma 可以：

• 访问第三方 API
• 连接数据库
• 与其他工具集成

安装 MCP 服务器

从市场

1. 打开 设置 → MCP
2. 浏览可用服务器
3. 点击 安装

手动添加

1. 打开 设置 → MCP
2. 点击 添加服务器
3. 配置服务器设置

配置

服务器类型

stdio：本地进程

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem"]
}

SSE：远程服务器

{
  "url": "https://example.com/mcp"
}

环境变量

某些服务器需要 API 密钥或其他配置：

{
  "env": {
    "API_KEY": "your-key"
  }
}

使用 MCP 工具

MCP 工具与内置工具一样使用：

1. 安装 MCP 服务器后，其工具自动可用
2. 工具以 serverName__toolName 格式显示
3. AI 可以自动选择使用

为 Alma 声明工具输出安全模式

Alma 会在某些情况下压缩 MCP 工具的大输出，以节省 token。如果某个 MCP 工具的结果必须保持精确不变，可以显式声明。

支持的模式：

• exact：保持结果原样
• compact：允许 Alma 压缩大文本字段
• passthrough：完全跳过压缩

推荐方式：在 MCP 工具的 _meta["alma/outputSafetyMode"] 中声明：

{
  "name": "read_repo_file",
  "description": "精确读取仓库文件内容",
  "_meta": {
    "alma/outputSafetyMode": "exact"
  }
}

兜底方式：在 description 中添加指令：

{
  "name": "read_repo_file",
  "description": "精确读取仓库文件内容 [alma-output-safety: exact]"
}

对于源代码原文、ID、后续步骤要程序化消费的结构化结果，使用 exact。对于日志、搜索结果、网页正文这类允许有损截断的文本，才使用 compact。

流行的 MCP 服务器

服务器	功能
filesystem	文件系统访问
github	GitHub API 集成
postgres	PostgreSQL 数据库访问
slack	Slack 消息发送

故障排除

服务器无法启动

• 检查命令和参数
• 验证依赖是否已安装
• 查看日志获取错误信息

工具不可用

• 确保服务器已启用
• 检查服务器是否成功连接
• 在工具选择器中启用 MCP 工具