io.github.sustinbebustin/citadel-mcp

Citadel MCP

A Code Mode MCP server that gives AI coding agents curated, per-stack documentation as typed tools.

Citadel is built to be forked and tailored. The hosted package ships with a small starter set of stacks, but the real value comes from packaging the docs your agents actually need. Each stack is a tiny module — adding one is mostly mechanical.

Getting Started

Requirements

• Node.js v20.19 or a newer latest maintenance LTS version
• npm or pnpm

Install with add-mcp

Install the MCP server for all your coding agents:

npx add-mcp citadel-mcp@latest

Add -y to skip the confirmation prompt and install to all detected agents already in use in the project directory. Add -g to install globally across all projects.

Manual installation

Add the following config to your MCP client:

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

[!NOTE] Using citadel-mcp@latest ensures that your MCP client will always use the latest version of the Citadel MCP server.

MCP Client Configuration

Amp

Using Amp CLI:

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

Or configure manually:

Follow Amp's MCP documentation and apply the standard configuration shown above.

Claude Code

Use the Claude Code CLI to add the Citadel MCP server:

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

Use -s project instead of -s user to scope the install to the current project. Restart Claude Code, then verify with claude mcp list. A working server advertises a single tool named docs.

Codex

Using Codex CLI:

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

Or configure manually:

Follow the MCP setup guide with the standard configuration format:

• Command: npx
• Arguments: -y, citadel-mcp@latest

Cursor

Go to Cursor Settings -> MCP -> New MCP Server. Use the JSON config provided above.

Gemini

Using Gemini CLI:

Project-wide installation:

gemini mcp add citadel npx citadel-mcp@latest

Global installation:

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

VS Code / Copilot

Using VS Code CLI:

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

Or configure manually:

Follow the official VS Code MCP server setup guide and add the Citadel server through VS Code settings.

Warp

Navigate to Settings | AI | Manage MCP Servers and select + Add to register a new MCP server with the following configuration:

• Name: citadel
• Command: npx
• Arguments: -y, citadel-mcp@latest

What you get out of the box

The hosted package includes a starter set of stacks so you can try it immediately:

• Next.js (App Router, Next.js 16)
• React
• Turborepo
• Supabase guides

This list is intentionally small. For the best results, fork this repo and add the stacks your agents care about — your internal libraries, the framework version you actually use, or any docs site that publishes machine-readable markdown. See docs/adding-a-docs-tool.md.

How it works

Citadel is a Code Mode server: instead of advertising one tool per docs source, it advertises a single docs tool. The agent writes one async () => { ... } per turn that calls codemode.<stack>_docs(...) and codemode.<stack>_index() directly, and the server runs that code in a local Node sandbox. N doc fetches collapse into one round-trip.

Each stack contributes two callable tools to the sandbox SDK:

• <stack>_index() — returns the doc index so the agent can pick a valid path
• <stack>_docs({ path }) — fetches that specific doc as markdown

Citadel also exposes a cross-stack ranked search: codemode.docs_search({ query, stacks?, fetch: true }) returns BM25-ranked matches with markdown content attached in a single call.

Documentation

• Using Citadel as an AI agent — playbook for the docs tool, served at runtime as MCP resource citadel://docs/agent-usage. SDK reference, parallel fan-out, error handling, worked examples.
• Adding a docs tool — package a new stack as <stack>_index + <stack>_docs.

Local Development

To run the MCP server locally for development:

1. Clone the repository.
2. Install and build:

    pnpm install
    pnpm build

3. Configure your MCP client to use the local version:

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

   Or with the Claude Code CLI:

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

For development with auto-reload, point the MCP client at tsx and the src entry instead:

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

License

MIT