APILinter MCP Server

APILinter MCP サーバー

OpenAPI MCP サーバーは、Model Context Protocol（MCP）を実装することで、LLM と REST API のシームレスな通信を実現します。

機能

機能	実装済み	備考
構造化ロギング	✅
メトリクスとモニタリング	✅
サーキットブレーカー	✅
リトライパターン	✅
ヘルスチェック	✅
API ドキュメント	❌	予定
レート制限	❌	予定
セキュリティ制御	❌
エラー処理	✅
OpenTelemtry	❌	予定

MCP プロトコルへの準拠

機能	実装済み	備考
プロトコル仕様	✅	v2025-03-26
MCP 認証	❌	不要
セッション管理	❌	ステートレス
ツールのサポート	✅	validate_api_specification list_rules calculate_api_quality_score get_rule_categories get_api_docs get_api_linter_link
リソースのサポート	❌
プロンプトのサポート	✅	api_design_review
ストリーミング可能な HTTP トランスポート	✅
SSE トランスポート	❌	予定なし
STDIO トランスポート	❌	予定なし
SDK クライアント	✅	https://github.com/jbovet/zally-mcp-server.git

インストール

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

   git clone [email protected]:jbovet/zally-mcp-server.git
   cd zally-mcp-server

プロジェクト構成：

• src/: TypeScript のソースコードが含まれています。
  • circuitbreaker/: サーキットブレーカーとリトライの実装です。
  • config/: 設定ファイルです。
  • controllers/: StreamableHttp コントローラーを含む Express コントローラーです。
  • models/: データモデル用の TypeScript インターフェースです。
  • repositories/: API Linter のデータアクセス層です。
  • services/: API Linter と MCP 統合のビジネスロジックです。
  • utils/: HTTP クライアントやエラー処理などのユーティリティクラスです。
  • target/: コンパイル済みの JavaScript ファイルです。
• package.json: プロジェクトのメタデータと依存関係です。
• tsconfig.json: TypeScript の設定ファイルです。
• curl-mcp-client.sh: curl を使って MCP サーバーのエンドポイントをテストする Bash スクリプトです。
• README.md: プロジェクトのドキュメントです。

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

npm install

2. プロジェクトをビルドします。

npm run build

設定

環境変数：

• PORT: サーバーのポート（デフォルト：3000）
• APILINTER_URL: API Linter サービスの URL（デフォルト：http://localhost:3000）
• RETRY_COUNT: 失敗したリクエストのリトライ回数（デフォルト：3）
• CIRCUIT_BREAKER_THRESHOLD: サーキットブレーカーを作動させる失敗しきい値（デフォルト：5）

サーバーの実行

注意： 先に Zally Server を実行する必要があります。ドキュメントは https://github.com/zalando/zally?tab=readme-ov-file#quick-start-guide で確認できます。

次のコマンドでサーバーを起動します。

npm run dev

MCP サーバーは、次のエンドポイントでストリーミング可能な HTTP モードで実行されます：http://localhost:3000/mcp

サーバーのテスト

次のコマンドでテストを実行します。

npm run test

サンプルクライアントの実行

MCP サーバー用の対話型サンプルクライアントを実行するには、次のコマンドを使用します。

npx tsx example/simpleStreamableHttp.ts

これにより対話型クライアントが起動し、MCP サーバーのさまざまなコマンドや機能をテストできます。

> list-rules
> list-rules true
> validate-api ./my-api-spec.yaml
> validate-api-rules ./my-api-spec.json id

ツール

MCP サーバーでは、API のリンティングに以下のツールを利用できます。

• validate_api_specification：API 仕様（OpenAPI/Swagger）が API Linter のルールに準拠しているか検証します

  • パラメーター：spec（API 仕様の内容）、ruleIds（任意。使用するルール ID のリスト）
  • 戻り値：違反内容と書式情報を含む検証結果
  • リトライロジック：一時的な障害が発生した場合、検証リクエストを再試行します
  • サーキットブレーカー：API Linter サービスが応答しなくなった場合、検証リクエストを停止します

• list_rules：利用可能な API Linter のルールをすべて一覧表示します

  • パラメーター：isActive（任意のブール値。有効状態で絞り込む場合に指定）
  • 戻り値：詳細情報を含む、利用可能なリンティングルールのリスト
  • リトライロジック：一時的な障害が発生した場合、ルール一覧の取得リクエストを再試行します
  • サーキットブレーカー：API Linter サービスの障害がしきい値を超えた場合、それ以上のリクエストを防止します

• calculate_api_quality_score：API 仕様の品質スコアを計算します

  • パラメーター：spec（API 仕様の内容）
  • 戻り値：詳細な内訳を含む品質スコア

• get_rule_categories：API Linter のルールカテゴリを取得します

  • パラメーター：なし
  • 戻り値：ルールカテゴリのリスト

プロンプト

MCP サーバーでは、以下の事前設定済みプロンプトを利用できます。

• api_design_review：API 仕様を分析し、包括的な設計フィードバックを提供します
  • パラメーター：
    • specification（JSON または YAML 形式の API 仕様の内容）
    • focusAreas（任意。重点を置く領域のカンマ区切りリスト。例：「security,naming,consistency」）
  • 戻り値：以下を含む、構造化された API 設計フィードバック：
    • API の目的と設計に関するエグゼクティブサマリー
    • 強みの特定
    • 改善点（命名、一貫性、エラー処理、セキュリティなど）
    • API を強化するための具体的な推奨事項

セキュリティに関する注意事項

• DNS リバインディング攻撃を防ぐため、オリジン検証を実装しています
• セキュリティのため、ステートレスモードで Streamable HTTP トランスポートを使用します
• 開発時は、信頼できるオリジン（localhost）からのリクエストのみを処理します
• すべての API 入力は処理前に検証されます
• リトライロジックとサーキットブレーカー：サービス障害に適切に対処することで、耐障害性とセキュリティを高めます

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 依存関係をインストールします（npm install）
4. 変更を加えます
5. テストを実行して、すべて成功することを確認します（npm test）
6. 変更をコミットします（git commit -m 'Add some amazing feature'）
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. プルリクエストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。