AWS Amplify Documentation MCP Server

AWS Amplify ドキュメント MCP サーバー

AWS Amplify ドキュメントを強力に検索できる Model Context Protocol（MCP）サーバーです。このサーバーは、AWS Amplify の公式ドキュメントリポジトリをクローンし、シンプルな MCP ツールインターフェースから検索できるようにします。

機能

• 強力な検索：自然言語のクエリで AWS Amplify ドキュメントを検索します
• 高度な検索構文：ブール演算子、ワイルドカード、フィールド指定検索などに対応します
• スマートな検索結果のランキング：クエリとの関連性に基づいて検索結果をインテリジェントにランク付けします
• ページネーション：ページネーション機能を使って大量の検索結果を閲覧できます
• パフォーマンスキャッシュ：検索結果をキャッシュしてパフォーマンスを向上させます
• 自動更新：AWS Amplify の公式リポジトリからドキュメントを自動的に更新します
• 世代の選択：Gen 1、Gen 2、または両方のドキュメントセットから選択し、ディスク使用量と検索範囲を最適化できます。
• TypeScript による実装：型安全性と開発者エクスペリエンスを高めるため、TypeScript で構築されています

免責事項：これは個人プロジェクトであり、AWS Amplify または Amazon Web Services と提携、承認、あるいは公式に関係しているものではありません。このツールは、いかなる保証もない現状有姿で提供されます。

インストール

1. このリポジトリをクローンします。

git clone https://github.com/ykethan/amplify-doc-mcp.git
cd amplify-doc-mcp

1. 依存関係をインストールします。

npm install

1. TypeScript コードをビルドします。

npm run build

設定

サーバーは docs-mcp.config.json ファイルを使用して設定します。

{
  "gitUrl": "https://github.com/aws-amplify/docs.git",
  "gitRef": "main",
  "autoUpdateInterval": 60,
  "toolName": "search_amplify_docs",
  "toolDescription": "Search AWS Amplify documentation using the probe search engine.",
  "ignorePatterns": [
    "node_modules",
    ".git",
    "dist",
    "build",
    "coverage",
    ".vitepress/cache",
    "*.jpg",
    "*.jpeg",
    "*.png",
    "*.gif",
    "*.svg",
    "*.mp4",
    "*.webm"
  ],
  "amplifyGeneration": "gen2"
}

設定オプション

オプション	説明	デフォルト
gitUrl	ドキュメントをクローンする Git リポジトリの URL	"https://github.com/aws-amplify/docs.git"
gitRef	チェックアウトする Git ブランチまたはタグ	"main"
autoUpdateInterval	更新を確認する間隔（分）（0 にすると無効）	60
dataDir	ドキュメントデータを保存するディレクトリ	"./data"
toolName	検索ツールの名前	"search_amplify_docs"
toolDescription	検索ツールの説明	"Search AWS Amplify documentation using the probe search engine."
ignorePatterns	検索時に無視するパターンの配列	["node_modules", ".git", ...]
amplifyGeneration	対象にする Amplify ドキュメントの世代	"gen2"

自動更新の仕組み

サーバーには、ドキュメントを最新の状態に保つ自動更新機能が備わっています。

1. サーバーの起動時に、gitUrl で指定されたドキュメントリポジトリをクローンします。
2. autoUpdateInterval が 0 より大きい値に設定されている場合、サーバーは定期的に更新を確認します。
3. autoUpdateInterval 分ごとに、サーバーは次の処理を行います。
   • リモートリポジトリから最新の変更を取得します
   • ローカルブランチがリモートブランチより遅れているか確認します
   • 更新がある場合は、変更を自動的に取得します
   • 更新が不要な場合は、現在のドキュメントを引き続き使用します

これにより、サーバーを再起動しなくても、ドキュメントの検索結果に常に最新の情報が含まれるようになります。

使用方法

サーバーの起動

npm start

または、オプションを指定して付属の起動スクリプトを使用します。

./start-server.sh [--gen <1|2|both>] [--rebuild]

オプション

• --gen 1：Gen 1 のドキュメントのみを含めます（ディスク使用量を削減します）
• --gen 2：Gen 2 のドキュメントのみを含めます（デフォルト。ディスク使用量を削減します）
• --gen both：Gen 1 と Gen 2 の両方のドキュメントを含めます
• --rebuild：データディレクトリを強制的に再構築します

例

# Start with Gen 2 documentation (default)
./start-server.sh

# Start with only Gen 1 documentation
./start-server.sh --gen 1

# Start with both Gen 1 and Gen 2 documentation
./start-server.sh --gen both

# Start with only Gen 2 documentation and force rebuild
./start-server.sh --gen 2 --rebuild

重要：異なる生成オプション間を切り替える場合（例：Gen 1 から Gen 2、またはその逆）、リポジトリをクリーンな状態にするため、--rebuild フラグを使用することをおすすめします。これにより、data ディレクトリが削除され、リポジトリが再度クローンされるため、選択した生成に応じて適切なファイルが含まれます。

例：

# クリーンな再ビルドで Gen 2 から Gen 1 に切り替え
./start-server.sh --gen 1 --rebuild

# クリーンな再ビルドで Gen 1 から Gen 2 に切り替え
./start-server.sh --gen 2 --rebuild

MCP ツール：search_amplify_docs

サーバーには、Amplify のドキュメントを検索するための search_amplify_docs というツールが用意されています。

パラメーター

パラメーター	型	必須	デフォルト	説明
query	string	はい	-	Elasticsearch のクエリー文字列
page	number	いいえ	1	ページネーションのページ番号
includeContent	boolean	いいえ	false	結果にコンテンツの抜粋を含めます
maxResults	number	いいえ	10	返す結果の最大数
filesOnly	boolean	いいえ	false	コンテンツを含めず、ファイルパスのみを返します
useJson	boolean	いいえ	false	結果を JSON 形式で返します
sessionId	string	いいえ	-	関連する検索のセッション ID
fullContent	boolean	いいえ	false	指定したファイルの全文を取得します
filePath	string	いいえ	-	全文を取得する特定のファイルへのパス

リクエスト例

{
  "query": "authentication react",
  "page": 1,
  "includeContent": true,
  "maxResults": 15
}

高度な検索構文

検索ツールは、高度な検索構文に対応しています。

• 完全一致フレーズ："authentication flow"
• 除外語句：authentication -flutter
• フィールドを指定した検索：title:authentication
• ワイルドカード：auth*
• ブール演算子：authentication AND (react OR javascript) NOT flutter

クエリ処理の仕組み

検索クエリを送信すると、サーバーはいくつかの手順で処理します。

1. クエリ処理：サーバーはクエリを解析し、ブール演算子やワイルドカードなどの高度な構文を理解します。

2. ディレクトリの最適化：サーバーはディレクトリ構造を利用し、クエリの語句と選択された Amplify の生成（Gen 1、Gen 2、または両方）に基づいて、検索対象のファイルを絞り込みます。

3. スマートな順位付け：高度なアルゴリズムを使用して、以下の要素を考慮しながら結果を順位付けします。

   • クエリに特定の生成（Gen 1 または Gen 2）が記載されているか
   • クエリがセットアップ、CLI コマンド、またはリソース作成に関するものか
   • クエリの文脈に対するドキュメントの関連性
   • ドキュメントタイトルとの完全一致
   • 一致数とドキュメントの重要度

4. コンテンツの抽出：一致したファイルごとに、関連するコンテンツを抽出して表示用に整形します。

5. キャッシュ：同じクエリを繰り返したときのパフォーマンスを向上させるため、検索結果をキャッシュします。

このインテリジェントな処理により、検索結果の上位に最も関連性の高いドキュメントが表示され、時間と労力を節約できます。

生成の選択

サーバーは、Amplify のドキュメント生成について、3 つのモードに対応しています。

1. Gen 2 のみ（デフォルト）

"amplifyGeneration": "gen2"

• メリット：最新の Amplify 実装に特化し、ディスク容量の使用を抑えられます
• おすすめの対象：Amplify Gen 2 の機能を使用する新規プロジェクト
• デフォルト：Gen 2 は現在の Amplify のバージョンであるため、これがデフォルト設定です

2. Gen 1 のみ

"amplifyGeneration": "gen1"

• メリット：従来の Amplify 実装に特化し、ディスク容量の使用を抑えられます
• おすすめの対象：Amplify Gen 1 の機能を特に使用する既存プロジェクト

3. 両方の生成

"amplifyGeneration": "both"

• メリット：ドキュメントを網羅的に参照できます
• デメリット：検索範囲が広くなり、Gen 1 と Gen 2 に似たカテゴリーがあるため、混乱することがあります
• 使用する場合：両方の生成を同時に参照する必要がある場合

プロジェクト構成

• src/index.ts：メインサーバーの実装
• src/config.ts：設定の読み込みと処理
• src/git.ts：Git リポジトリの管理
• src/cache.ts：検索結果のキャッシュ
• src/directory.ts：ディレクトリ構成の管理
• src/types/：TypeScript の型定義
• scripts/build.js：ドキュメントを準備するビルドスクリプト
• bin/mcp：サーバーを実行する実行可能スクリプト

使用上の推奨事項

1. 環境に合わせて最適化する：

   • 最適な検索結果を得るには、"amplifyGeneration" に "gen1" または "gen2" のみを指定してください。

2. 検索の最適化：

   • 一般的な表現ではなく、具体的な技術用語を使用してください。
   • 結果を絞り込むには、カテゴリ名を含めてください（例：「access」だけではなく「storage owner access」）。
   • 完全一致検索には引用符を使用してください。
   • 検索結果の改善には、略語や別の用語も含めてください。

3. パフォーマンスに関する考慮事項：

   • 必要に応じて適切な autoUpdateInterval を設定してください（値を大きくするとサーバーの負荷が軽減されます）。
   • 頻繁にアクセスするクエリには、キャッシュシステムを使用してください。
   • 最初の広範な検索のパフォーマンスを向上させるには、filesOnly: true の使用を検討してください。

コントリビューションとフィードバック

この MCP サーバーの改善に向けたコントリビューションやフィードバックを歓迎します。以下について提案がある場合：

• 検索クエリの結果の改善
• ランキングアルゴリズムの強化
• 新機能やパラメーターの追加
• パフォーマンスの最適化

GitHub でイシューを作成するか、プルリクエストを送信してください。皆さまのフィードバックが、このツールをより多くの人にとって役立つものにします。その過程で新しいことも学べます。

システム要件

• Node.js 18.x 以上（Node.js 20.18.2 でテスト済み）
• npm 8.x 以上（npm 10.8.2 でテスト済み）

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。