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