Fedramp Docs MCP

🚀 FedRAMP Docs MCP Server

FedRAMP Docs MCP Server 是一个自定义模型上下文协议（MCP）服务器，它使 FedRAMP/docs 仓库可通过支持 FRMR 的工具进行查询。该服务器会扫描 FRMR JSON 数据集和配套的 Markdown 指南，提供结构化工具进行分析，还可选择为你克隆并缓存上游仓库。

🚀 快速开始

本地开发

1. 安装依赖：

npm install

2. 构建项目：

npm run build

3. 运行服务器：

node dist/index.js

全局安装

若要全局安装并使用 fedramp-docs-mcp 命令，可执行以下操作：

npm install -g .
fedramp-docs-mcp

注意：如果你想在 MCP 客户端配置（如 Claude Desktop、Goose 等）中使用 fedramp-docs-mcp 作为命令，则需要进行全局安装。或者，你也可以使用构建后服务器的完整路径：node /path/to/fedramp-docs-mcp/dist/index.js。

服务器启动时会确保 FedRAMP/docs 仓库可用，对 FRMR JSON 和 Markdown 内容建立索引，然后开始在 MCP 标准输入输出上处理请求。

✨ 主要特性

• 自动检测 FRMR JSON 文件（KSI、MAS、VDR、SCN、FRD、ADS）并构建类型化元数据。
• 提取 KSI 条目、扁平化的控制映射和重大变更引用。
• 通过由 Lunr 支持的倒排索引实现快速 Markdown 搜索，支持代码片段和行号显示。
• 对 FRMR 版本进行结构化差异比较，包括逐项变更检测。
• 提供健康检查、版本列表和精心整理的重大变更指南聚合器。

📦 安装指南

前提条件

• Node.js 18 或更高版本
• npm 8 或更高版本

💻 使用示例

基础用法

当使用 MCP 服务器与 Claude Desktop 或其他 MCP 客户端时，以下是一些示例查询：

获取 KSI 信息：

"List all available FedRAMP documents"
→ 使用 list_frmr_documents

"Show me the Key Security Indicators"
→ 使用 get_frmr_document，路径为 'FRMR.KSI.key-security-indicators.json'

"What are the KSI categories?"
→ 解析 KSI 文档以显示类别，如 IAM、CNA、MLA 等。

搜索文档：

"Search for information about continuous monitoring"
→ 使用 search_markdown，查询词为 'continuous monitoring'

"Find guidance on incident response"
→ 使用 search_markdown，查询词为 'incident response'

处理控制项：

"List all controls mapped in the MAS"
→ 使用 list_controls

"Find all markdown files that reference AC-2"
→ 使用 grep_controls_in_markdown，控制项为 'AC-2'

分析变更：

"What's new in the latest KSI release?"
→ 先使用 list_versions，再使用 diff_frmr 比较版本

"Show significant change guidance"
→ 使用 get_significant_change_guidance

📚 详细文档

配置

环境变量可控制仓库发现和索引行为：

变量	默认值	描述
FEDRAMP_DOCS_PATH	~/.cache/fedramp-docs	现有 FedRAMP/docs 检出路径。
FEDRAMP_DOCS_REMOTE	https://github.com/FedRAMP/docs	克隆时使用的远程仓库。
FEDRAMP_DOCS_BRANCH	main	克隆时检出的分支。
FEDRAMP_DOCS_ALLOW_AUTO_CLONE	true	路径缺失时自动克隆。
FEDRAMP_DOCS_AUTO_UPDATE	true	自动检查并获取仓库更新。
FEDRAMP_DOCS_UPDATE_CHECK_HOURS	24	自动更新检查的时间间隔（启用自动更新时）。
FEDRAMP_DOCS_INDEX_PERSIST	true	将内存中的索引持久化到 ~/.cache/fedramp-docs/index-v1.json。

如果你维护着本地克隆，请设置 FEDRAMP_DOCS_PATH。否则，不设置该变量，让服务器创建一个浅缓存副本。

保持数据最新

服务器包含自动更新检查功能，以确保 FedRAMP 文档保持最新：

自动更新（默认行为）：

• 每 24 小时（可配置），服务器会检查缓存的仓库是否需要更新。
• 如果有更新可用，服务器启动时会自动获取。
• 这确保你无需手动干预即可始终拥有最新的 FedRAMP 数据。

手动更新：

• 使用 update_repository 工具强制立即更新。
• 在 Claude Desktop 中的示例查询："Update the FedRAMP docs repository"。
• 当你知道有新的要求或指南发布时很有用。

禁用自动更新：

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

自定义更新频率：

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

可用工具

所有工具都遵循产品规范中描述的错误模型，并以 JSON 有效负载响应。主要工具包括：

• list_frmr_documents — 枚举已索引的 FRMR JSON 文档。
• get_frmr_document — 返回文档的完整 JSON 和摘要。
• list_ksi / get_ksi — 过滤和检查关键安全指标。
• list_controls — 扁平化 FRMR → NIST 控制映射。
• search_markdown / read_markdown — 全文搜索和带摘要的检索。
• list_versions — 按 FRMR 文档类型整理版本元数据。
• diff_frmr — 使用支持 ID 的比较方法对两个 FRMR 数据集进行结构化差异比较。
• grep_controls_in_markdown — 在 Markdown 指南中定位控制引用。
• get_significant_change_guidance — 整理跨 FRMR 和 Markdown 的重大变更引用。
• health_check — 确认服务器是否成功建立索引并显示仓库路径。
• update_repository — 强制将缓存的 FedRAMP 文档更新到最新版本。

有关使用 Zod 实现的精确架构，请参阅 src/tools/。每个工具要么返回一个成功对象，要么返回一个包含 code、message 和可选 hint 的 error 有效负载。

MCP 客户端配置

FedRAMP Docs MCP 服务器可与任何兼容 MCP 的客户端配合使用。以下是一些最流行和可靠客户端的设置说明。

推荐客户端：

• Claude Desktop - 最成熟的 MCP 集成，工具发现功能出色。
• Claude Code CLI - Anthropic 官方的 CLI 工具，适合终端工作流程。
• LM Studio - 原生支持 MCP，与本地模型配合使用可保障隐私。
• OpenCode - 基于终端的编码代理，支持 MCP。
• Goose - 实验性支持，可能存在工具发现问题。

Claude Desktop

将服务器添加到你的 Claude Desktop 配置文件中：

位置：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

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

更新配置后，重启 Claude Desktop。FedRAMP Docs 工具将出现在你的对话中。

Claude Code CLI

Claude Code 是 Anthropic 官方的 CLI 工具，内置 MCP 支持。

方法 1：使用 CLI（推荐）

# 添加 FedRAMP Docs MCP 服务器
claude mcp add --transport stdio fedramp-docs fedramp-docs-mcp

# 使用完整路径
claude mcp add --transport stdio fedramp-docs /path/to/node/bin/fedramp-docs-mcp

# 列出已配置的服务器
claude mcp list

# 如有需要，移除服务器
claude mcp remove fedramp-docs

方法 2：配置文件

Claude Code 支持三种配置范围：

1. 项目范围（推荐用于团队）：项目根目录下的 .mcp.json。
2. 用户范围：~/.claude/settings.local.json。
3. 项目本地：项目根目录下的 .claude/settings.local.json。

示例 .mcp.json（项目范围，可进行版本控制）：

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

使用环境变量扩展：

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

测试：

• 配置更改后重启 Claude Code。
• 使用 /mcp 命令进行交互式管理。
• 使用 --mcp-debug 标志进行故障排除：claude --mcp-debug。
• 使用 claude mcp list 进行验证。

注意：.mcp.json 中的项目范围配置可确保所有团队成员都能访问相同的 MCP 工具，从而实现团队协作。

LM Studio

LM Studio（v0.3.17+）原生支持 MCP，与本地模型配合使用可实现注重隐私的工作流程。

设置说明

1. 打开 LM Studio，点击右侧边栏中的 Program 标签（终端图标 >_）。
2. 点击 "Edit mcp.json"，位于安装部分下方。
3. 添加 FedRAMP Docs 配置：

配置文件位置：

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

基本配置：

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

使用完整路径（推荐在找不到命令时使用）：

{
  "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. 保存文件 - LM Studio 将自动加载服务器。
5. 开始聊天 - 与任何本地模型打开聊天窗口。
6. 测试 - 询问："List all FedRAMP FRMR documents"。
7. 批准工具调用 - LM Studio 在执行每个工具之前会显示确认对话框。

注意：需要全局安装（npm install -g .）或使用可执行文件的完整路径。使用 which fedramp-docs-mcp 查找路径。

OpenCode

OpenCode 是一个为终端构建的强大 AI 编码代理，原生支持 MCP。

设置说明

1. 创建或编辑你的 OpenCode 配置文件：

配置文件位置：

• 全局：~/.config/opencode/opencode.json
• 项目：项目根目录下的 opencode.json

2. 添加 FedRAMP Docs MCP 服务器：

基本配置：

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

使用完整路径：

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

使用环境变量：

{
  "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. 重启 OpenCode 以加载 MCP 服务器。
4. 测试 - FedRAMP 工具将与内置工具一起自动可用。

注意：MCP 服务器会添加到你的上下文，因此仅启用你需要的服务器。使用 "enabled": false 可暂时禁用服务器而无需移除。

Goose

Goose 是 Block 的开源 AI 代理。你可以使用以下任何方法添加 FedRAMP Docs MCP 服务器：

方法 1：通过 Goose CLI（推荐）

goose configure

然后选择：

1. Add Extension
2. Command-line Extension
3. 输入以下详细信息：
   • 名称：FedRAMP Docs
   • 命令：fedramp-docs-mcp
   • 超时时间：300

方法 2：通过 Goose 桌面应用

1. 打开 Goose 桌面应用。
2. 点击侧边栏中的 Extensions。
3. 点击 Add custom extension。
4. 填写表单：
   • 扩展名称：FedRAMP Docs
   • 类型：STDIO
   • 命令：fedramp-docs-mcp
   • 超时时间：300
   • 环境变量：（可选）
     • FEDRAMP_DOCS_PATH：/path/to/FedRAMP/docs
     • FEDRAMP_DOCS_AUTO_UPDATE：true

方法 3：通过配置文件

编辑 ~/.config/goose/config.yaml（Linux/macOS）或 %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"  # 可选
      FEDRAMP_DOCS_AUTO_UPDATE: "true"            # 可选

配置完成后，重启 Goose 或重新加载扩展。你可以通过询问 "What FedRAMP tools are available?" 进行测试。

注意：Goose 的 MCP 支持仍在不断完善中，可能在从标准输入输出服务器发现工具时存在问题。如果你遇到工具发现问题，可考虑使用 Claude Desktop、Claude Code CLI、LM Studio 或 OpenCode。

MCP 检查器（调试）

若要直接调试和测试服务器，可使用以下命令：

npx @modelcontextprotocol/inspector node dist/index.js

🔧 技术细节

开发模式运行

使用 tsx 进行快速迭代，无需构建：

npm run dev

这将直接运行 TypeScript 源代码，并在代码更改时自动重新编译。

运行测试

仓库中包含基于 Vitest 的单元测试和契约测试，使用小型测试数据：

npm test

测试将 FEDRAMP_DOCS_PATH 设置为 tests/fixtures/repo，确保索引器、搜索和差异比较逻辑能够确定性地运行，而无需使用真实的 FedRAMP 仓库。

代码结构

代码库使用以下技术：

• TypeScript 5.4+，启用严格模式。
• ES 模块（package.json 中的 "type": "module"）。
• Node.js 模块解析（moduleResolution: "NodeNext"）。
• Zod 进行运行时模式验证。
• MCP SDK v1.20+ 用于服务器实现。

项目结构

src/
  index.ts                 # MCP 启动文件
  repo.ts                  # 仓库发现和克隆
  indexer.ts               # FRMR + Markdown 索引逻辑
  frmr.ts                  # 以 FRMR 为中心的辅助函数
  search.ts                # Markdown 搜索 + 聚合
  diff.ts                  # 结构化 FRMR 差异比较引擎
  tools/                   # 各个 MCP 工具处理程序

测试数据位于 tests/fixtures 下，而 Vitest 测试规范位于 tests/ 中。

📄 许可证

文档中未提及相关信息。

🔍 演示

查看 FedRAMP Docs MCP Server 在 Claude Desktop 中的实际运行情况： https://github.com/user-attachments/assets/6c96ace6-cbd8-4479-9aa9-4474643362c4

❓ 故障排除

构建错误

错误：Cannot find module '@modelcontextprotocol/sdk' 确保你安装了正确的 SDK 版本：

npm install @modelcontextprotocol/sdk@^1.20.0

错误：Module not found 或导入错误 项目使用 ES 模块和 NodeNext 解析。确保你使用的是 Node.js 18+，并且 TypeScript 配置匹配：

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

运行时错误

错误：REPO_CLONE_FAILED 服务器无法克隆 FedRAMP 文档仓库。请检查：

• 网络连接。
• 将 FEDRAMP_DOCS_PATH 设置为现有的本地克隆，或者
• 确保 FEDRAMP_DOCS_ALLOW_AUTO_CLONE=true（默认值）。

服务器启动但没有工具显示 验证构建是否成功完成：

npm run build
ls dist/  # 应包含 index.js、tools/ 等。

开发问题

TypeScript 关于缺少类型的错误 安装所有开发依赖项：

npm install

所需的类型包：

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