citadel-mcp

Citadel MCP

一个 Code Mode MCP 服务，为 AI 编码 Agent 提供按技术栈整理的精选文档，并将其作为类型化工具提供。

Citadel 专为分叉并定制而打造。托管软件包提供少量入门技术栈，但真正的价值在于打包 Agent 实际需要的文档。每个技术栈都是一个小型模块——添加一个模块大多只需按部就班地操作。

入门

要求

• Node.js，版本为 v20.19 或更新的最新维护版 LTS
• npm 或 pnpm

使用 add-mcp 安装

为所有编码 Agent 安装 MCP 服务：

npx add-mcp citadel-mcp@latest

添加 -y 可跳过确认提示，并安装到项目目录中所有已检测到且正在使用的 Agent。添加 -g 可将其全局安装到所有项目。

手动安装

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "citadel": {
      "command": "npx",
      "args": ["-y", "citadel-mcp@latest"]
    }
  }
}

说明

使用 citadel-mcp@latest 可确保 MCP 客户端始终使用最新版本的 Citadel MCP 服务。

MCP 客户端配置

amp mcp add citadel -- npx citadel-mcp@latest

claude mcp add -s user citadel -- npx -y citadel-mcp@latest

codex mcp add citadel -- npx citadel-mcp@latest

gemini mcp add citadel npx citadel-mcp@latest

gemini mcp add -s user citadel npx citadel-mcp@latest

code --add-mcp '{"name":"citadel","command":"npx","args":["-y","citadel-mcp@latest"]}'

开箱即用的内容

托管软件包包含一组入门技术栈，供你立即试用：

• Next.js（App Router，Next.js 16）
• React
• Turborepo
• Supabase 指南

此列表有意保持精简。为获得最佳效果，请分叉此仓库并添加 Agent 所需的技术栈——例如你的内部库、实际使用的框架版本，或任何提供机器可读 Markdown 的文档网站。请参阅 docs/adding-a-docs-tool.md。

工作原理

Citadel 是一个 Code Mode 服务：它不会为每个文档来源公布一个工具，而是只公布一个 docs 工具。Agent 每轮会编写一个 async () => { ... }，直接调用 codemode.<stack>_docs(...) 和 codemode.<stack>_index()，服务则会在本地 Node 沙箱中运行这段代码。N 次文档获取会合并为一次往返请求。

每个技术栈都会向沙箱 SDK 提供两个可调用工具：

• <stack>_index() — 返回文档索引，供 Agent 选择有效路径
• <stack>_docs({ path }) — 以 Markdown 格式获取指定文档

Citadel 还提供跨技术栈的排序搜索：codemode.docs_search({ query, stacks?, fetch: true }) 会在一次调用中返回按 BM25 排序且附带 Markdown 内容的匹配结果。

文档

• 将 Citadel 用作 AI Agent — docs 工具的使用指南，运行时通过 MCP 资源 citadel://docs/agent-usage 提供。SDK 参考、并行扇出、错误处理和示例。
• 添加 docs 工具 — 将新的技术栈打包为 <stack>_index + <stack>_docs。

本地开发

要在本地运行 MCP 服务进行开发：

1. 克隆仓库。

2. 安装并构建：

   pnpm install
   pnpm build
   

3. 配置 MCP 客户端以使用本地版本：

   {
     "mcpServers": {
       "citadel-dev": {
         "command": "node",
         "args": ["/absolute/path/to/citadel-mcp/dist/index.js"]
       }
     }
   }
   

   或使用 Claude Code CLI：

   claude mcp add -s user citadel-dev -- node /absolute/path/to/citadel-mcp/dist/index.js
   

要启用自动重新加载进行开发，请将 MCP 客户端指向 tsx 和 src 入口：

claude mcp add -s user citadel-dev -- npx tsx /absolute/path/to/citadel-mcp/src/index.ts

许可证

MIT