MCP 集成

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，它让 AI 模型能够安全地连接和使用外部工具。Karma One 全面支持 MCP 协议，内置了多个 MCP 服务器，同时允许你接入自定义的 MCP 服务器来扩展 AI 的能力边界。

什么是 MCP

简单来说，MCP 就像是 AI 的"USB 接口"——它定义了一套标准的方式，让 AI 模型可以：

调用工具 — 执行搜索、发邮件、操作文件等具体动作
读取资源 — 访问知识库、数据库、文件系统中的信息
遵循提示模板 — 按照预设的模式处理特定任务

MCP 由 Anthropic 提出并开源，正在成为 AI 工具连接的行业标准。

Karma One 内置的 MCP 服务器

Karma One 预集成了以下 MCP 服务器，开箱即用：

| MCP 服务器 | 提供的能力 | 说明 | |------------|-----------|------| | Playwright | 浏览器自动化 | 网页导航、截图、表单操作 | | Chrome DevTools | 浏览器调试 | 性能分析、DOM 检查、网络监控 | | File System | 文件操作 | 沙箱内的文件读写和管理 | | Bubble File Search | 知识库检索 | 文件上传、解析、向量搜索 | | Tool Gateway | 系统集成 | macOS 原生功能、云端工具、多媒体生成 |

MCP 工具调用流程

当你在对话中提出一个需要使用工具的请求时，整个流程如下：

用户请求 → AI 分析意图 → 选择合适的 MCP 工具 → 发送工具调用请求
    ↓
MCP 服务器执行操作 → 返回结果 → AI 整合结果 → 回复用户

具体步骤：

意图识别 — AI 理解你的请求需要什么工具
工具选择 — 从可用的 MCP 工具中选择最合适的
参数构造 — 根据你的请求自动填充工具参数
权限检查 — 验证当前权限设置是否允许此操作
执行调用 — MCP 服务器执行具体操作
结果返回 — AI 将工具的返回结果整合为自然语言回复

权限控制

Karma One 提供三级权限模式来管理 MCP 工具的使用：

| 权限模式 | 工具调用行为 | 适用场景 | |----------|-------------|----------| | 自动模式 | AI 自主决定是否调用工具，无需确认 | 日常使用、信任场景 | | 确认模式 | 每次工具调用前请求用户确认 | 敏感操作、初次使用 | | 禁用模式 | 不调用任何外部工具 | 纯对话场景 |

提示：涉及发送邮件、删除文件等不可逆操作时，即使在自动模式下，Karma One 也会提前告知你将要执行的操作。

常见 MCP 工具分类

文件操作

帮我读取沙箱中的 /home/user/data.csv 文件

文件读写和编辑
目录浏览和管理
文件上传和下载

知识库搜索

在我的知识库中搜索关于"退款政策"的内容

向量语义搜索
支持多种文档格式
跨多个知识库联合检索

浏览器控制

打开这个网址并帮我填写表单

Playwright 驱动的完整浏览器控制
页面截图和可访问性快照
性能分析和网络监控

系统命令

在沙箱终端里运行 python script.py

Shell 命令执行
包管理（npm、pip）
进程管理

macOS 原生集成

帮我截个屏然后发个系统通知

截图、剪贴板、通知
日历事件管理
邮件收发
Safari 控制
Finder 文件管理

自定义 MCP 服务器

如果你是开发者，可以配置自己的 MCP 服务器来扩展 Karma One 的能力。

配置方式

在 Karma One 项目设置中，你可以添加自定义 MCP 服务器的连接信息：

服务器地址 — MCP 服务器的 URL 或本地路径
传输方式 — 支持 stdio（本地进程）和 SSE（远程服务）
认证信息 — 如果服务器需要认证

MCP 服务器开发

一个最简单的 MCP 服务器示例：

使用 @modelcontextprotocol/sdk 创建服务器
↓ 定义工具（名称、描述、参数 schema）
↓ 实现工具处理函数
↓ 启动服务器（stdio 或 HTTP+SSE）

开发要点：

工具的 description 要清晰，AI 依赖它来理解工具用途
参数使用 JSON Schema 定义，类型信息越完整越好
返回结果建议是结构化的文本或 JSON
做好错误处理，返回有意义的错误信息

调试与排查

如果 MCP 工具调用没有按预期工作：

检查权限设置 — 确认当前权限模式允许工具调用
查看工具列表 — 确认目标工具在可用列表中
检查连接状态 — 自定义 MCP 服务器是否正常运行
查看错误信息 — AI 会在工具调用失败时报告错误原因

注意事项

MCP 工具调用会消耗额外的 Token，复杂的工具链可能增加响应时间
自定义 MCP 服务器的安全性由你自己负责
某些 MCP 工具需要特定的运行环境（如 macOS 工具仅在 Mac 上可用）
MCP 协议仍在快速演进中，建议关注官方更新

提示：你可以在对话中问 Karma One "你现在有哪些工具可以用？"来查看当前可用的 MCP 工具列表。