specwise-mcp

Specwise MCP サーバー

コーディングエージェントで API コントラクトをチェックできます。OpenAPI ドキュメントの検証、2 つのバージョン間（git との比較も可能）の破壊的変更の検出、JSON Schema とデータの検証を行います。

サーバーはオープンソース（MIT）です。有料の Specwise API を呼び出しますが、無料プランもあります。

• RapidAPI または api.market で取得したご自身のキーを使用します。
• ツールを呼び出すたびに、プランのリクエストを 1 回使用します。
• 無料の Basic プランは月 15 回までで、上限が厳密に設定されているため、請求が発生することはありません。

1. キーを取得する

マーケットプレイス
RapidAPI	プラン
api.market	ストア

2. MCP クライアントにサーバーを追加する

サーバーは uv を使い、stdio 経由でローカル実行されます。キーは環境変数に設定してください。

JSON 設定（Claude Desktop、Cursor、VS Code およびほとんどのクライアント向け）：

{
  "mcpServers": {
    "specwise": {
      "command": "uvx",
      "args": ["--from", "bytestay-specwise-mcp", "specwise-mcp"],
      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
    }
  }
}

Claude Code：

claude mcp add specwise --env RAPIDAPI_KEY=your-rapidapi-key -- uvx --from bytestay-specwise-mcp specwise-mcp

環境変数

変数	説明
RAPIDAPI_KEY	RapidAPI キー
API_MARKET_KEY	RAPIDAPI_KEY が設定されていない場合に使用する api.market キー
HFL_MARKETPLACE	両方のキーが設定されている場合は rapidapi または apimarket

キーがなくてもサーバーは起動します。最初のツール呼び出し時に、キーの取得先が案内されます。

Glama にも掲載されています：

3. ツール

ツール	機能
validate_openapi(spec=… | spec_path=…)	すべてのエラーについて、JSON Pointer、行、列を表示し、リンティング警告も示します（OpenAPI 3.x および Swagger 2.0）
diff_openapi(...)	2 つの OpenAPI 3.x バージョン間の各変更を、破壊的、警告、非破壊、情報のいずれかに分類し、semver の推奨を示します
validate_json_schema(schema=… | schema_path=…, instance=… | instance_path=…, draft=None)	スキーマをそのメタスキーマに照らして検証し、データが指定されている場合は、そのデータをスキーマに照らして検証します

diff_openapi では、次の 3 つの方法のいずれかで 2 つのバージョンを指定します。

• base と revision をテキストとして指定します。
• base_path と revision_path をファイルとして指定します。
• revision_path と base_git_ref を指定します。たとえば、仕様を編集した後に revision_path="openapi.yaml", base_git_ref="main" とします。

各ツールは API の JSON レスポンスを返します。

• マーケットプレイスから報告された場合は、今月のプランで残っているリクエスト数を示す quota_remaining が追加されます。
• エラーは、次に行うべきこととともに平易な言葉で説明されます。
  • キーが拒否された場合は、登録リンクが表示されます。
  • クォータに達した場合は、プランが表示されます。
  • API が処理できなかった入力の場合は、その理由が表示されます。

プライバシー

• ローカルファイルは、ツールにパスを指定した場合にのみ読み込まれ、そのリクエストの処理に限って API に送信されます。
• API は入力をメモリ上で処理し、保存しません。プライバシーポリシーをご覧ください。
• キーは、選択したマーケットプレイスにのみ送信されます。

制限事項

• 各ドキュメントの上限は約 900 KiB です。
• 外部の $ref は取得されません。複数ファイルからなる仕様は、先にバンドルしてください（redocly bundle）。
• diff には OpenAPI 3.x が必要です。Swagger 2.0 は検証できますが、diff はできません。
• サーバーには Python 3.10 以降が必要です（uv がインストールします）。

開発

uv venv && uv pip install -e ".[dev]"
.venv/bin/pytest            # unit tests, no network; 100% coverage required
.venv/bin/ruff check src tests scripts

scripts/e2e_stdio.py specwise は、クライアントと同じようにサーバーを stdio 経由で実行し、実際の API に対してツールを呼び出します。RAPIDAPI_KEY または API_MARKET_KEY が必要です。

ライセンス

MIT。Specwise 自体は無料プランもある有料 API で、ByteStay が運営しています。