FedRAMP Docs MCP Server

自定义模型上下文协议（MCP）服务器，使FedRAMP/docs存储库可以通过FRMR感知工具进行查询。该服务器扫描FRMR JSON数据集和支持的markdown指南，提供结构化的分析工具，并可选择克隆和缓存上游存储库。

演示

使用Claude Desktop查看FedRAMP Docs MCP Server的实际操作：

https://github.com/user-attachments/assets/6c96ace6-cbd8-4479-9aa9-4474643362c4

预备条件

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

功能

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

开始使用

本地开发

1. 安装依赖项：

npm install

2. 构建项目：

npm run build

3. 运行服务器：

node dist/index.js

全局安装

要全局安装并使用fedramp-docs-mcp命令：

npm install -g .
fedramp-docs-mcp

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

启动时，服务器确保FedRAMP/docs存储库可用，索引FRMR JSON和markdown内容，然后开始通过MCP标准I/O提供请求。

配置

环境变量控制存储库发现和索引行为：

变量	默认值	描述
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中："更新FedRAMP文档存储库"
• 当您知道已发布新的要求或指南时非常有用。

禁用自动更新：

{
  "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文档到最新版本。

参见src/tools/了解使用Zod实现的具体模式。每个工具返回成功的对象或包含code、message和可选hint的error负载。

使用示例

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

获取KSI信息：

"列出所有可用的FedRAMP文档"
→ 使用list_frmr_documents

"显示关键安全指标"
→ 使用get_frmr_document，路径为'FRMR.KSI.key-security-indicators.json'

"KSI类别是什么？"
→ 解析KSI文档以显示IAM、CNA、MLA等类别。

搜索文档：

"搜索有关持续监控的信息"
→ 使用search_markdown，查询词为'continuous monitoring'

"查找关于事件响应的指南"
→ 使用search_markdown，查询词为'incident response'

处理控制：

"列出MAS中映射的所有控制"
→ 使用list_controls

"查找引用AC-2的所有markdown文件"
→ 使用grep_controls_in_markdown，控制为'AC-2'

分析变化：

"最新KSI发布有什么新内容？"
→ 使用list_versions，然后使用diff_frmr比较版本

"显示重大变更指南"
→ 使用get_significant_change_guidance

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 并点击右侧边栏的“程序”标签（终端图标 >_）
2. 点击“编辑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. 测试它 - 询问：“列出所有FedRAMP FRMR文档”
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. 添加扩展
2. 命令行扩展
3. 输入以下详细信息：
   • 名称： FedRAMP Docs
   • 命令： fedramp-docs-mcp
   • 超时： 300

方法2：通过Goose桌面应用

1. 打开Goose Desktop
2. 点击侧边栏的“扩展”
3. 点击“添加自定义扩展”
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或重新加载扩展。您可以通过询问：“有哪些FedRAMP工具可用？”来测试。

注意： Goose的MCP支持仍在成熟中，可能会遇到从stdio服务器发现工具的问题。如果遇到工具发现问题，请考虑使用Claude Desktop、Claude Code CLI、LM Studio或OpenCode。

MCP Inspector（调试）

用于调试和直接测试服务器：

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模块（"type": "module"在package.json中）
• 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/下。

故障排除

构建错误

错误：无法找到模块'@modelcontextprotocol/sdk'

确保安装了正确的SDK版本：

npm install @modelcontextprotocol/sdk@^1.20.0

错误：模块未找到或导入错误

该项目使用ES模块和NodeNext解析。确保您使用的是Node.js 18+，并且您的TypeScript配置匹配：

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

运行时错误

错误：REPO_CLONE_FAILED

服务器无法克隆FedRAMP文档存储库。检查：

• 网络连接
• 设置FEDRAMP_DOCS_PATH为现有的本地克隆，或