fedramp-docs-mcp

FedRAMP Docs MCP Server

⚠️ 此项目即将停止维护

此 MCP 服务不再积极开发。FedRAMP 搜索和 FRMR 解析功能正整合到 GRC Clanker 和 myctrl.tools 中，作为实际 GRC 工作流的一部分运行，而不是独立的子进程。

npm 软件包和此代码库仍会保留，供现有用户使用，但这里不会再推出新功能。有关原因和事后总结，请参阅项目说明。

— Ethan（2026-04-15）

免责声明： 这是一个非官方的社区项目，与 FedRAMP 或美国联邦政府无关联，也未获其认可或支持。作者并非 FedRAMP 官方成员。FedRAMP 名称及任何相关标志均为各自所有者的财产。

自定义 Model Context Protocol（MCP）服务，可使用具备 FRMR 感知能力的工具查询 FedRAMP/docs 代码库。此服务会扫描 FRMR JSON 数据集和相关的 Markdown 指南，提供用于分析的结构化工具，并可选择为你克隆和缓存上游代码库。

演示

观看 FedRAMP Docs MCP Server 与 Claude Desktop 搭配使用的演示：

https://github.com/user-attachments/assets/653c3956-0bfb-46c4-9e72-8a6d75e3a80d

文档

其他资源：

• 本地开发 - 从源代码构建
• Docker 设置 - 容器部署
• 安全加固 - 生产环境配置
• 参与贡献 - 如何参与贡献

前置条件

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

功能

• 自动检测全部 12 种 FRMR JSON 文档类型并构建类型化元数据。
• 提取 KSI 条目、扁平化的控制项映射和 Significant Change 引用。
• 通过基于 Lunr 构建的倒排索引快速搜索 Markdown，并提供摘要片段和行号。
• 为 tools/site/content/ 中的 62 个以上 Markdown 文件编制索引（Zensical 静态站点内容）。
• 对 FRMR 版本进行结构化差异比较，包括逐项变更检测。
• 提供健康检查、版本列表和精选的 Significant Change 指南聚合功能。
• Claude 插件，包含斜杠命令、Agent 技能和合规分析师 Agent。
• Docker 支持，按照 2025 年最佳实践进行安全加固。

支持的文档类型

开始使用

本地开发

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

CLI 命令

该软件包包含一些实用的 CLI 命令：

# Show help and usage information
npx fedramp-docs-mcp help

# Install Claude Code plugin
npx fedramp-docs-mcp setup

# Print MCP server configuration for Claude Desktop/Code
npx fedramp-docs-mcp mcp-config

# Start MCP server (used by MCP clients)
npx fedramp-docs-mcp

启动时，服务会确保 FedRAMP/docs 仓库可用，为 FRMR JSON 和 Markdown 内容建立索引，然后开始通过 MCP stdio 提供服务。

配置

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

如果你维护着本地克隆，请设置 FEDRAMP_DOCS_PATH。否则，请保持未设置，让服务创建浅层缓存副本。

保持数据为最新

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

自动更新（默认行为）：

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

手动更新：

• 使用 update_repository 工具立即强制更新
• Claude Desktop 中的查询示例：“更新 FedRAMP 文档仓库”
• 当你知道有新的要求或指导已发布时，此功能很有用

禁用自动更新：

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

自定义更新频率（每 6 小时检查一次）：

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "fedramp-docs-mcp",
      "env": {
        "FEDRAMP_DOCS_UPDATE_CHECK_HOURS": "6"
      }
    }
  }
}

可用工具

该服务提供 21 个工具，按类别组织。所有工具都遵循错误模型，并以 JSON 载荷响应。

文档发现

KSI（关键安全指标）

控制映射

搜索与查找

分析

系统

证据收集建议

get_evidence_examples 工具为每个 KSI 提供社区建议的证据示例。这些建议便于自动化，可展示如何通过 API、CLI 命令和安全工具以编程方式收集合规证据。

**重要提示：**这些并非 FedRAMP 官方指导。请务必通过 FedRAMP 官方文档核实要求。

包含内容

针对 72 个 KSI 指标中的每一项，我们提供：

• 证据类型：API 调用、报告、扫描、日志、配置、文档
• 自动化来源：AWS、Azure、GCP、Okta、Splunk、Terraform、GitHub Actions 等
• 示例命令：可直接使用的 CLI 命令和 API 端点

按主题划分的证据来源示例

使用示例

"What evidence do I need for KSI-IAM-01 (Phishing-Resistant MFA)?"
→ Returns suggested API calls, CLI commands, and artifacts to collect

"Get evidence checklist for the CNA theme"
→ Returns automation sources for all Cloud Native Architecture indicators

请参阅 src/tools/，了解通过 Zod 实现的精确架构。每个工具都会返回成功对象，或包含 code、message 以及可选 hint 的 error 负载。

使用示例

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

获取 KSI 信息：

"List all available FedRAMP documents"
→ Uses list_frmr_documents

"Show me all KSI items for moderate impact systems"
→ Uses filter_by_impact with impact='moderate'

"Give me a summary of the IAM theme requirements"
→ Uses get_theme_summary with theme='IAM'

"What evidence do I need for IAM compliance?"
→ Uses get_evidence_examples with theme='IAM'

搜索文档：

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

"What does 'federal customer data' mean in FedRAMP?"
→ Uses search_definitions with term='federal customer data'

"Get the details for requirement KSI-IAM-01"
→ Uses get_requirement_by_id with id='KSI-IAM-01'

处理控制措施：

"What FedRAMP requirements map to control AY-01?"
→ Uses get_control_requirements with control='AY-01'

"Which control families have the most FedRAMP coverage?"
→ Uses analyze_control_coverage

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

分析变更：

"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

高级查询：仪表板与架构洞察

这些提示词将 FedRAMP 数据与 Claude 的分析能力相结合，帮助你设计合规仪表板和功能：

仪表板架构：

"Using the FedRAMP KSI data, design a compliance dashboard architecture.
What components would I need? How should I structure the data for real-time monitoring?"

"Get all KSI themes and their indicators. Then recommend how to organize
them into a dashboard with drill-down navigation."

可视化设计：

"Analyze the FedRAMP control coverage data. What would be the best
chart types to visualize control family coverage? Suggest a color
scheme for compliance status."

"List the KSIs filtered by impact level. Design a risk heat map
visualization showing low/moderate/high impact requirements."

功能规划：

"Get the evidence checklist from FedRAMP. How would you build a
feature that tracks evidence collection progress with percentage
completion per KSI theme?"

"What are the requirements for AC-2 (Account Management)? Design a
feature that helps users track their implementation status against
these requirements."

数据建模：

"Analyze the structure of KSI indicators and their control mappings.
What database schema would you recommend for a compliance tracking app?"

"Get a theme summary for IAM. How would you model the relationship
between KSIs, NIST controls, and evidence in a graph database?"

高管报告：

"Using the control coverage analysis, design an executive summary
dashboard that shows compliance posture at a glance."

"Analyze all high-impact KSI requirements and create a prioritized
remediation roadmap template."

工具搜索与延迟加载

本 MCP 服务包含 21 个工具，非常适合采用延迟工具加载（也称为工具搜索）。客户端无需预先加载所有工具，而是可以加载一小组必要工具，再通过 search_tools 工具按需发现其余工具。

search_tools 工具

search_tools 工具允许客户端按关键词或类别发现可用工具：

"What tools help with KSI compliance?"
→ search_tools(query="ksi compliance")
→ Returns: list_ksi, get_ksi, filter_by_impact, get_theme_summary, get_evidence_examples

"What analysis tools are available?"
→ search_tools(category="Analysis")
→ Returns: diff_frmr, grep_controls_in_markdown, get_significant_change_guidance

建议始终加载的工具

使用延迟加载时，请始终加载以下 5 个工具：

使用延迟加载配置 Claude API

使用 mcp_toolset 调用 Claude API 时，可以配置延迟加载：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "stdio",
            "command": "fedramp-docs-mcp",
            "name": "fedramp-docs",
        }
    ],
    messages=[{"role": "user", "content": "..."}],
)

Claude API 将使用工具注释（readOnlyHint、destructiveHint 等）来做出明智的工具选择。全部 21 个工具都包含注释。

MCP 客户端配置

FedRAMP Docs MCP 服务适用于任何兼容 MCP 的客户端。以下是最受欢迎且可靠的客户端的设置说明。

推荐客户端：

• Claude Desktop - 最成熟的 MCP 集成，工具发现体验出色
• Claude Code CLI - Anthropic 官方 CLI 工具，非常适合终端工作流
• Cursor - 支持原生 MCP 的 AI 驱动 IDE
• VS Code + GitHub Copilot - 原生支持 MCP，无需扩展
• Windsurf - 支持原生 MCP 的 AI 驱动 IDE
• Codex (OpenAI) - 支持 MCP 的开源编码 Agent
• Gemini CLI - Google 的命令行 AI Agent，支持 MCP
• LM Studio - 原生支持 MCP，可配合本地模型使用，保护隐私
• OpenCode - 支持 MCP 的终端编码 Agent
• Goose - 实验性支持，可能存在工具发现问题

Claude Desktop

将服务添加到 Claude Desktop 配置文件：

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

选项 1：使用 npx（推荐 - 无需安装）

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

选项 2：全局安装

npm install -g fedramp-docs-mcp

{
  "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（推荐）

# 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

方法 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. 在 Install 部分下点击 “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. 测试 - 提问：“列出所有 FedRAMP FRMR 文档”
7. 批准工具调用 - LM Studio 会在执行每个工具前显示确认对话框

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

OpenCode

OpenCode 是一款功能强大的 AI 编码 Agent，专为终端打造，原生支持 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 Agent。你可以通过以下任一方法添加 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 Desktop
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"  # optional
      FEDRAMP_DOCS_AUTO_UPDATE: "true"            # optional

完成配置后，重启 Goose 或重新加载扩展。你可以询问“有哪些 FedRAMP 工具可用？”来进行测试。

注意： Goose 的 MCP 支持仍在完善中，可能无法从 stdio 服务发现工具。如果你在工具发现方面遇到问题，可以改用 Claude Desktop、Claude Code CLI、LM Studio 或 OpenCode。

Kiro

Kiro 是 AWS 的规范驱动型 IDE，原生支持 MCP。

设置说明

1. 打开 Kiro MCP 设置：

   • 全局：~/.kiro/settings/mcp.json
   • 项目：.kiro/settings/mcp.json（优先级更高）

2. 添加 FedRAMP Docs 配置：

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

使用全局安装：

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

3. 保存文件——配置更改后，Kiro 会自动加载 MCP 服务
4. 测试——向 Kiro 询问：“列出所有 FedRAMP FRMR 文档”

注意： 需要全局安装（npm install -g fedramp-docs-mcp）或使用 npx。运行 which fedramp-docs-mcp 查找路径。

Cursor

Cursor 支持通过项目或全局配置使用 MCP 服务。

配置文件位置： .cursor/mcp.json（项目）或 ~/.cursor/mcp.json（全局）

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

保存后重启 Cursor。你也可以通过 Cursor Settings > MCP 进行配置。

VS Code + GitHub Copilot

VS Code 通过 GitHub Copilot 原生支持 MCP（无需安装扩展）。

配置文件位置： .vscode/mcp.json（工作区范围）

注意： VS Code 使用 servers（而非 mcpServers），且要求 "type": "stdio"。

{
  "servers": {
    "fedramp-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "fedramp-docs-mcp"]
    }
  }
}

保存后，Copilot 会自动检测新服务。你可以通过 命令面板（Ctrl+Shift+P > “MCP: List Servers”）管理 MCP 服务。

Windsurf

Windsurf 是一款原生支持 MCP 的 AI IDE。

配置文件位置： ~/.codeium/windsurf/mcp_config.json

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

保存后重启 Windsurf。

Codex (OpenAI)

Codex 是 OpenAI 的开源编码 Agent，通过 TOML 配置支持 MCP。

配置文件位置： ~/.codex/config.toml（全局）或 .codex/config.toml（项目）

[mcp_servers.fedramp-docs]
command = "npx"
args = ["-y", "fedramp-docs-mcp"]

[mcp_servers.fedramp-docs.env]
FEDRAMP_DOCS_AUTO_UPDATE = "true"

你也可以通过 codex mcp 管理 MCP 服务。

Gemini CLI

Gemini CLI 是 Google 推出的支持 MCP 的命令行 AI Agent。

配置文件位置： ~/.gemini/settings.json（全局）或 .gemini/settings.json（项目）

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

保存后重启 Gemini CLI。

MCP Inspector（调试）

MCP Inspector 是用于测试和调试 MCP 服务的官方工具。它提供可视化界面，可交互式地调用工具并探索资源。

要求： Node.js 22.7.5 或更高版本

交互式界面：

# Start the inspector with fedramp-docs-mcp
npx @modelcontextprotocol/inspector node dist/index.js

# Or if installed globally
npx @modelcontextprotocol/inspector fedramp-docs-mcp

打开 http://localhost:6274 访问界面，然后测试以下工具：

• health_check - 验证服务是否正常运行
• list_frmr_documents - 查看所有已索引的 FedRAMP 文档
• list_ksi - 浏览关键安全指标

CLI 模式（快速测试）：

# List all available tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name health_check

导出配置： Inspector 界面包含复制服务配置的按钮，可用于 Claude Desktop、Cursor 和其他 MCP 客户端。

Claude 插件

此代码仓库包含一个 Claude Code 插件，提供斜杠命令、Agent 技能和专用合规分析 Agent。

快速安装

在 Claude Code 中运行：

/plugin marketplace add hackIDLE/fedramp-docs-mcp
/plugin install fedramp-docs

完成！插件已准备就绪。

# One-command setup
npx fedramp-docs-mcp setup

# Then start Claude Code with the plugin
claude --plugin-dir ~/.fedramp-docs-mcp/plugin

alias claude-fedramp='claude --plugin-dir ~/.fedramp-docs-mcp/plugin'

可用命令

Agent 技能

• frmr-analysis - 分析 FRMR 文档或控制项映射时自动调用
• control-mapping - 将 NIST 控制项映射到 FedRAMP 要求时自动调用

完整文档请参阅 plugin/README.md。

Docker

在安全加固的 Docker 容器中运行 MCP 服务。

快速开始

# Build the image
docker build -t fedramp-docs-mcp .

# Run interactively (for MCP stdio)
docker run --rm -i \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --read-only \
  --memory 512m \
  -v fedramp-cache:/home/mcpuser/.cache/fedramp-docs \
  fedramp-docs-mcp

Docker Compose

# Start with docker-compose (security hardening included)
docker compose up -d

使用 Docker 运行 Claude Desktop

配置 Claude Desktop 使用 Docker 容器：

{
  "mcpServers": {
    "fedramp-docs": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--security-opt", "no-new-privileges:true",
        "--cap-drop", "ALL",
        "--read-only",
        "--memory", "512m",
        "-v", "fedramp-cache:/home/mcpuser/.cache/fedramp-docs",
        "fedramp-docs-mcp:latest"
      ]
    }
  }
}

安全特性

Docker 设置遵循 2025 年 MCP 安全最佳实践：

• 非 root 用户：以 mcpuser（UID 1001）身份运行
• 只读文件系统：防止未经授权的修改
• 移除能力：--cap-drop ALL 移除所有 Linux 能力
• 禁止新增权限：防止权限提升
• 资源限制：限制内存和 CPU
• 网络隔离：使用默认情况下无法访问外部网络的内部网络

开发

在开发模式下运行

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

npm run dev

此命令会直接运行 TypeScript 源代码，并在发生更改时自动重新编译。

运行测试

仓库包含基于 Vitest 的单元测试和契约测试，并使用小型测试夹具：

npm test

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

集成测试使用真实的上游 FedRAMP/docs 克隆仓库验证索引器：

npm run test:integration

这些测试会克隆并索引实际的上游仓库，以验证解析器能否正确处理当前的上游数据。设置 FEDRAMP_DOCS_PATH 可跳过克隆并使用已有的检出副本。如果使用自己的检出副本，还要设置 FEDRAMP_DOCS_AUTO_UPDATE=false，以防测试修改该副本。

代码结构

代码库使用：

• TypeScript 5.4+，并启用严格模式
• ES 模块（在 package.json 中设置 "type": "module"）
• Node.js 模块解析（moduleResolution: "NodeNext"）
• Zod 进行运行时架构验证
• MCP SDK v1.24+ 实现服务

项目结构

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

测试夹具位于 tests/fixtures 下，Vitest 测试文件位于 tests/ 中。

版本历史

跟踪 FedRAMP FRMR v0.9.2-beta 文档。完整详情请参阅 CHANGELOG.md。

故障排除

构建错误

错误：Cannot find module '@modelcontextprotocol/sdk'

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

npm install @modelcontextprotocol/sdk@^1.20.0

错误：Module not found 或导入错误

项目使用基于 NodeNext 解析的 ES 模块。请确保使用 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/  # Should contain index.js, tools/, etc.

开发问题

有关缺少类型的 TypeScript 错误

安装所有开发依赖项：

npm install

必需的类型包：

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