通过内置 MCP Server 以 HTTP/JSON-RPC 将本地知识库能力暴露给外部 Agent 与工具系统

方案简介

AI LocalBase 内置基础 MCP Server 能力，作为后端内嵌工具服务运行，可供外部 Agent、脚本或工具系统通过 HTTP / JSON-RPC 接入，把本地知识库检索与问答能力作为工具暴露给 Cherry Studio、Claude Desktop、Cursor 等 MCP 客户端。

支持的协议能力包括：initialize、ping、tools/list、tools/call 与初始化通知、工具列表发现、只读/写入/危险工具权限分级、API Key Scope 鉴权、限流、超时与审计日志、危险工具一次性确认机制。

业务工具层面还提供：文档详情、检索调试、结构化查询、评估集生成和重建索引工具；MCP Job 工作流（异步导入、状态查询、取消和最近任务列表）；Agent 友好组合工具（带来源回答、知识库质量检查、检索模式对比、评测样本创建和文档摘要）。

亮点与能力

• HTTP / JSON-RPC MCP 入口（JSON 响应型 Streamable HTTP 子集）
• 只读 / 写入 / 危险工具权限分级，API Key Scope 鉴权
• 限流、超时与审计日志，危险工具一次性确认机制
• MCP 能力自检工具 get_mcp_capabilities
• 异步导入 Job：状态查询、取消和最近任务列表
• Agent 友好组合工具：带来源回答、知识库质量检查、检索模式对比、评测样本创建和文档摘要
• Settings 内置 Cherry Studio、Claude Desktop、Cursor / 通用 HTTP MCP 复制模板

组成与分工

• MCP Server（内置）：后端内嵌工具服务，复用现有知识库、会话、配置与检索服务
• Cherry Studio / Claude Desktop / Cursor：外部 MCP 客户端，通过 HTTP JSON-RPC 调用知识库工具
• API Key（带 mcp:* scope）：MCP 鉴权方式，支持 mcp:read、mcp:upload、mcp:eval、mcp:danger 分级授权

前置要求

MCP 相关环境变量：ENABLE_MCP 是否启用 MCP，默认 false；MCP_BASE_PATH 挂载路径默认 /mcp；MCP_REQUEST_TIMEOUT_SECONDS 请求超时默认 15；MCP_REQUESTS_PER_MINUTE 每分钟限流默认 120。服务器部署时请只在 ENABLE_AUTH=true 后再开启 MCP。

实施步骤

1. 开启 MCP 与认证

在 .env 中设置 ENABLE_MCP 启用 MCP Server，服务器部署时先确保 ENABLE_AUTH=true。

2. 在 Cherry Studio 中配置接入

• 类型：HTTP JSON-RPC（客户端配置中可能显示为 streamableHttp）
• URL：http://127.0.0.1:8080/mcp
• 请求头：
• Content-Type: application/json
• Authorization: Bearer <带 MCP scope 的 API Key>
• Accept: application/json, text/event-stream
• 建议 scope：mcp:read、mcp:upload、mcp:eval；需要删除类工具时再额外授予 mcp:danger

3. 验证工具接入

默认入口为 GET /mcp、GET /mcp/tools、POST /mcp，可通过 get_mcp_capabilities 自检工具验证能力。

使用与配置要点

Docker 前端同源代理支持默认 /mcp，也支持以 /mcp 结尾的嵌套路径，例如 /agent/mcp。如果使用其他自定义路径，需要自行配置外部反向代理，或让 MCP 客户端直接访问后端端口。

更完整的方法、工具列表、鉴权与调用示例见 docs/mcp.md。

注意事项与常见问题

• 当前实现返回 JSON，不发放 MCP 会话 ID，也不提供 SSE 长连接；客户端应同时接受 application/json，不要只声明 text/event-stream
• 旧 MCP Token 等价 MCP 全权限，已废弃且默认不允许鉴权；仅迁移旧客户端时临时设置 ENABLE_MCP_LEGACY_TOKEN=true
• 服务器部署时请只在 ENABLE_AUTH=true 后再开启 MCP

优缺点

• ✓ 支持 Cherry Studio、Cla
• ✓ 权限分级与限流审计完善
• ✕ 不发放 MCP 会话 ID，也不提供 S
• ✕ 默认 ENABLE_MCP 为 fals

出处

本方案挖掘自开源项目 veyliss/ai-localbase，方案内容与实施命令均来自其 README 原文。