Fedramp Docs MCP

🚀 FedRAMP Docs MCP Server

Custom Model Context Protocol (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 クライアント設定（Claude Desktop、Goose など）で fedramp-docs-mcp をコマンドとして使用する場合は、グローバルインストールが必要です。または、ビルドされたサーバーの完全パスを使用することもできます。例: node /path/to/fedramp-docs-mcp/dist/index.js

サーバー起動時には、FedRAMP/docs リポジトリが利用可能か確認し、FRMR JSON と Markdown コンテンツをインデックス化した後、MCP stdio でリクエストの処理を開始します。

⚙️ 設定

環境変数を使用して、リポジトリの検出とインデックス化の動作を制御できます。

変数	デフォルト値	説明
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 を考慮した比較を使用して、2 つの FRMR データセットの構造化差分を求めます。
• grep_controls_in_markdown — Markdown ガイダンス内のコントロール参照を検索します。
• get_significant_change_guidance — FRMR と Markdown 全体の選りすぐりの重要な変更参照を取得します。
• health_check — サーバーが正常にインデックス化されたことを確認し、リポジトリのパスを公開します。
• update_repository — キャッシュされた FedRAMP ドキュメントを最新バージョンに強制更新します。

src/tools/ を参照すると、Zod で実装された正確なスキーマを確認できます。各ツールは、成功オブジェクトまたは code、message、およびオプションの hint を含む error ペイロードを返します。

💻 使用例

Claude Desktop や他の MCP クライアントで MCP サーバーを使用する場合、以下はいくつかのクエリ例です。

KSI 情報の取得:

"List all available FedRAMP documents"
→ list_frmr_documents を使用します。

"Show me the Key Security Indicators"
→ パス 'FRMR.KSI.key-security-indicators.json' で get_frmr_document を使用します。

"What are the KSI categories?"
→ KSI ドキュメントを解析して、IAM、CNA、MLA などのカテゴリを表示します。

ドキュメントの検索:

"Search for information about continuous monitoring"
→ クエリ 'continuous monitoring' で search_markdown を使用します。

"Find guidance on incident response"
→ クエリ 'incident response' で search_markdown を使用します。

コントロールの操作:

"List all controls mapped in the MAS"
→ list_controls を使用します。

"Find all markdown files that reference AC-2"
→ コントロール 'AC-2' で grep_controls_in_markdown を使用します。

変更の分析:

"What's new in the latest KSI release?"
→ list_versions を使用してから diff_frmr を使用してバージョンを比較します。

"Show significant change guidance"
→ 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 は、組み込みの MCP サポートを備えた Anthropic の公式 CLI ツールです。

方法 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 は 3 つの設定スコープをサポートしています。

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. テストします - "List all FedRAMP FRMR documents" と尋ねます。
7. ツール呼び出しを承認します - LM Studio は各ツールを実行する前に確認ダイアログを表示します。

注意: グローバルインストール（npm install -g .）が必要です。または、実行可能ファイルの完全パスを使用します。パスを確認するには、which fedramp-docs-mcp を使用します。

OpenCode

OpenCode は、ネイティブ MCP サポートを備えたターミナル向けの強力な AI コーディングエージェントです。

設定手順

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 Desktop アプリを使用する

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"  # オプション
      FEDRAMP_DOCS_AUTO_UPDATE: "true"            # オプション

設定後、Goose を再起動するか、拡張機能を再読み込みします。"What FedRAMP tools are available?" と尋ねることでテストできます。

注意: 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 モジュール (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/ にあります。

🐞 トラブルシューティング

ビルドエラー

エラー: 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