金大哥 - fedramp-docs-mcp MCP 详情

article

README

🚀 FedRAMP Docs MCP Server

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

🚀 快速开始

本地开发

安装依赖：

npm install

构建项目：

npm run build

运行服务器：

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 支持三种配置范围：

项目范围（推荐用于团队）：项目根目录下的 .mcp.json。
用户范围：~/.claude/settings.local.json。
项目本地：项目根目录下的 .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，与本地模型配合使用可实现注重隐私的工作流程。

设置说明

打开 LM Studio，点击右侧边栏中的 Program 标签（终端图标 >_）。
点击 "Edit mcp.json"，位于安装部分下方。
添加 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"
      }
    }
  }
}

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

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

OpenCode

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

设置说明

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

配置文件位置：

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

添加 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"
      }
    }
  }
}

重启 OpenCode 以加载 MCP 服务器。
测试 - FedRAMP 工具将与内置工具一起自动可用。

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

Goose

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

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

goose configure

然后选择：

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

方法 2：通过 Goose 桌面应用

打开 Goose 桌面应用。
点击侧边栏中的 Extensions。
点击 Add custom extension。
填写表单：
- 扩展名称：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

fedramp-docs-mcp

README

🚀 FedRAMP Docs MCP Server

🚀 快速开始

本地开发

全局安装

✨ 主要特性

📦 安装指南

前提条件

💻 使用示例

基础用法

📚 详细文档

配置

保持数据最新

可用工具

MCP 客户端配置

Claude Desktop

Claude Code CLI

方法 1：使用 CLI（推荐）

方法 2：配置文件

LM Studio

设置说明

OpenCode

设置说明

Goose

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

方法 2：通过 Goose 桌面应用

方法 3：通过配置文件

MCP 检查器（调试）

🔧 技术细节

开发模式运行

运行测试

代码结构

项目结构

📄 许可证

🔍 演示

❓ 故障排除

构建错误

运行时错误

开发问题

运行方式说明

托管运行

本地运行 / 其它方式