io.github.sustinbebustin/citadel-mcp
A growing Citadel of stack-specific docs, served as MCP tools for AI coding agents.
Open source Open in the app JSON README (API)
About
A growing Citadel of stack-specific docs, served as MCP tools for AI coding agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- sustinbebustin
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.2.0
- Stars
- 1
- Last push
- 2026-05-10T03:42:30Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:29
- Updated
- 2026-08-29 04:01:29
- Origin id
io.github.sustinbebustin/citadel-mcp
README
# Citadel MCP
[](https://npmjs.org/package/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](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version
- [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
### Install with add-mcp
Install the MCP server for all your coding agents:
```bash
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:
```json
{
"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
<details>
<summary>Amp</summary>
**Using Amp CLI:**
```bash
amp mcp add citadel -- npx citadel-mcp@latest
```
**Or configure manually:**
Follow [Amp's MCP documentation](https://ampcode.com/manual#mcp) and apply the standard configuration shown above.
</details>
<details>
<summary>Claude Code</summary>
Use the Claude Code CLI to add the Citadel MCP server:
```bash
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`.
</details>
<details>
<summary>Codex</summary>
**Using Codex CLI:**
```bash
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`
</details>
<details>
<summary>Cursor</summary>
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the JSON config provided above.
</details>
<details>
<summary>Gemini</summary>
**Using Gemini CLI:**
Project-wide installation:
```bash
gemini mcp add citadel npx citadel-mcp@latest
```
Global installation:
```bash
gemini mcp add -s user citadel npx citadel-mcp@latest
```
</details>
<details>
<summary>VS Code / Copilot</summary>
**Using VS Code CLI:**
```bash
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.
</details>
<details>
<summary>Warp</summary>
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`
</details>
## 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](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](src/resources/agent-usage.ts) — 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](docs/adding-a-docs-tool.md) — 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:
```bash
pnpm install
pnpm build
```
3. Configure your MCP client to use the local version:
```json
{
"mcpServers": {
"citadel-dev": {
"command": "node",
"args": ["/absolute/path/to/citadel-mcp/dist/index.js"]
}
}
}
```
Or with the Claude Code CLI:
```bash
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:
```bash
claude mcp add -s user citadel-dev -- npx tsx /absolute/path/to/citadel-mcp/src/index.ts
```
## License
MIT