Skip to main content
Glama
ecarcamo

Sync Licensing MCP Server

by ecarcamo

Sync Licensing MCP Server

音楽のシンクロライセンスプラットフォームのカタログとビジネスロジックを公開するローカルModel Context Protocolサーバー。クリエイティブブリーフによるトラック検索、権利クリアランスの確認、条件付き価格ルールに基づくライセンス見積もり、契約書の発行、使用登録までを処理します。

CC3067 Redes(Universidad del Valle de Guatemala)プロジェクト1のために構築されました。MCPメッセージフローはJSON-RPC 2.0の上に直接実装されており、MCP SDKもFastMCPもフレームワークも使用していません。サーバーパッケージはPython標準ライブラリのみに依存しています。


目次

  1. ビジネスケース

  2. アーキテクチャ

  3. 要件

  4. インストール

  5. カタログの構築

  6. 使用方法

  7. ツールリファレンス

  8. 価格設定ルール

  9. プロトコル詳細

  10. データの出所

  11. テスト

  12. プロジェクト構成

  13. プロジェクトの状態


Related MCP server: MusicBrainz MCP Server

1. ビジネスケース

同期ライセンスは、Epidemic Sound、Artlist、Musicbedなどのプラットフォームのビジネスモデルです。クリエイターや広告代理店は、映像コンテンツでトラックを使用する前にライセンスを購入する必要があります。このプロセスには3つの摩擦があります:

  • クリエイティブブリーフと予算の両方に合うトラックを見つけるのは時間がかかります。

  • トラックの法的ステータスは明確ではありません。クリアされていないサンプルが含まれている場合や、著作権紛争で凍結されている場合があります。

  • 価格は固定されていません。同じトラックでも、Instagramの投稿用と全国テレビキャンペーン用では価格がまったく異なります。

このサーバーは、そのワークフローをアシスタントが連鎖できる5つのツールに変換します。価格表が付いた検索エンジンではありません。料金は条件付きルールから計算され、ツールはクライアントを法的リスクにさらす操作を拒否します。

2. アーキテクチャ

        ┌────────────────────────┐
        │  Host (chatbot / CLI)  │
        └───────────┬────────────┘
                    │  spawns as a subprocess
        ┌───────────▼────────────┐
        │   MCP client           │   client/mcp_cli.py
        └───────────┬────────────┘
                    │  JSON-RPC 2.0 over stdio
                    │  (one JSON object per line)
        ┌───────────▼────────────┐
        │   MCP server           │   synclicense_mcp/
        │                        │
        │   jsonrpc.py  framing  │
        │   server.py   dispatch │
        │   tools.py    5 tools  │
        │   pricing.py  rate card│
        │   contracts.py contracts
        │   catalog.py  catalog  │
        └───────────┬────────────┘
                    │
        ┌───────────▼────────────┐
        │  data/catalog.json     │  built by scripts/seed_catalog.py
        │  data/usage_log.jsonl  │  append-only audit log
        └────────────────────────┘

stdoutはプロトコルトラフィックのみを運びます。サーバーが出力するすべての診断情報はstderrに送られるため、サーバーの出力をパイプしてもストリームが壊れることはありません。

3. 要件

  • Python 3.10以降(3.11で開発)。

  • サーバーを実行するための他の依存関係はありません。

  • requestsはJamendoから実際のメタデータを取得するためだけに必要で、pytestはテストスイートを実行するためだけに必要です。どちらもrequirements.txtに含まれています。

4. インストール

git clone https://github.com/ecarcamo/MCP-Local-Redes.git
cd MCP-Local-Redes

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

このパッケージはインストールされません。リポジトリのルートからインポートされるため、以下のすべてのコマンドはプロジェクトディレクトリから実行されます。

5. カタログの構築

リポジトリにはすでにdata/catalog.jsonにJamendo APIから取得した800曲の実際のトラックを含むカタログが同梱されているため、このセクションをスキップして利用に直接進むことができます。異なるサイズ、異なるシード、または認証情報を必要としないカタログが必要な場合にのみ再構築してください。

オフラインモード(デフォルト、認証情報不要、ネットワーク不要)

python scripts/seed_catalog.py --offline --count 800

決定論的です。同じ--seedは常に同じカタログを生成します。また、既知の3つのトラックを先頭に固定します(TRK-00001はクリア済み、TRK-00002はサンプル保留中、TRK-00003はブロック済み)。これにより、失敗シナリオを簡単にデモンストレーションできます。

Jamendoモード(実際のCreative Commonsメタデータ)

https://devportal.jamendo.com に登録してclient_idを取得し、次に:

cp .env.example .env
# edit .env and set JAMENDO_CLIENT_ID=your_client_id

python scripts/seed_catalog.py --jamendo --count 800

トラックメタデータはAPIから取得されます。基本料金と権利ステータスは引き続きローカルで生成されます(セクション10を参照)。人気度はAPI自身のpopularity_total順序から取得されます。無料のJamendoプランはバーストリクエストをスロットリングし、スロットリングされたページにはエラーではなく空の結果リストで応答するため、スクリプトはページ間で一時停止し、カタログが尽きたと結論する前に空のページを再試行します。

オプション

デフォルト

説明

--offline / --jamendo

--offline

トラックメタデータのソース

--count N

800

書き込むトラック数

--seed N

23016

シミュレートされたビジネスレイヤーのシード

--output PATH

data/catalog.json

カタログの書き込み先

6. 利用

6.1 ガイド付きデモを実行

スクリプト化されたエンドツーエンドの実行で、スモークテストとして役立ちます。サーバーを起動し、完全なライセンス会話を再生し、ワイヤーを通過するすべてのJSON-RPCメッセージを出力します(-->送信、<--受信):

python client/mcp_cli.py --demo

デモでは、ハンドシェイク→tools/list→トラックの検索→クリアランスの確認→見積もり→契約の発行→使用の登録→そして3つの失敗ケース(ブロックされたトラック、別のトラックに属する見積もり、無効な引数)を順に進めます。

--quietを追加すると、生のプロトコルトレースを非表示にして、回答のみを表示します:

python client/mcp_cli.py --demo --quiet

6.2 インタラクティブセッション(主な使用方法)

サーバーを手動で1つずつツールを操作するためのREPL:

python client/mcp_cli.py --interactive

コマンド

説明

list

サーバーが公開するツール

schema <tool>

1つのツールのJSON Schema

call <tool> <json>

JSON引数でツールを呼び出す

vars

以前の回答から記憶されたID

ping

JSON-RPC pingを送信

raw <method> [json]

任意のJSON-RPCメソッドを手動で送信

quit

セッションを閉じる

IDは記憶されます。 ツールが返すすべての*_idは保存され、次の呼び出しで$nameとして再利用できるため、ライセンス交渉全体をIDを1つもコピーせずに入力できます:

mcp> call buscar_pista {"mood": "epico", "instrumental": true, "presupuesto_max": 100, "limite": 3}
   ...
   remembered: $pista_id=TRK-00312

mcp> call verificar_clearance {"pista_id": "$pista_id"}

mcp> call calcular_costo_licencia {"pista_id": "$pista_id", "tipo_uso": "publicidad_online", "territorio": "latam", "exclusividad": "sectorial", "duracion_meses": 12}
   ...
   remembered: $cotizacion_id=COT-719E615733

mcp> call generar_contrato {"pista_id": "$pista_id", "cliente": "Agencia Lumen S.A.", "cotizacion_id": "$cotizacion_id"}
   ...
   remembered: $contrato_id=CTR-F9D1D72B0D

mcp> call registrar_uso {"contrato_id": "$contrato_id", "plataforma": "YouTube", "url_proyecto": "https://youtube.com/watch?v=demo"}

mcp> vars
mcp> quit

$pista_idは、最後の検索の最上位候補にデフォルト設定されます。現在記憶されている内容を確認するには、いつでもvarsを使用します。

6.3 サーバーを単独で実行

python -m synclicense_mcp

その後、stdinでJSON-RPCメッセージを待機します。--catalog PATHを使用して、別のカタログファイルを指定します。

6.4 クライアントなしで通信

トランスポートは改行区切りのJSONだけなので、シェルから直接サーバーを操作できます:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"verificar_clearance","arguments":{"pista_id":"TRK-00001"}}}' \
  | python -m synclicense_mcp

7. ツールリファレンス

ツール

必須引数

戻り値

buscar_pista

(なし — すべてのフィルターはオプション)

候補トラック(id、タイトル、アーティスト、再生時間、基本料金)

verificar_clearance

pista_id

法的ステータス:クリア済み、サンプル保留中、またはブロック済み

calcular_costo_licencia

pista_id、tipo_uso、territorio、exclusividad、duracion_meses

完全な料金内訳、USD合計、cotizacion_id

generar_contrato

pista_id、cliente、cotizacion_id

範囲、期間、金額、制限、contrato_idを含む契約

registrar_uso

contrato_id、plataforma、url_proyecto

ロイヤリティと監査のために記録された使用記録

7.1 buscar_pista

オプションのフィルター:mood、genero、instrumental、duracion_seg_min、duracion_seg_max、presupuesto_max、limite(1–20、デフォルト5)。

  • mood:alegre、epico、melancolico、relajado、tenso、energetico、inspirador、oscuro

  • genero:pop、rock、electronica、hip_hop、jazz、clasica、folk、ambient、cinematica、latina

著作者紛争でブロックされたトラックは除外されます。ライセンスできないため、提供すると誤検出になります。

7.2 verificar_clearance

ステータス

ライセンス可能

効果

libre

はい

担保なし

samples_pendientes

はい

+15%エスクロー追加料金と保留条項

bloqueada

いいえ

著作者紛争。見積もりと契約は拒否されます

7.3 calcular_costo_licencia

引数

許可される値

tipo_uso

redes_sociales、evento_interno、podcast、web_corporativo、publicidad_online、videojuego、tv_nacional、cine

territorio

local、latam、europa、norteamerica、mundial

exclusividad

no、sectorial、total

duracion_meses

0(永久)または1–120

リクエストとレスポンスの例:

--> {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
      "name":"calcular_costo_licencia",
      "arguments":{"pista_id":"TRK-00312","tipo_uso":"redes_sociales",
                   "territorio":"local","exclusividad":"no","duracion_meses":6}}}

<-- {"jsonrpc":"2.0","id":5,"result":{
      "content":[{"type":"text","text":"Quote for TRK-00312 \"Stop!\" ... TOTAL USD 94.50"}],
      "structuredContent":{
        "ok":true,
        "cotizacion_id":"COT-3D18B1547D",
        "pista_id":"TRK-00312",
        "alcance":{"tipo_uso":"redes_sociales","territorio":"local",
                   "exclusividad":"no","duracion_meses":6},
        "desglose":{"tarifa_base_usd":94.5,
                    "multiplicadores":{"tipo_uso":1.0,"territorio":1.0,
                                       "exclusividad":1.0,"vigencia":1.0},
                    "subtotal_usd":94.5,"recargo_escrow_usd":0.0,
                    "total_usd":94.5,"moneda":"USD"},
        "valida_hasta":"2026-09-19T18:15:54+00:00"},
      "isError":false}}

7.4 ツールチェーン

ツールはセッション内でステートフルです。これがユースケースのポイントです:

buscar_pista ──► pista_id
                    ├──► verificar_clearance      (can stop the whole flow)
                    └──► calcular_costo_licencia ──► cotizacion_id
                                                        └──► generar_contrato ──► contrato_id
                                                                                     └──► registrar_uso

generar_contratoは、存在しない、期限切れ(30日)、または別のトラックに対して発行された見積もりを拒否します。registrar_usoは、不明または非アクティブな契約を拒否します。見積もりと契約は1つの接続に属し、セッション間で共有されません。

8. 価格設定ルール

subtotal = tarifa_base × mult_use × mult_territory × mult_exclusivity × mult_term
total    = subtotal + escrow surcharge (15% when the track has pending samples)

使用タイプ

×

地域

×

独占性

×

期間

×

redes_sociales

1.0

local

1.0

no

1.0

≤ 3ヶ月

0.8

evento_interno

1.1

latam

1.8

sectorial

2.0

≤ 6ヶ月

1.0

podcast

1.3

europa

2.2

total

4.5

≤ 12ヶ月

1.5

web_corporativo

1.6

norteamerica

2.4

≤ 24ヶ月

2.2

publicidad_online

2.5

mundial

3.2

≤ 36ヶ月

2.8

videojuego

4.0

> 36ヶ月

3.2

tv_nacional

6.0

永久

3.5

cine

8.0

6ヶ月が基準期間であり、それが1.0に設定されている理由です。見積もりは30日間価格を保持します。

9. プロトコル詳細

トランスポート。 stdio、1行に1つのJSON-RPC 2.0メッセージ、UTF-8、埋め込み改行なし。サーバーはEOFでクリーンに終了します。

プロトコルバージョン。 2025-11-25(推奨)と2025-06-18。クライアントが他のものを要求した場合、サーバーはハンドシェイクを失敗させる代わりに、推奨バージョンで応答します。

メソッド。

メソッド

結果

initialize

ネゴシエートされたバージョン、機能、サーバー情報、指示

notifications/initialized

(通知 — 応答なし)

ping

{}

tools/list

JSONスキーマを持つ5つのツール記述子

tools/call

content、structuredContent、isError

エラーコード。# Sync Licensing MCP Server

音楽のシンクロライセンスプラットフォームのカタログとビジネスロジックを公開するローカルModel Context Protocolサーバーです。クリエイティブブリーフによるトラック検索、権利クリアランスの確認、条件付き価格ルールに基づくライセンス見積もり、契約の発行、使用の登録を行います。

CC3067 Redes(Universidad del Valle de Guatemala)、プロジェクト1のために構築されました。MCPメッセージフローはJSON-RPC 2.0の上に直接実装されています。MCP SDKもFastMCPもフレームワークもありません。サーバーパッケージはPython標準ライブラリのみに依存しています。


目次

  1. ビジネスケース

  2. アーキテクチャ

  3. 要件

  4. インストール

  5. カタログの構築

  6. 使用方法

  7. ツールリファレンス

  8. 価格設定ルール

  9. プロトコル詳細

  10. データの出所

  11. テスト

  12. プロジェクト構成

  13. プロジェクトの状態


1. ビジネスケース

シンクロライセンスは、Epidemic Sound、Artlist、Musicbedなどのプラットフォームのビジネスモデルです。クリエイターや広告代理店は、映像コンテンツでトラックを使用する前にライセンスを購入する必要があります。このプロセスには3つの摩擦があります:

  • クリエイティブブリーフと予算の両方に合う**トラックを見つけるのは遅い。

  • トラックの法的ステータスは明らかではない — クリアされていないサンプルが含まれているか、著作権紛争で凍結されている可能性がある。

  • 価格は固定されていない。同じトラックでも、Instagramの投稿と全国テレビキャンペーンでは価格がまったく異なる。

このサーバーは、そのワークフローをアシスタントが連鎖できる5つのツールに変換します。価格リストが付いた検索エンジンではありません。料金は条件付きルールから計算され、ツールはクライアントを法的リスクにさらす操作を拒否します。

2. アーキテクチャ

        ┌────────────────────────┐
        │  Host (chatbot / CLI)  │
        └───────────┬────────────┘
                    │  spawns as a subprocess
        ┌───────────▼────────────┐
        │   MCP client           │   client/mcp_cli.py
        └───────────┬────────────┘
                    │  JSON-RPC 2.0 over stdio
                    │  (one JSON object per line)
        ┌───────────▼────────────┐
        │   MCP server           │   synclicense_mcp/
        │                        │
        │   jsonrpc.py  framing  │
        │   server.py   dispatch │
        │   tools.py    5 tools  │
        │   pricing.py  rate card│
        │   contracts.py contracts
        │   catalog.py  catalog  │
        └───────────┬────────────┘
                    │
        ┌───────────▼────────────┐
        │  data/catalog.json     │  built by scripts/seed_catalog.py
        │  data/usage_log.jsonl  │  append-only audit log
        └────────────────────────┘

stdoutはプロトコルトラフィックのみを運びます。サーバーが出力するすべての診断情報はstderrに送られるため、サーバーの出力をパイプしてもストリームが壊れることはありません。

3. 要件

  • Python 3.10以降(3.11で開発)。

  • サーバーを実行するための他の依存関係はありません。

  • requestsはJamendoから実際のメタデータを取得するためだけに必要で、pytestはテストスイートを実行するためだけに必要です。どちらもrequirements.txtにあります。

4. インストール

git clone https://github.com/ecarcamo/MCP-Local-Redes.git
cd MCP-Local-Redes

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

パッケージはインストールされません。リポジトリのルートからインポートされるため、以下のすべてのコマンドはプロジェクトディレクトリから実行されます。

5. カタログの構築

リポジトリにはすでにdata/catalog.jsonにJamendo APIから取得した800の実際のトラックを含むカタログが同梱されているため、このセクションをスキップして使用方法に直接進むことができます。異なるサイズ、異なるシード、または認証情報を必要としないカタログが必要な場合にのみ再構築してください。

オフラインモード(デフォルト、認証情報不要、ネットワーク不要)

python scripts/seed_catalog.py --offline --count 800

決定論的です。同じ--seedは常に同じカタログを生成します。また、既知の3つのトラックを先頭に固定します(TRK-00001はクリア済み、TRK-00002はサンプル保留中、TRK-00003はブロック済み)。これにより、失敗シナリオを簡単にデモできます。

Jamendoモード(実際のCreative Commonsメタデータ)

https://devportal.jamendo.com に登録してclient_idを取得し、次に:

cp .env.example .env
# edit .env and set JAMENDO_CLIENT_ID=your_client_id

python scripts/seed_catalog.py --jamendo --count 800

トラックメタデータはAPIから取得されます。基本料金と権利ステータスは引き続きローカルで生成されます(セクション10を参照)。人気度はAPI自身のpopularity_total順序から取得されます。無料のJamendoプランはバーストリクエストをスロットリングし、スロットリングされたページにはエラーではなく空の結果リストで応答するため、スクリプトはページ間で一時停止し、カタログが尽きたと結論する前に空のページを再試行します。

オプション

デフォルト

説明

--offline / --jamendo

--offline

トラックメタデータのソース

--count N

800

書き込むトラック数

--seed N

23016

シミュレートされたビジネスレイヤーのシード

--output PATH

data/catalog.json

カタログの書き込み先

6. 使用方法

6.1 ガイド付きデモを実行

スクリプト化されたエンドツーエンドの実行で、スモークテストとして役立ちます。サーバーを起動し、完全なライセンス会話を再生し、ワイヤーを通過するすべてのJSON-RPCメッセージを出力します(-->送信、<--受信):

python client/mcp_cli.py --demo

デモでは、ハンドシェイク → tools/list → トラックの検索 → クリアランスの確認 → 見積もり → 契約の発行 → 使用の登録 → そして3つの失敗ケース(ブロックされたトラック、別のトラックに属する見積もり、無効な引数)を順に進みます。

--quietを追加すると、生のプロトコルトレースを非表示にして、回答のみを表示します:

python client/mcp_cli.py --demo --quiet

6.2 インタラクティブセッション(主な使用方法)

サーバーを手動で1つずつツールを操作するためのREPL:

python client/mcp_cli.py --interactive

コマンド

説明

list

サーバーが公開するツール

schema <tool>

1つのツールのJSON Schema

call <tool> <json>

JSON引数でツールを呼び出す

vars

以前の回答から記憶されたID

ping

JSON-RPC pingを送信

raw <method> [json]

任意のJSON-RPCメソッドを手動で送信

quit

セッションを閉じる

IDは記憶されます。 ツールが返すすべての*_idは保存され、次の呼び出しで$nameとして再利用できるため、ライセンス交渉全体をIDを1つもコピーせずに入力できます:

mcp> call buscar_pista {"mood": "epico", "instrumental": true, "presupuesto_max": 100, "limite": 3}
   ...
   remembered: $pista_id=TRK-00312

mcp> call verificar_clearance {"pista_id": "$pista_id"}

mcp> call calcular_costo_licencia {"pista_id": "$pista_id", "tipo_uso": "publicidad_online", "territorio": "latam", "exclusividad": "sectorial", "duracion_meses": 12}
   ...
   remembered: $cotizacion_id=COT-719E615733

mcp> call generar_contrato {"pista_id": "$pista_id", "cliente": "Agencia Lumen S.A.", "cotizacion_id": "$cotizacion_id"}
   ...
   remembered: $contrato_id=CTR-F9D1D72B0D

mcp> call registrar_uso {"contrato_id": "$contrato_id", "plataforma": "YouTube", "url_proyecto": "https://youtube.com/watch?v=demo"}

mcp> vars
mcp> quit

$pista_idは、最後の検索の最上位候補にデフォルト設定されます。現在記憶されている内容を確認するには、いつでもvarsを使用してください。

6.3 サーバーを単独で実行

python -m synclicense_mcp

その後、stdinでJSON-RPCメッセージを待機します。--catalog PATHを使用して、別のカタログファイルを指定します。

6.4 クライアントなしで通信する

トランスポートは改行区切りのJSONだけなので、シェルから直接サーバーを操作できます:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"verificar_clearance","arguments":{"pista_id":"TRK-00001"}}}' \
  | python -m synclicense_mcp

7. ツールリファレンス

ツール

必須引数

戻り値

buscar_pista

(なし — すべてのフィルターはオプション)

候補トラック(id、タイトル、アーティスト、再生時間、基本料金)

verificar_clearance

pista_id

法的ステータス:クリア済み、サンプル保留中、またはブロック済み

calcular_costo_licencia

pista_id、tipo_uso、territorio、exclusividad、duracion_meses

完全な料金内訳、USD合計、cotizacion_id

generar_contrato

pista_id、cliente、cotizacion_id

範囲、期間、金額、制限、contrato_idを含む契約

registrar_uso

contrato_id、plataforma、url_proyecto

ロイヤリティと監査のために記録された使用記録

7.1 buscar_pista

オプションのフィルター:mood、genero、instrumental、duracion_seg_min、duracion_seg_max、presupuesto_max、limite(1–20、デフォルト5)。

  • mood:alegre、epico、melancolico、relajado、tenso、energetico、inspirador、oscuro

  • genero:pop、rock、electronica、hip_hop、jazz、clasica、folk、ambient、cinematica、latina

著作権紛争でブロックされたトラックは除外されます。ライセンスできないため、提供すると誤検出になります。

7.2 verificar_clearance

ステータス

ライセンス可能

効果

libre

はい

担保なし

samples_pendientes

はい

+15% エスクロー追加料金と保留条項

bloqueada

いいえ

著作権紛争。見積もりと契約は拒否されます

7.3 calcular_costo_licencia

引数

許可される値

tipo_uso

redes_sociales、evento_interno、podcast、web_corporativo、publicidad_online、videojuego、tv_nacional、cine

territorio

local、latam、europa、norteamerica、mundial

exclusividad

no、sectorial、total

duracion_meses

0(永久)または1–120

リクエストとレスポンスの例:

--> {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
      "name":"calcular_costo_licencia",
      "arguments":{"pista_id":"TRK-00312","tipo_uso":"redes_sociales",
                   "territorio":"local","exclusividad":"no","duracion_meses":6}}}

<-- {"jsonrpc":"2.0","id":5,"result":{
      "content":[{"type":"text","text":"Quote for TRK-00312 \"Stop!\" ... TOTAL USD 94.50"}],
      "structuredContent":{
        "ok":true,
        "cotizacion_id":"COT-3D18B1547D",
        "pista_id":"TRK-00312",
        "alcance":{"tipo_uso":"redes_sociales","territorio":"local",
                   "exclusividad":"no","duracion_meses":6},
        "desglose":{"tarifa_base_usd":94.5,
                    "multiplicadores":{"tipo_uso":1.0,"territorio":1.0,
                                       "exclusividad":1.0,"vigencia":1.0},
                    "subtotal_usd":94.5,"recargo_escrow_usd":0.0,
                    "total_usd":94.5,"moneda":"USD"},
        "valida_hasta":"2026-09-19T18:15:54+00:00"},
      "isError":false}}

7.4 ツールチェーン

ツールはセッション内でステートフルです。これがユースケースのポイントです:

buscar_pista ──► pista_id
                    ├──► verificar_clearance      (can stop the whole flow)
                    └──► calcular_costo_licencia ──► cotizacion_id
                                                        └──► generar_contrato ──► contrato_id
                                                                                     └──► registrar_uso

generar_contratoは、存在しない、期限切れ(30日)、または別のトラックに対して発行された見積もりを拒否します。registrar_usoは、不明または非アクティブな契約を拒否します。見積もりと契約は1つの接続に属し、セッション間で共有されません。

8. 価格設定ルール

subtotal = tarifa_base × mult_use × mult_territory × mult_exclusivity × mult_term
total    = subtotal + escrow surcharge (15% when the track has pending samples)

使用タイプ

×

地域

×

独占性

×

期間

×

redes_sociales

1.0

local

1.0

no

1.0

≤ 3ヶ月

0.8

evento_interno

1.1

latam

1.8

sectorial

2.0

≤ 6ヶ月

1.0

podcast

1.3

europa

2.2

total

4.5

≤ 12ヶ月

1.5

web_corporativo

1.6

norteamerica

2.4

≤ 24ヶ月

2.2

publicidad_online

2.5

mundial

3.2

≤ 36ヶ月

2.8

videojuego

4.0

> 36ヶ月

3.2

tv_nacional

6.0

永久

3.5

cine

8.0

6ヶ月が基準期間であり、それが1.0に位置する理由です。見積もりは30日間価格を保持します。

9. プロトコル詳細

トランスポート。 stdio、1行に1つのJSON-RPC 2.0メッセージ、UTF-8、埋め込み改行なし。サーバーはEOFでクリーンに終了します。

プロトコルバージョン。 2025-11-25(推奨)と2025-06-18。クライアントがそれ以外を要求した場合、サーバーはハンドシェイクを失敗させる代わりに、推奨バージョンで応答します。

メソッド。

メソッド

結果

initialize

ネゴシエートされたバージョン、機能、サーバー情報、指示

notifications/initialized

(通知 — 応答なし)

ping

{}

tools/list

JSON Schemaを持つ5つのツール記述子

tools/call

content、structuredContent、isError

エラーコード。

コード

意味

-32700

構文エラー — 行が有効なJSONではありません

-32600

無効なリクエスト — 不正なエンベロープ

-32601

メソッドが見つかりません

-32602

無効なパラメータ — 引数の欠落、型の不一致、列挙値の範囲外、または不明なツール

-32603

内部エラー

-32002

サーバーが初期化されていません — ハンドシェイクの前にリクエストが到着しました

プロトコルエラーとビジネスエラー。 不正な形式の呼び出しはJSON-RPCのerrorとして返されます。ライセンス規則が拒否する形式が正しい呼び出し(ブロックされたトラック、期限切れのクォート、不明な契約)は、isError: trueと読みやすい説明を含む成功レスポンスとして返されます。モデルはトランスポートの失敗を見るのではなく、理由を読んで軌道を修正できます。

完全な仕様はdocs/SERVER_SPEC.mdにあります。

10. データの出所

トラックメタデータ(タイトル、アーティスト、再生時間、ジャンル、ムード、ライセンス、人気ランキング)は、Creative Commonsカタログを公開するJamendo APIから取得されます。このリポジトリに同梱されているカタログはそのようにして構築されました。オフラインジェネレーターは同じ形をローカルで生成するため、このプロジェクトは認証情報もネットワークアクセスもなしで実行できます。

ビジネス層は意図的にシミュレーションされています。 どのプラットフォームもレートカードや各トラックの内部的な法的ステータスを公開していないため、tarifa_base_usdとestado_derechosは固定シードから現実的な分布(82%クリア済み、13%サンプル保留中、5%ブロック)で生成されます。レートカードの乗数は、Jamendo Licensingなどのプラットフォームの公開ロイヤルティフリーレートカードから設計されました。この範囲はコースの講師によってレビューされ、承認されました。

11. テスト

python -m pytest tests/ -v

スイートは、レートカードの規則、JSON-RPCフレーミング、ハンドシェイク、エラーコード、ツールチェーンとその拒否、シードジェネレーター、そして実際のサーバープロセスを起動してstdioトランスポートで通信するエンドツーエンドテストを1件カバーしています。テストは固定IDではなく権利ステータスでトラックを検索するため、オフライン、Jamendo、または別のシードで再生成されたカタログのどれに対しても合格します。

12. プロジェクト構成

MCP-Local-Redes/
├── synclicense_mcp/          MCP server package (standard library only)
│   ├── __main__.py           entry point: python -m synclicense_mcp
│   ├── jsonrpc.py            JSON-RPC 2.0 framing over stdio
│   ├── server.py             MCP method dispatch
│   ├── tools.py              the five tools: schemas, validation, handlers
│   ├── pricing.py            conditional rate card
│   ├── contracts.py          contracts and usage registration
│   ├── catalog.py            catalog loading and search
│   └── errors.py             business-rule failures
├── client/mcp_cli.py         manual JSON-RPC client (demo + REPL)
├── scripts/seed_catalog.py   catalog builder (offline / Jamendo)
├── data/catalog.json         generated catalog
├── tests/                    pytest suite
└── docs/                     proposal, assignment brief, server specification

13. プロジェクトの状況

この段階で納品されたもの:

  • 承認されたユースケースの5つのツールを備えたstdio上のローカルMCPサーバー。

  • JSON-RPC 2.0とMCPハンドシェイクの手動実装。

  • スクリプト化されたデモと対話型REPLを備えたコマンドラインクライアント。

  • オフラインとJamendoの両モードでのカタログシーディング。

  • テストスイート。

プロジェクトの残りで計画されているもの:

  • Anthropic API上のチャットボットホスト。セッションコンテキストと、すべてのMCPインタラクションの可視ログ付き。

  • 公式のFilesystemおよびGit MCPサーバーとの統合。

  • 同じサーバーのHTTP経由でのリモートデプロイ。

  • Wiresharkキャプチャと、リモートトラフィックのレイヤー別分析。


著者: Esteban Cárcamo (23016) — CC3067 Redes, Section 20

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for Spotify control and synchronized lyrics retrieval that enables playback management, queue navigation, and music search capabilities. It also features perception tools for real-time track analysis, including BPM, key detection, and timestamped lyrics.
    39 npm
    3
    Apache 2.0
  • F
    license
    Not graded
    quality
    C
    maintenance
    A remote MCP server for the Arxpot processing core, enabling music search, metadata retrieval, and download management with remote storage delivery.
    -