ganjoor-mcp-server

Ganjoor MCP Server — Ganjoor のペルシャ詩 API 用 Model Context Protocol サーバーです。

エージェントは、詩人や詩集を閲覧し、詩とその詩句を読み、韻律や押韻を分析し、詩人をまたいで返歌をたどり、朗読や注釈を検索し、関連人物や家系図のグラフを調べることができます。

44 個のツール、読み取り専用アクセスです。API キーは必要ありません。

目次

• インストール
• Docker
• 設定
• 概念
• ツールリファレンス
• レスポンス形式
• 使い方
• アーキテクチャ
• 開発
• 既知の制限事項
• 評価
• コントリビュート

インストール

Node.js 18.17 以降が必要です。

npm install ganjoor-mcp-server # for locally installed stdio transport. no need if using VS Code or Claude Desktop / Cursor.

VS Code

npm パッケージをインストールする必要はありません。MCP サーバーはプロセス内で実行され、必要に応じて VS Code が起動します。

以下のバッジをクリックするだけで、Ganjoor MCP サーバーを VS Code ワークスペースにインストールできます。サーバーは .vscode/mcp.json 設定ファイルに自動的に追加されます。

または、.vscode/mcp.json に追加します。

{
  "servers": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {}
    }
  }
}

VS Code CLI：

code --add-mcp '{\"name\":\"io.github.ehsanghaffar/ganjoor-mcp-server\",\"command\":\"npx\",\"args\":[\"-y\",\"ganjoor-mcp-server\"],\"env\":{}}'

Claude Desktop / Cursor

以下のバッジをクリックするだけで、Ganjoor MCP サーバーを Claude Desktop または Cursor アプリにインストールできます。サーバーは MCP 設定に自動的に追加されます。

または、MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {},
      "type": "local",
      "tools": [
        "*"
      ]
    }
  }
}

その他のクライアント

claude mcp add io.github.ehsanghaffar/ganjoor-mcp-server npx -y ganjoor-mcp-server

[mcp_servers.ganjoor-mcp-server]
command = "npx"
args = ["-y", "ganjoor-mcp-server"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "ganjoor-mcp-server"
      ],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "io.github.ehsanghaffar/ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {},
      "type": "local",
      "tools": [
        "*"
      ]
    }
  }
}

{
  "mcpServers": {
    "ganjoor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ganjoor-mcp-server"
      ],
      "env": {},
      "type": "local",
      "tools": [
        "*"
      ]
    }
  }
}

このソースからインストールする

npm install
npm run build
npm start            # stdio transport (default)

VS Code

.vscode/mcp.json に追加します：

{
  "servers": {
    "ganjoor": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Claude Desktop / Cursor

MCP 設定ファイルに追加します：

{
  "mcpServers": {
    "ganjoor": {
      "command": "node",
      "args": ["/absolute/path/to/ganjoor-mcp/dist/index.js"]
    }
  }
}

ストリーミング可能な HTTP（リモート／共有デプロイ）

HTTP=true PORT=3000 npm start

MCP エンドポイントは POST /mcp で、GET /health はサーバーとアップストリームの状態を報告します。HTTP トランスポートはステートレスで実行される（リクエストごとに新しいサーバーインスタンスを起動する）ため、水平スケーリングが可能です。デフォルトでは 127.0.0.1 にバインドし、DNS リバインディング攻撃を防ぐために Origin ヘッダーを検証します。ループバック以外のオリジンが必要な場合は、ALLOWED_ORIGINS（カンマ区切り）を設定してください。

MCP Inspector

npm run inspector

Docker

マルチステージの Dockerfile と docker-compose.yml が含まれています。イメージは node:22-alpine をベースに構築され、コンパイル済みの出力と本番用の依存関係のみが含まれます。

docker compose up --build

Compose ファイルは、http://localhost:3000/mcp でストリーミング可能な HTTP モードのサーバーを起動し、 GET /health でサーバーとアップストリームの状態を報告します。公開ポートをホストから アクセスできるように、HOST は 0.0.0.0 に設定されています。以下の表にあるすべての設定変数は、通常の 環境変数として使用できます。Compose を使わずに単一のコンテナーを実行するには：

docker build -t ganjoor-mcp .
docker run --rm -p 3000:3000 -e HTTP=true -e HOST=0.0.0.0 ganjoor-mcp

Docker 経由の stdio トランスポート

サーバーを自分で起動するクライアント（HTTP 経由で接続するのではなく）は、stdio プロファイルを使用できます。このプロファイルは、プロトコルストリーム用に stdin を開き、HTTP リスナーを起動しません：

docker compose --profile stdio run --rm ganjoor-mcp-stdio

Claude Desktop を使う場合

ローカルの Node インストールではなく Docker 経由でサーバーを実行するには：

{
  "mcpServers": {
    "ganjoor": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ganjoor-mcp"]
    }
  }
}

設定

すべての設定は環境変数で、必須のものはありません。

概念

Ganjoor のデータモデルは、3 つの階層で構成されています。これらを正しく理解しているかどうかが、エージェントとのセッションを実りあるものにするか、無駄に終わらせるかの分かれ目です。

graph TD
    P["Poet — e.g. Hafez, id 2, slug /hafez"] --> C1["Category — e.g. Ghazals, id 24"]
    P --> C2["Category — e.g. Qeta, id 25"]
    C1 --> M1["Poem — e.g. Ghazal 494, id 2623, /hafez/ghazal/sh494"]
    C2 --> M2["Poem"]
    M1 --> V["Verses (hemistichs, paired into couplets)"]
    M1 --> S["Sections (nested stanzas with metre + rhyme)"]
    M1 --> R["Recitations (audio)"]
    M1 --> CM["Comments (reader commentary)"]
    M1 --> Q["Quoted / related poems"]

• 詩人 — 作者です。Hafez は詩人 ID 2、Saadi は 7、Rumi は 5、Khayyam は 3、Ferdowsi は 4 です。 ganjoor_list_poets を使うと、名前から ID を取得できます。
• カテゴリ — 詩人の作品に含まれる書物やセクションです（CatType 0 は一般、1 は詩、2 は書物）。Hafez のルートカテゴリは 9、ガザルは 24 です。
• 詩 — 1 つのテキストで、数値 ID と hafez/ghazal/sh494 のような URL スラッグで識別されます。
• 詩句 — 半句です。連続する 2 つの詩句で couplet（versePosition 0 と 1）を構成します。

URL スラッグには先頭のスラッシュが必要です。 上流 API は ?url=hafez/ghazal/sh494 に対して 404 を返しますが、?url=/hafez/ghazal/sh494 なら解決できます。このサーバーが正規化するため、どちらの形式でも使用できます。

ペルシア語のテキストは原文のまま返されます。 右から左に書かれ、韻律を示すためにアラビア文字の発音記号が使われています。ユーザーから明示的に求められない限り、ローマ字に転写したり翻訳したりしないでください。

ツールリファレンス

詩人と詩集

カテゴリ

詩

韻律、押韻、構成

音声朗読

人物

注釈、FAQ、補足資料

すべてのツールには readOnlyHint、idempotentHint、openWorldHint が注釈として付与されており、Ganjoor の状態を変更するツールはありません。

応答形式

すべてのツールは response_format 引数を受け取ります。

• markdown（デフォルト）— 見出し、リスト、クリック可能なリンクを含む、人が読みやすい出力です。
• json — 同じデータを構造化オブジェクトとして返します。MCP の structuredContent としても返されるため、対応しているクライアントはテキストを解析せずにフィールドを直接利用できます。

リストツールでは、一貫したページネーション用のエンベロープを共有します。

{
  "total": 842,
  "count": 20,
  "page": 1,
  "page_size": 20,
  "has_more": true,
  "next_page": 2,
  "poems": [{ "id": 2623, "title": "غزل شمارهٔ ۴۹۴", "full_url": "/hafez/ghazal/sh494" }]
}

page と page_size は 1 から始まり、page_size の上限は 100 です。25,000 文字を超える応答は、暗黙に切り詰めるのではなく、明示的な truncated フラグを付けて切り詰めます。

上流の 2 つのエンドポイント（/api/ganjoor/poets と /api/ganjoor/rhythms）はページネーションのパラメーターを無視し、常にコレクション全体を返します。サーバーはこの挙動を検出して、要求された範囲をローカルで切り出すため、すべてのリストツールで page と has_more は正確かつ一貫した値になります。

エラーはプロトコルエラーではなくツールの結果として返され、エンドポイントを示すメッセージと次の手順が提示されます。たとえば、404 の場合は、有効な ID を探すために ganjoor_list_poets を案内します。

使用例

「ハーフェズとはどのような人物ですか？」

ganjoor_get_poet { "url": "hafez" }

「ハーフェズのガザル 494 を見せてください」

ganjoor_get_poem { "url": "hafez/ghazal/sh494", "include_recitations": true }

「ハーフェズの詩のうち、صبر という語を含むのはどれですか？」

ganjoor_search_poems { "term": "صبر", "poet_id": 2, "page_size": 10 }

「この詩の韻律は何ですか？ また、同じ韻律で詩を書いたのはほかに誰ですか？」

ganjoor_analyze_poem_rhythm { "poem_id": 2623 }
ganjoor_list_rhythms { "page_size": 100 }
ganjoor_find_similar_poems { "metre": "<rhythm from the previous step>", "page_size": 10 }

「この人物の祖先は誰ですか？」

ganjoor_get_person { "person_id": 22 }
ganjoor_get_person_family_tree { "person_id": 22 }

「私の質問について、ハーフェズは何と言っていますか？」

ganjoor_get_hafez_faal { }

アーキテクチャ

src/
├── index.ts            # Process entry: stdio or streamable HTTP transport
├── server.ts           # createServer() — registers every tool
├── client.ts           # fetch wrapper, error mapping, pagination helpers
├── types.ts            # TypeScript interfaces for Ganjoor's payloads
├── constants.ts        # Base URLs, limits, server identity
├── schemas.ts          # Shared Zod schemas (pagination, URL slugs, ids)
├── format.ts           # Markdown rendering and formatting helpers
└── tools/
    ├── registry.ts     # defineTool() wrapper: consistent errors + both formats
    ├── poets.ts        # Poet discovery
    ├── categories.ts   # Category browsing
    ├── poems.ts        # Poem retrieval, search, URL resolution
    ├── analysis.ts     # Prosody, rhyme, sections
    ├── audio.ts        # Recitations
    ├── content.ts      # Images, quotations, corrections, geo tags
    └── people.ts       # People graph, comments, FAQ

コードベース全体では、次の 2 つの規約が採用されています。

• defineTool() がすべての登録処理をラップします。 各ツールが、対処可能なメッセージを含む isError の結果として失敗を報告し、Markdown または JSON を一貫した形式でレンダリングし、テキストとともに structuredContent を返すことを保証します。
• md() がドキュメントを構築します。 明示的な空行を保持して Markdown の見出しとリストを適切に区切り、null／false は除去して、条件付きの断片がすっきり消えるようにします。

上流の固有の挙動は、呼び出し元にそのまま伝わらないよう、client.ts とツールモジュールで正規化されます。たとえば、カテゴリーのエンドポイントが返す { poet, cat } エンベロープ、詩のペイロードに含まれるネストされた category.cat、URL パラメーターで先頭のスラッシュが必要なことなどです。

開発

npm run build       # compile to dist/
npm run typecheck   # type-check without emitting
npm test            # live smoke test against api.ganjoor.net
npm run inspect     # print real tool output for review
npm run clean

npm test はインメモリトランスポート経由でサーバーを起動し、すべてのツールに十分な説明があることを検証したうえで、稼働中の API に対して 44 個すべてのツールを呼び出します。いずれかの呼び出しがエラー応答を返すと、テストは失敗します。

既知の制限事項

• セマンティック検索が無効になっている場合があります。 Ganjoor の埋め込みバックエンドはオプションです。デプロイ環境で無効になっている場合、ganjoor_semantic_search_poems は 503 を返します。このツールは明確なメッセージを表示し、代わりにペルシャ語のキーワードを使って ganjoor_search_poems を利用するよう案内します。
• リダイレクトの解決は限られています。 Ganjoor は実際に名前を変更したパスについてのみリダイレクトを保存するため、有効な URL の大半は転送先ではなく has_redirect: false を返します。
• 常に認証が必要なツールもあります。 Ganjoor アカウントが必要なエンドポイント（ブックマーク、コメントの投稿、修正のアップロード）は、意図的に対象外です。このサーバーは読み取り専用で、匿名で利用できます。
• 書籍カタログは厳選されています。 ganjoor_list_books は約168の名前付き作品集を対象としていますが、主要な詩人の一部は含まれていません。Hafez の項目はありません。代わりに include_cats: true を指定して ganjoor_get_poet を使うと、各詩人のセクションをルートカテゴリから直接取得できます。
• ページ分割されたエンドポイントには総件数がありません。 上流の API は総件数を報告せずにページ分割するため、総数が不明な場合は total を省略します。has_more は、ページの行数より1つ多く取得して推定します。
• 詩のテキストのカバー範囲は厳選されています。 人物タグ、地理タグ、言語タグはもともと不完全です。通常、結果が空なのはカバー範囲の不足によるものであり、存在しないことの証明ではありません。
• 日付フィールドは近似値の場合があります。 Ganjoor は確度の低い日付にフラグを付けます（validBirthDate / validDeathDate）。呼び出し元が絞り込みできるよう、ツールはこれらのフラグを公開します。

評価

evaluation/evaluation.xml には、検証済みの回答がある読み取り専用の質問が10件含まれています。各質問に回答するには複数のツール呼び出しが必要で、記録する前にライブ API と照合して確認済みです。

npx tsx tests/verify-evaluation.ts   # replays every question through the MCP tools

これらの質問は、単一の検索で答えられるような雑学を意図的に避けています。詩人と世紀を相互に照合し、親族関係のグラフをたどり、詩の韻律をコーパス全体の韻律リストと比較し、引用記録を通じて返歌の連鎖を解決します。

貢献

CONTRIBUTING.md を参照してください。