openapi-mcp
=========================

OpenAPI仕様を入力として、MCPサーバー(stdio)のツール定義と実行処理を自動構成する実験プロジェクトです。
API仕様を単一のsource of truthとして維持し、LLM連携時の実装負荷と運用負荷を下げることを目的とします。

目次
-------------------------

1. [主要機能](#主要機能)
2. [技術スタック](#技術スタック)
3. [セットアップ手順](#セットアップ手順)
4. [使用方法](#使用方法)
5. [プロジェクト構造](#プロジェクト構造)
6. [関連ドキュメント](#関連ドキュメント)

主要機能
-------------------------

- OpenAPI仕様の読み込み: `--spec`で単一/複数ファイル、`--dir`でディレクトリ探索に対応します。
- MCPツール自動生成: `paths`と`operation`を走査し、入力スキーマと説明文を自動で生成します。
- 公開制御: `x-mcp.expose`と`--deny-*`引数を併用して公開/非公開を制御します。
- 認証情報の解決: APIキー認証とBasic認証を環境変数から解決してHTTPリクエストへ注入します。
- エラー正規化: HTTPステータスごとに`hint`と`retryable`を付与した構造化エラーを返します。
- サンプル仕様対応: 複数形式のOpenAPI入力を使った検証に対応します。

技術スタック
-------------------------

### 言語・実行環境

- JavaScript: ECMAScript Modules
- Node.js: `fetch`が利用できるランタイムを想定
- zx: 実行ランタイム兼ユーティリティ

### 主要ライブラリ

- `@modelcontextprotocol/sdk`: MCPサーバー実装
- `@apidevtools/swagger-parser`: OpenAPI仕様の解決

### 品質管理ツール

- `markdownlint-cli2`: Markdownルール検証
- `textlint`: 日本語品質ルール検証
- `prettier`: 文章・設定ファイルの整形

セットアップ手順
-------------------------

### 前提条件

- Node.js
- zx([公式リポジトリー](https://github.com/google/zx))

### インストール

1. リポジトリーを取得します。

    ```bash
    git clone https://github.com/wate/openapi-mcp.git
    cd openapi-mcp
    ```

2. 動作確認としてサーバーを起動します。

    ```bash
    zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml
    ```

3. ドキュメント品質チェックを実行する場合のみ、依存関係をインストールします。

    ```bash
    yarn install
    ```

使用方法
-------------------------

### 基本フロー

1. 入力するOpenAPI仕様を選びます。
2. `zx --install ./mcp-server.mjs`でMCPサーバーを起動します。
3. MCPクライアントから`tools/list`と`tools/call`を実行します。
4. 必要に応じて`x-mcp`や`--deny-*`で公開範囲を調整します。

### 代表コマンド

```bash
# 単一specを指定
zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml

# 複数specを指定
zx --install ./mcp-server.mjs \
    --spec ./openapi/endoflife.yml \
    --spec ./openapi/jgrants.yaml

# ディレクトリを指定して自動探索
zx --install ./mcp-server.mjs --dir ./openapi

# 公開除外を指定
zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml --deny-methods delete
```

### `x-mcp`による補助情報

```yaml
paths:
  /customers:
    get:
      operationId: searchCustomers
      x-mcp:
        expose: true
        name: search_customers
        description: 顧客検索用ツール
        annotations:
          readOnlyHint: true
          destructiveHint: false
          idempotentHint: true
```

プロジェクト構造
-------------------------

```text
.
├ README.md
├ mcp-server.mjs
├ package.json
├ lib/
│    ├ args.mjs
│    ├ auth.mjs
│    ├ config.mjs
│    ├ executor.mjs
│    ├ tools.mjs
│    ├ trimming.mjs
│    └ utils.mjs
├ tests/
│    ├ unit/
│    ├ integration/
│    └ e2e/
└ docs/
     └ design.md
```

- `mcp-server.mjs`: エントリーポイント。main のみを担当します。
- `lib/`: OpenAPI解析、ツール生成、HTTP実行、エラー整形などのロジックを分離したモジュール群です。
- `tests/`: ユニット・統合・E2E テスト。
- `docs/design.md`: 設計方針と仕様詳細を管理します。

関連ドキュメント
-------------------------

### 初回把握向け

- [設計メモ](docs/design.md): 変換方針、優先順位、設計背景を確認するときに参照します。

更新ポリシー
-------------------------

- 実装方針を変更した場合は、まず`docs/design.md`を更新します。
- 進捗や判断理由は、Git管理下の運用ドキュメントに記録します。
- READMEは概要導線に限定し、詳細は関連ドキュメントへ追記します。