Fedramp Docs MCP

🚀 FedRAMP Docs MCP Server

The FedRAMP Docs MCP Server is a Custom Model Context Protocol (MCP) server that enables querying of the FedRAMP/docs repository using FRMR-aware tooling. It scans FRMR JSON datasets and supporting markdown guidance, provides structured tools for analysis, and can optionally clone and cache the upstream repository for you.

🚀 Quick Start

Prerequisites

• Node.js 18 or higher
• npm 8 or higher

Local Development

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Run the server:

node dist/index.js

Global Installation

To install globally and use the fedramp-docs-mcp command:

npm install -g .
fedramp-docs-mcp

Note: Global installation is required if you want to use fedramp-docs-mcp as the command in MCP client configurations (Claude Desktop, Goose, etc.). Alternatively, you can use the full path to the built server: node /path/to/fedramp-docs-mcp/dist/index.js

During startup, the server ensures a FedRAMP/docs repository is available, indexes FRMR JSON and markdown content, and then begins serving requests on MCP stdio.

✨ Features

• Auto-detects FRMR JSON files (KSI, MAS, VDR, SCN, FRD, ADS) and builds typed metadata.
• Extracts KSI entries, flattened control mappings, and Significant Change references.
• Fast markdown search via an inverted index backed by Lunr with snippets and line numbers.
• Structured diffing between FRMR versions, including per-item change detection.
• Health check, version listing, and curated Significant Change guidance aggregator.

📦 Installation

Local Setup

1. Ensure you have Node.js 18 or higher and npm 8 or higher installed.
2. Clone the repository if you haven't already.
3. Navigate to the project directory in your terminal.
4. Install the project dependencies:

npm install

5. Build the project:

npm run build

6. Start the server:

node dist/index.js

Global Installation

To install the MCP server globally and use the fedramp-docs-mcp command:

npm install -g .
fedramp-docs-mcp

💻 Usage Examples

When using the MCP server with Claude Desktop or other MCP clients, here are some example queries:

Basic Usage

Getting KSI Information:

"List all available FedRAMP documents"
→ Uses list_frmr_documents

"Show me the Key Security Indicators"
→ Uses get_frmr_document with path 'FRMR.KSI.key-security-indicators.json'

"What are the KSI categories?"
→ Parses KSI document to show categories like IAM, CNA, MLA, etc.

Advanced Usage

Searching Documentation:

"Search for information about continuous monitoring"
→ Uses search_markdown with query 'continuous monitoring'

"Find guidance on incident response"
→ Uses search_markdown with query 'incident response'

Working with Controls:

"List all controls mapped in the MAS"
→ Uses list_controls

"Find all markdown files that reference AC-2"
→ Uses grep_controls_in_markdown with control 'AC-2'

Analyzing Changes:

"What's new in the latest KSI release?"
→ Uses list_versions then diff_frmr to compare versions

"Show significant change guidance"
→ Uses get_significant_change_guidance

📚 Documentation

Configuration

Environment variables control repository discovery and indexing behaviour:

Set FEDRAMP_DOCS_PATH if you maintain a local clone. Otherwise, leave it unset and allow the server to create a shallow cached copy.

Keeping Data Up-to-Date

The server includes automatic update checking to keep the FedRAMP docs current:

⚠️ Important Note

The server will automatically check for updates every 24 hours (configurable). If updates are available, they will be fetched automatically on server startup. This ensures you always have recent FedRAMP data without manual intervention.

Manual Updates:

• Use the update_repository tool to force an immediate update.
• Example query in Claude Desktop: "Update the FedRAMP docs repository".
• Useful when you know new requirements or guidance has been published.

Disabling Auto-Update:

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "env": {
        "FEDRAMP_DOCS_AUTO_UPDATE": "false"
      }
    }
  }
}

Custom Update Frequency:

{
  "env": {
    "FEDRAMP_DOCS_UPDATE_CHECK_HOURS": "6"
  }
}

Available Tools

All tools follow the error model described in the product spec and respond with JSON payloads. Key tools include:

• list_frmr_documents — enumerate indexed FRMR JSON documents.
• get_frmr_document — return full JSON and summary for a document.
• list_ksi / get_ksi — filter and inspect Key Security Indicators.
• list_controls — flatten FRMR → NIST control mappings.
• search_markdown / read_markdown — full-text search and retrieval with digests.
• list_versions — collate version metadata by FRMR document type.
• diff_frmr — structured diff of two FRMR datasets using ID-aware comparison.
• grep_controls_in_markdown — locate control references inside markdown guidance.
• get_significant_change_guidance — curated Significant Change references across FRMR + markdown.
• health_check — confirm the server indexed successfully and expose repo path.
• update_repository — force update the cached FedRAMP docs to the latest version.

See src/tools/ for the precise schemas implemented with Zod. Each tool returns either a successful object or an error payload containing code, message, and optional hint.

MCP Client Configuration

The FedRAMP Docs MCP server works with any MCP-compatible client. Here are the setup instructions for popular clients:

Claude Desktop

Add the server to your Claude Desktop configuration file: Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "env": {
        "FEDRAMP_DOCS_PATH": "/path/to/FedRAMP/docs"
      }
    }
  }
}

After updating the config, restart Claude Desktop. The FedRAMP Docs tools will appear in your conversations.

Claude Code CLI

Claude Code is Anthropic's official CLI tool with built-in MCP support.

Method 1: Using CLI (Recommended)

# Add the FedRAMP Docs MCP server
claude mcp add --transport stdio fedramp-docs fedramp-docs-mcp

# With full path
claude mcp add --transport stdio fedramp-docs /path/to/node/bin/fedramp-docs-mcp

# List configured servers
claude mcp list

# Remove if needed
claude mcp remove fedramp-docs

Method 2: Configuration File Claude Code supports three configuration scopes:

1. Project-scoped (recommended for teams): .mcp.json in project root
2. User-scoped: ~/.claude/settings.local.json
3. Project-local: .claude/settings.local.json in project root

Example .mcp.json (project-scoped, can be version-controlled):

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "args": [],
      "env": {
        "FEDRAMP_DOCS_AUTO_UPDATE": "true"
      }
    }
  }
}

With environment variable expansion:

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "args": [],
      "env": {
        "FEDRAMP_DOCS_PATH": "${HOME}/fedramp-docs",
        "FEDRAMP_DOCS_AUTO_UPDATE": "true"
      }
    }
  }
}

Testing:

• Restart Claude Code after configuration changes.
• Use /mcp command for interactive management.
• Use --mcp-debug flag for troubleshooting: claude --mcp-debug.
• Verify with: claude mcp list.

Note: Project-scoped configurations in .mcp.json enable team collaboration by ensuring all team members have access to the same MCP tools.

LM Studio

LM Studio (v0.3.17+) has native MCP support and works great with local models for privacy-focused workflows.

Setup Instructions

1. Open LM Studio and click the Program tab (terminal icon >_) in the right sidebar.
2. Click "Edit mcp.json" under the Install section.
3. Add the FedRAMP Docs configuration:

Config file location:

• macOS/Linux: ~/.lmstudio/mcp.json
• Windows: %USERPROFILE%\.lmstudio\mcp.json

Basic configuration:

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "args": [],
      "env": {
        "FEDRAMP_DOCS_AUTO_UPDATE": "true"
      }
    }
  }
}

Using full path (recommended if command not found):

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "/path/to/node/bin/fedramp-docs-mcp",
      "args": [],
      "env": {
        "FEDRAMP_DOCS_AUTO_UPDATE": "true",
        "FEDRAMP_DOCS_PATH": "/path/to/FedRAMP/docs"
      }
    }
  }
}

4. Save the file - LM Studio will automatically load the server.
5. Start chatting - Open a chat with any local model.
6. Test it - Ask: "List all FedRAMP FRMR documents".
7. Approve tool calls - LM Studio will show a confirmation dialog before executing each tool.

Note: Requires global installation (npm install -g .) or use the full path to the executable. Find your path with: which fedramp-docs-mcp.

OpenCode

OpenCode is a powerful AI coding agent built for the terminal with native MCP support.

Setup Instructions

1. Create or edit your OpenCode configuration file:

Config file location:

• Global: ~/.config/opencode/opencode.json
• Project: opencode.json (in your project root)

2. Add the FedRAMP Docs MCP server:

Basic configuration:

{
  "mcp": {
    "fedramp-docs": {
      "type": "local",
      "command": ["fedramp-docs-mcp"],
      "enabled": true
    }
  }
}

With full path:

{
  "mcp": {
    "fedramp-docs": {
      "type": "local",
      "command": ["/path/to/node/bin/fedramp-docs-mcp"],
      "enabled": true
    }
  }
}

With environment variables:

{
  "mcp": {
    "fedramp-docs": {
      "type": "local",
      "command": ["fedramp-docs-mcp"],
      "enabled": true,
      "env": {
        "FEDRAMP_DOCS_AUTO_UPDATE": "true",
        "FEDRAMP_DOCS_PATH": "/path/to/FedRAMP/docs"
      }
    }
  }
}

3. Restart OpenCode to load the MCP server.
4. Test it - The FedRAMP tools will be automatically available alongside built-in tools.

Note: MCP servers add to your context, so enable only the ones you need. Use "enabled": false to temporarily disable a server without removing it.

Goose

Goose is Block's open-source AI agent. You can add the FedRAMP Docs MCP server using any of these methods:

Method 1: Via Goose CLI (Recommended)

goose configure

Then select:

1. Add Extension
2. Command-line Extension
3. Enter the following details:
   • Name: FedRAMP Docs
   • Command: fedramp-docs-mcp
   • Timeout: 300

Method 2: Via Goose Desktop App

1. Open Goose Desktop.
2. Click Extensions in the sidebar.
3. Click Add custom extension.
4. Fill in the form:
   • Extension Name: FedRAMP Docs
   • Type: STDIO
   • Command: fedramp-docs-mcp
   • Timeout: 300
   • Environment Variables: (optional)
     • FEDRAMP_DOCS_PATH: /path/to/FedRAMP/docs
     • FEDRAMP_DOCS_AUTO_UPDATE: true

Method 3: Via Config File Edit ~/.config/goose/config.yaml (Linux/macOS) or %USERPROFILE%\.config\goose\config.yaml (Windows):

extensions:
  fedramp-docs:
    name: FedRAMP Docs
    cmd: fedramp-docs-mcp
    enabled: true
    type: stdio
    timeout: 300
    envs:
      FEDRAMP_DOCS_PATH: "/path/to/FedRAMP/docs"  # optional
      FEDRAMP_DOCS_AUTO_UPDATE: "true"            # optional

After configuration, restart Goose or reload extensions. You can test by asking: "What FedRAMP tools are available?"

Note: Goose's MCP support is still maturing and may have issues discovering tools from stdio servers. If you experience problems with tool discovery, consider using Claude Desktop, Claude Code CLI, LM Studio, or OpenCode instead.

MCP Inspector (Debugging)

For debugging and testing the server directly:

npx @modelcontextprotocol/inspector node dist/index.js

🔧 Technical Details

Development

Running in Development Mode

Use tsx for rapid iteration without building:

npm run dev

This runs the TypeScript source directly, automatically recompiling on changes.

Running Tests

The repository includes Vitest-based unit and contract tests with small fixtures:

npm test

Tests set FEDRAMP_DOCS_PATH to tests/fixtures/repo, ensuring the indexer, search, and diff logic run deterministically without needing the real FedRAMP repo.

Code Structure

The codebase uses:

• TypeScript 5.4+ with strict mode enabled.
• ES Modules ("type": "module" in package.json).
• Node.js module resolution (moduleResolution: "NodeNext").
• Zod for runtime schema validation.
• MCP SDK v1.20+ for server implementation.

Project Structure

src/
  index.ts                 # MCP bootstrap
  repo.ts                  # repo discovery and cloning
  indexer.ts               # FRMR + markdown indexing logic
  frmr.ts                  # FRMR-centric helpers
  search.ts                # markdown search + aggregations
  diff.ts                  # structured FRMR diff engine
  tools/                   # individual MCP tool handlers

Fixtures live under tests/fixtures, while Vitest specs reside in tests/.

Troubleshooting

Build Errors

Error: Cannot find module '@modelcontextprotocol/sdk' Ensure you have the correct SDK version installed:

npm install @modelcontextprotocol/sdk@^1.20.0

Error: Module not found or import errors The project uses ES modules with NodeNext resolution. Make sure you're using Node.js 18+ and that your TypeScript configuration matches:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Runtime Errors

Error: REPO_CLONE_FAILED The server couldn't clone the FedRAMP docs repository. Check:

• Network connectivity.
• Set FEDRAMP_DOCS_PATH to an existing local clone, or
• Ensure FEDRAMP_DOCS_ALLOW_AUTO_CLONE=true (default).

Server starts but no tools appear Verify the build completed successfully:

npm run build
ls dist/  # Should contain index.js, tools/, etc.

Development Issues

TypeScript errors about missing types Install all development dependencies:

npm install

Required type packages:

• @types/node
• @types/fs-extra
• @types/lunr
• @types/glob

📄 License

No license information provided in the original document.