Guitar Practice Routine App — Chord Charts

ギターコードチャート — MCP サーバー

MCP 対応の AI クライアントが Guitar Practice Routine App (GPRA) のギターコードチャートを検索し、 テキストのコード図として表示できる、小規模な読み取り専用の Model Context Protocol サーバーです。

guitarpracticeroutine.com/find-a-chord-chart が提供するものとまったく同じです。コード名を 1 つ受け取り、同じコードライブラリの同梱スナップショットからチャートを 1 つ返します。データベースも、認証も、シークレットもありません。

Am

    E  A  D  G  B  E
    x  o           o
   ==================
 1  |  |  |  |  1  |
   -+--+--+--+--+--+-
 2  |  |  3  2  |  |
   -+--+--+--+--+--+-
 3  |  |  |  |  |  |
   -+--+--+--+--+--+-
 4  |  |  |  |  |  |
   -+--+--+--+--+--+-
 5  |  |  |  |  |  |
   -+--+--+--+--+--+-

x = muted   o = open   digits in grid = fingers (1 index, 2 middle, 3 ring, 4 pinky)
EADGBE

フレットはナット側から上から下へ並び、1 弦（最も音が高い弦）は右端の列になります。標準的なコードボックスの表記と、サイト上のチャートに合わせています。

ツール

ツール	説明
get_chord_chart_by_name	コード名 1 つ（G、Am7、D/F#）に対し、そのコードのウェブサイト上のチャートを 1 つ返します。
get_chord_chart_by_id	すでに返されたチャートを再描画するため、数値 ID で同じチャートを返します。
get_chord_of_the_day	今日のコード・オブ・ザ・デイです。GPRA が Bluesky と Facebook に投稿するコードと同じものです。
send_feedback	エージェントが、コードや機能の不足、問題点、または称賛を報告できます。分析 SDK によって追加され、分析が有効な場合にのみ存在します。

各結果は、チャートの直接リンクの PNG URLから始まり、続いて同じチャートをフェンス付きテキストグリッドで表示します。この URL は、あらゆる環境で使える形式の画像です。Markdown の画像が機能する環境では画像として表示され、機能しない環境ではクリック可能なリンクとして残り、アーティファクト、HTML ページ、保存ファイルにもそのまま使用できます。テキストグリッドは、どちらも使えない場合の代替手段です。

PNG バイト列のインライン表示は、format: "image" または format: "both" を指定した場合に選択できます。画像トークンを消費し、複数のクライアントでは折りたたまれたツールドロワーに埋もれてしまうため、URL で用が足りる現在、デフォルトで送信する価値はありません。format のデフォルトは "text" ですが、この場合も画像 URL は含まれます。クレジット表記は、どのモードでも維持されます。

すべてのツールは、呼び出す理由を説明する context 引数も受け取ります。これは PostHog の MCP SDK によって挿入され、分析でエージェントの意図を把握するために使われます。レスポンスの内容には影響しません。

チャートがユーザーに届くまで

「画像を表示できるか」を確認する機能ネゴシエーションはないため、結果には複数のレイヤーを含め、ホストが理解できるものを使えるようにしています。

レイヤー	表示される場所
テキストグリッド + Chart image: URL	すべての環境。これが最低限の表示です。
MCP Apps ウィジェット（_meta.ui.resourceUri）	MCP Apps を描画するホスト（Claude Code、Cowork、ChatGPT、PostHog Desktop）。
インライン PNG バイト列（format: "image"）	リクエストに応じて、画像コンテンツブロックを表示するホスト。

ウィジェットは ui://gpra-chord-charts/chart/{id} リソースで、コードをあらかじめ埋め込んだ自己完結型 HTML ページに解決されます。JavaScript も、postMessage ブリッジも、クライアントバンドルもありません。これを無視するホストではウィジェットが表示されないだけで、テキストの回答には影響しません。

claude.ai での実測結果です。同じ方法を再び試そうとしている方の参考にしてください。通常の Markdown 画像は、インライン表示ではなく、クリックするとブラウザーのタブを開くプレースホルダーとして表示されます。リンクで囲んだ画像はリンクに折りたたまれ、raw HTML はエスケープされて文字列として表示されます。また、MCP Apps の iframe は取得されますが、マウントされません（ext-apps#671）。この環境では URL がすべてであり、そのためテキストの先頭に置いています。

結果には意図的に structuredContent を含めていません。これを理解するクライアントは、コンテンツブロックの代わりにそれを表示する場合があります。実際に、あるクライアントでは回答が 3 つの JSON フィールドに縮小され、チャート、クレジット表記、行動喚起が失われました。テキストを置き換えてしまう可能性のあるものは、結果に含めません。

ライブラリの内容

標準チューニング（EADGBE）のボイシングを12,708件収録しており、各コード名につきちょうど1件です。このサーバーはあいまい一致やクエリの整形を行いません。ウェブサイトと同じ方法で名前をそのまま渡すため、ツールの説明では、呼び出し元のアシスタントにプレーンなコード名（「G major の弾き方」ではなく「G」）を送るよう求めています。

図はサイトと同様に、ナットから始まる5フレット分のグリッド上に描画されます。そのため、5フレットより上の音を含むボイシングでは、その音がグリッドの外に出ることがあります。画像ではサイトと同様にその音を省略しますが、テキストでは下に「この5フレット分のグリッドより先に押さえる音：5弦（A）6フレット」のように記載します。そのため、図だけでは伝わらない場合でも、画像とテキストの組み合わせで正確に伝えられます。

画像は、サイトのような透明背景に白ではなく、白地に黒で描画します。サイトでは暗色の UI を想定できますが、チャットクライアントの背景色はわからないためです。

クライアントの接続

リモート MCP では、ユーザーはインストール不要でURLを追加します。

https://mcp.guitarpracticeroutine.com/mcp

JSON 設定ファイルで構成するクライアントでは、ストリーム可能な HTTP トランスポートを使用します。

{
  "mcpServers": {
    "gpra-chord-charts": {
      "type": "streamable-http",
      "url": "https://mcp.guitarpracticeroutine.com/mcp"
    }
  }
}

stdio のみを使用するクライアントの場合は、mcp-remote でブリッジします。

{
  "mcpServers": {
    "gpra-chord-charts": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.guitarpracticeroutine.com/mcp"]
    }
  }
}

ローカルで実行する

npm install
npm run build
npm test

npm start          # stdio transport
npm run start:http # HTTP, listens on 127.0.0.1:2112, POST /mcp (set PORT / HOST)

ヘルスチェック：GET /health → ステータス、バージョン、コード数。

クライアントを使わずに、ターミナルから図をプレビューできます。

npx tsx scripts/preview.ts G Am C F Bm D/F#

CORS ヘッダーは設定されていません。Claude とコネクターのディレクトリはサーバー側でデータを取得するため不要ですが、ブラウザベースの MCP クライアントでは必要になります。

コードスナップショットの再構築

GPRA データベースへのアクセスが必要です。ソーステーブルはめったに変更されないため、これは手動で行う手順です。

psql "$DATABASE_URL" -Atf scripts/dump-chords.sql > data/common-chords.raw.json
npm run build:index
npm run build && npm test

build:index はライブラリのフレット範囲をターミナルに出力し、データの異常（押弦音がないボイシング、指番号の欠落、演奏不可能なために省略された音）を報告します。異常を通知せずに正規化して取り除くことはありません。

プライバシー

ホスト版サーバーは、@posthog/mcp を通じて匿名の利用状況分析を記録します。記録される情報は、呼び出されたツール、所要時間、エラーの有無、呼び出し元クライアントの識別情報（接続時の名前とバージョン、および各呼び出し時のユーザーエージェント）、さらに呼び出しの理由を説明するためにエージェントが指定した context 文字列です。Mcp-Session-Id ヘッダーをエコーするクライアントからの呼び出しは、1つの分析セッションにまとめられます。このヘッダーは、クライアント名、バージョン、プロトコルバージョンを含む署名なしトークンです。エージェントが send_feedback を使用した場合は、自由記述のフィードバックも記録されます。認証情報、メールアドレス、電話番号、URL はマスキングされ、各フィールドは2,048文字までに制限されます。個人を識別できる情報は保存されず、個人プロフィールも作成されません。

POSTHOG_API_KEY が設定されていない限り、分析機能は完全に無効です。そのため、stdio 経由を含め、自分で実行する場合はどこにもデータが送信されません。

デプロイ

自分でインスタンスをホストする場合は、deploy/ に systemd ユニットと nginx リバースプロキシの設定ファイルがあります。

クレジット

このコードライブラリは、他の人々の成果によって成り立っています。

• SVGuitar-ChordCollection （@TormodKv による）— このライブラリの基になったコードデータベースです。そのコードデータベース自体も、@T-vK による chord-collection を基にしています。
• SVGuitar（ @omnibrain による）— このライブラリが使用するデータ形式のコード図レンダラーであり、 guitarpracticeroutine.com の図も描画しています。（このサーバーが出力するのはテキストであり、SVG ではありません。）

npm audit に関する注記

npm audit は、svguitar → svgdom を介して間接的に取り込まれる image-size に対して、重大度の高いアドバイザリを3件報告します。これらは ICNS、JXL、HEIF のファイルパーサーにおけるサービス拒否につながる無限ループで、<img> にソースが指定された際に imageSizeFromFile を呼び出す svgdom の HTMLImageElement を通じてのみ発生します。

ここでは画像を生成することはありません。チャートの描画では、コード名と整数 ID からベクター図形を描画します。境界を越える入力は最大64文字の文字列と正の整数のみで、画像ファイルを受け入れたり、取得したり、デコードしたりするコードパスはありません。上流には修正がないため、svgdom が image-size から移行するまで、これらのアドバイザリは表示され続けます。

ライセンス

• コード： MIT — LICENSE を参照してください。
• コードデータの出典： NOTICE を参照してください。
• コードデータ： ボイシングは SVGuitar-ChordCollection に由来しますが、明示されたライセンスがないため、ここではそれらに対するライセンスを主張しません。フィンガリングは、フレットボード上で指を置く位置を示す事実に基づく記述です。データを再利用する場合は、上記のプロジェクトをクレジットしてください。

---