# radius-mcp-server

A local MCP (Model Context Protocol) server that gives AI assistants everything they need to know about [Radius](https://radapp.io):

- **Docs** — full-text search and page reads over the official documentation ([docs.radapp.io](https://docs.radapp.io/)), sourced from a local cache of [radius-project/docs](https://github.com/radius-project/docs).
- **Source** — full-text search and file reads over [radius-project/radius](https://github.com/radius-project/radius): Go source, architecture docs, design notes, specs, and TypeSpec/Bicep type definitions.

It needs no local setup: on first use it clones shallow, read-only caches of both repos for itself (see [Data sources](#data-sources) below).

## Tools

| Tool | Description |
| --- | --- |
| `radius_docs_search` | Full-text search over the Radius docs |
| `radius_docs_read` | Read one docs page (by URL, URL path, or slug) as clean markdown |
| `radius_docs_list` | Browse doc sections / list pages in a section |
| `radius_docs_sync` | Refresh the local docs cache from GitHub |
| `radius_source_search` | Full-text (or regex) search over the Radius source repo |
| `radius_source_read` | Read a file from the Radius source repo |
| `radius_source_list` | List a directory in the Radius source repo |
| `radius_source_sync` | Refresh the managed source cache from GitHub |

## Quick start (once published to npm)

Most MCP clients just need to be told to run `npx -y radius-mcp-server`. See [Connecting it to an MCP client](#connecting-it-to-an-mcp-client) for exact config per tool. Requires [Node.js](https://nodejs.org/) 18+ and `git` on `PATH`.

## Data sources

| | Source | Local cache |
| --- | --- | --- |
| Docs | `github.com/radius-project/docs` | `~/.radius-mcp-server/cache/docs-repo` (override with `RADIUS_DOCS_CACHE`) |
| Source | `github.com/radius-project/radius` | `~/.radius-mcp-server/cache/radius-repo` (override with `RADIUS_REPO_CACHE`) |

Both are shallow (`--depth 1`) clones made on first use and left in place across runs; call `radius_docs_sync` / `radius_source_sync` to pull the latest.

If you already have a local `radius-project/radius` checkout you'd rather use instead of a managed clone — e.g. you're working in it directly — point `RADIUS_REPO_PATH` at it (or run this server from a directory with a sibling `radius/` folder, which is auto-detected). When set, that checkout is treated as yours to manage; `radius_source_sync` becomes a no-op and the tools just read from it as-is.

## Connecting it to an MCP client

All of these assume the package is published; swap `npx -y radius-mcp-server` for `node /absolute/path/to/radius-mcp-server/dist/index.js` to point at a local build instead (see [Development](#development)).

### Claude Code

```bash
claude mcp add radius -- npx -y radius-mcp-server
```

Or add manually to `.mcp.json` (project-scoped) or `~/.claude.json` (user-scoped):

```json
{
  "mcpServers": {
    "radius": {
      "command": "npx",
      "args": ["-y", "radius-mcp-server"]
    }
  }
}
```

Restart Claude Code (or run `/mcp` to check connection status) and the `radius_*` tools will be available.

### Claude Desktop

Add the same block to your Claude Desktop config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "radius": {
      "command": "npx",
      "args": ["-y", "radius-mcp-server"]
    }
  }
}
```

Restart Claude Desktop to pick up the new server.

### VS Code (GitHub Copilot Chat)

Add to `.vscode/mcp.json` in your workspace (or via "MCP: Open User Configuration" for a user-wide install). Note the top-level key is `servers`, not `mcpServers`:

```json
{
  "servers": {
    "radius": {
      "command": "npx",
      "args": ["-y", "radius-mcp-server"]
    }
  }
}
```

VS Code will prompt to start the server the first time it's used; check its status via the MCP Servers view.

### GitHub Copilot coding agent

In the repository's **Settings → Copilot → Coding agent → MCP configuration**, add:

```json
{
  "mcpServers": {
    "radius": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "radius-mcp-server"],
      "tools": ["*"]
    }
  }
}
```

`type` and `tools` are required by Copilot coding agent's schema (unlike the other clients above). See [GitHub's MCP docs](https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp) if you want to allowlist specific tools instead of `["*"]`.

### Other clients (Cursor, Windsurf, ...)

Most other MCP-capable tools follow the same `mcpServers` convention as Claude Desktop above — check the client's docs for the exact config file location.

## Publishing to npm

To publish a new version (maintainers only):

```bash
npm login                     # once, if not already logged in
npm run build                 # or rely on the prepublishOnly hook
npm version patch             # or minor / major — bumps package.json + tags
npm publish                   # prepublishOnly runs the build automatically
git push --follow-tags
```

`npm publish` is public and effectively permanent (npm blocks re-publishing a given version, and unpublishing after 72h is restricted) — double-check `package.json`'s `version` and the tarball contents (`npm pack --dry-run`) before running it.

## Development

```bash
npm install
npm run build   # one-off build
npm run dev     # tsc --watch
npm start       # run the built server directly on stdio (Ctrl+C to stop)
```

Re-run `npm run build` (or use `npm run dev` in the background) after editing anything in `src/`, then restart the server in your MCP client to pick up changes.