# FedRAMP Rules MCP Server

An [MCP](https://modelcontextprotocol.io) server that answers questions about the
**FedRAMP Consolidated Rules for 2026**. It bundles the official markdown corpus
from [`fedramp/2026-markdown`](https://github.com/fedramp/2026-markdown) and
exposes it to LLM agents through search and retrieval tools, so answers come from
the authoritative source text — with citations to file paths and rule IDs.

The content is **vendored at a pinned commit** (see `scripts/sync_content.py`), so
the server works offline, responds instantly, and gives stable, reproducible
answers. Re-run the sync script to update.

## Tools

| Tool | Description |
| --- | --- |
| `fedramp_search` | BM25 full-text search across the whole corpus. Optional `section` prefix filter; returns ranked snippets with paths. Identical-content hits (the `reference/` a/b/c/d tracks) are merged. |
| `fedramp_get_document` | Return the full markdown of one document by its repo-relative `path`. |
| `fedramp_list_documents` | Browse the corpus tree, optionally filtered to a section. |
| `fedramp_get_rule` | Retrieve a rule by ID (`FRC-CSO-FCP`, `VDR-CSO-CVE`, `KSI-IAM-01`, …) or a NIST control ID (`AC-20`, `SI-4`), with every location it appears. Case-insensitive. |
| `fedramp_get_definition` | Look up a defined term by name, alias, or FRD ID (`FRD-SGC`). Case-insensitive. |

There is also a `fedramp://source` resource exposing the source repo, pinned
commit, and sync timestamp for provenance.

## Install

Requires [uv](https://docs.astral.sh/uv/) and Python 3.12+. The rules corpus is
bundled in the package, so no clone or extra download is needed — install
straight from GitHub:

```bash
uv tool install git+https://github.com/dan-fedramp/fedramp-rules-mcp
```

Then run the server over stdio with:

```bash
fedramp-rules-mcp
```

Or run it without installing (uv fetches, builds, and runs in one step):

```bash
uvx --from git+https://github.com/dan-fedramp/fedramp-rules-mcp fedramp-rules-mcp
```

> Pin to a specific version by appending a ref, e.g.
> `git+https://github.com/dan-fedramp/fedramp-rules-mcp@main`.

## Connecting a client

### Claude Code

```bash
claude mcp add fedramp-rules -- uvx --from git+https://github.com/dan-fedramp/fedramp-rules-mcp fedramp-rules-mcp
```

### Claude Desktop / other stdio clients

Add to the client's MCP server config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "fedramp-rules": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/dan-fedramp/fedramp-rules-mcp",
        "fedramp-rules-mcp"
      ]
    }
  }
}
```

If you installed with `uv tool install`, you can instead set `"command": "fedramp-rules-mcp"` with no `args`.

### MCP Inspector

```bash
npx @modelcontextprotocol/inspector uvx --from git+https://github.com/dan-fedramp/fedramp-rules-mcp fedramp-rules-mcp
```

## Development

To work on the server from a local clone:

```bash
git clone https://github.com/dan-fedramp/fedramp-rules-mcp
cd fedramp-rules-mcp
uv sync                          # install dependencies
uv run python -m pytest -q       # run the smoke tests
uv run fedramp-rules-mcp         # run the server from source
```

## Updating the bundled rules

```bash
# vendor a specific commit or branch, then commit the result
uv run python scripts/sync_content.py --ref <commit-sha-or-branch>
```

## How it works

- `scripts/sync_content.py` downloads the repo tarball and extracts every `.md`
  file into `src/fedramp_rules_mcp/content/`, writing `_meta.json` for provenance.
- `content.py` loads the corpus once, strips YAML frontmatter, and parses the two
  structured artifacts: the glossary in `definitions.md` (`FRD-*` terms) and the
  `??? abstract "<ID>"` rule blocks throughout the corpus.
- `search.py` builds an in-memory Okapi BM25 index (no external services); the
  tokenizer preserves hyphenated IDs so rule-ID queries match.
- `server.py` wires the five tools with Pydantic-validated inputs and
  markdown/JSON output.

## Notes

This is an unofficial tool built on public FedRAMP content. It is not affiliated
with or endorsed by FedRAMP or the GSA. Always confirm against the official
source for authoritative guidance.