Hello World Tangle Blueprint 🌐

Tangle Network 向け MCP ブループリント 🌐

� プロジェクトの概要と目的

このプロジェクトは、リモート MCP（Model Context Protocol）サービスを実行するために設計された、Tangle Network 向けのブループリントです。このブループリントの新しいインスタンスをリクエストすると、ユーザーは指定した構成ファイルを持つ新しいサービスインスタンスを取得でき、MCP サーバーをシームレスにデプロイして管理できます。

ブループリントは、Tangle Network 上の AVS の仕様です。AVS とは、ユーザーが指定した期間、任意の計算を実行するオフチェーンサービスです。この MCP ブループリントは、さまざまなランタイム環境で MCP サーバーをデプロイして管理するための強力な抽象化を提供し、開発者が再利用可能な MCP サービスインフラストラクチャを作成できるようにします。

Tangle Network のブループリントの詳細については、プロジェクトのドキュメントを参照してください。

⚙️ 構成の詳細

このブループリントは、ポートを自動管理しながら、さまざまなランタイムの構成をサポートします。すべてのランタイムは、HTTP ベースの通信を行うために内部で SSE（Server-Sent Events）に変換されます。

サポートされるランタイム

• JavaScript（bun ランタイム）での STDIO トランスポート：必要に応じて bun を自動インストールし、bunx を使用して MCP サーバーを実行します
• Python（python3）での STDIO トランスポート：必要に応じて uv を自動インストールし、uvx を使用して MCP サーバーを実行します
• Docker コンテナ：インテリジェントなポート検出、ポートの自動割り当て、環境変数の注入により、Docker コンテナ内で MCP サーバーを実行します

ポート管理とトランスポート変換

このブループリントはポートの割り当てを自動で管理し、すべてのランタイム構成を SSE トランスポートに変換します。

ポートの自動管理：

• システムで利用可能なポートを検出して、自動的にポートを割り当てます
• すべての MCP サーバーに PORT 環境変数を自動的に注入します
• MCP サーバーは、PORT 環境変数で指定されたポートに必ずバインドする必要があります
• ブループリントのリクエストでポートを手動設定する必要はありません

トランスポート変換：

• Web クライアント向けの HTTP ベースの通信
• STDIO トランスポートと SSE トランスポート間での双方向メッセージ転送
• Server-Sent Events によるリアルタイムストリーミング
• クライアントがメッセージを送信するための POST エンドポイント

🔐 認証ワークフロー

認証ワークフローでは、スクリプト generate-auth-token.ts を使用し、チャレンジレスポンス方式でアクセストークンを生成します。

1. チャレンジリクエスト：クライアントが公開鍵と鍵の種類を /v1/auth/challenge に送信します
2. チャレンジレスポンス：サーバーが有効期限付きの暗号学的チャレンジを返します
3. 署名の生成：クライアントが自身の秘密鍵を使用してチャレンジに署名します
4. トークンの検証：クライアントが署名を /v1/auth/verify エンドポイントに送信します
5. アクセストークン：サーバーが有効期間付きのアクセストークンを返します

MCP サーバーの URL にアクセスするとき、認証は Authorization ヘッダーを介して行います。トークンの形式は {token_id}|{token_string} です。

📋 変更履歴と破壊的変更

⚠️ 破壊的変更：最近の更新で、ポートの自動管理が導入されました。移行手順と例について詳しくは、CHANGELOG.md を参照してください。

主な変更点：

• 構成から portBindings フィールドを削除
• PORT 環境変数の自動注入を追加
• MCP サーバーは PORT 環境変数からポートを読み取る必要があります

🚀 使用例とデモ

サンプル設定

fixtures ディレクトリには、さまざまなランタイムタイプのサンプル設定が含まれています。

• fixtures/00_mcp_python3.json：Python MCP サーバーの設定
• fixtures/01_mcp_js.json：Context7 パッケージを使用する JavaScript MCP サーバー
• fixtures/02_mcp_local_docker.json：Redis 環境を使用するローカル Docker MCP サーバー
• fixtures/03_tangle_mcp_docker.json：Tangle 専用の Docker MCP 設定

注：すべてのサンプル設定では、新しい形式が使用されており、portBindings は含まれていません。ポートの割り当てはブループリントによって自動的に処理されます。

ローカルでのセットアップ

ローカルでセットアップを実行するには、DEMO.md の詳細な手順に従ってください。デモでは、以下の内容を説明します。

1. Tangle ネットワークをローカルで起動する
2. ブループリントサービスを起動する
3. 新しいブループリントインスタンスをリクエストする
4. サービスリクエストを承認する
5. MCP サーバーを起動する
6. 認証トークンを生成する
7. MCP Inspector でテストする

内部ワークフロー

内部ワークフローの詳細については、包括的なフローチャートを掲載した mcp-blueprint-flowchart.md をご覧ください。フローチャートでは、以下の内容を示しています。

• ユーザーリクエストの流れと設定の処理
• ランタイムの検出とパッケージ管理
• STDIO から SSE へのトランスポート変換
• サーバーの初期化とエンドポイントの提供
• 認証とクライアント接続の処理

🔄 ワークフローの説明

ブループリントのプロセスは、次の大まかなワークフローに従います。

1. リクエストの受信：設定パラメーターを含むリモート MCP リクエストを受信します
2. 設定の処理：ランタイムタイプ、パッケージ／イメージ、環境変数を分析します
3. ポートの割り当て：使用可能なポートを自動的に割り当て、環境変数 PORT として設定します
4. ランタイムの初期化：
   • Python：パッケージ管理と実行に uv をインストール／使用します
   • JavaScript：パッケージ管理と実行に bun をインストール／使用します
   • Docker：イメージをプルし、公開ポートを検査して、インテリジェントなポートバインディングを使用してコンテナーを作成します
5. トランスポートのセットアップ：STDIO 通信を HTTP 互換の SSE に変換します
6. エンドポイントの公開：/sse および /message エンドポイントを含む HTTP URL を提供します
7. 認証：トークンベースの認証システムによってアクセスを保護します
8. クライアントとの通信：MCP クライアントが HTTP／SSE 経由で接続し、通信できるようにします

📋 前提条件

このプロジェクトを実行するには、マシンに以下のソフトウェアをインストールしておく必要があります。

• Rust
• Forge
• Node.js（認証トークン生成ツールの実行に使用）

また、Tangle Blueprints の作成とデプロイに使用する CLI ツール、cargo-tangle もインストールする必要があります。

Tangle CLI をインストールするには、次のコマンドを実行してください。

Linux、MacOS、Windows（WSL2）でサポートされています

cargo install cargo-tangle --git https://github.com/tangle-network/blueprint

✨ 主な機能

自動ポート管理

• 設定不要：設定ファイルでポートバインディングを指定する必要はありません
• 競合の防止：ポートを自動的に割り当て、ポートの競合を防ぎます
• 環境変数の設定：PORT 環境変数が MCP サーバーに自動的に設定されます
• 幅広い互換性：すべてのランタイムタイプ（Python、JavaScript、Docker）で動作します
• インテリジェントな Docker 処理：Docker イメージから公開ポートを自動的に検出し、必要な場合にのみポートマッピングを設定します

セキュリティと信頼性の強化

• 設定の簡素化：ポート管理の自動化により、攻撃対象領域を縮小します
• プロセスのライフサイクル：適切なクリーンアップとコンテナー管理を行います
• エラー処理：ポートの割り当てに失敗した場合の包括的なエラー処理

🛠️ 開発

前提条件をインストールしたら、プロジェクトをビルドしてデプロイできます。

cargo build

プロジェクトをビルドするには、次を実行します。

cargo tangle blueprint deploy

ブループリントを Tangle ネットワークにデプロイするには、次を実行します。

MCP サーバー開発者向けクイックリファレンス

このブループリント用の MCP サーバーを開発する際は、次の点にご注意ください。

1. 環境変数からポートを読み込む：必ず process.env.PORT（JS）または os.environ['PORT']（Python）を使用します。
2. すべてのインターフェースにバインドする：ホストには 0.0.0.0 または 127.0.0.1 を使用します。
3. ポートを設定しない：サーバーにハードコードされたポートがあれば削除します。
4. ローカルでテストする：ローカルテストでは環境変数 PORT=3000 を設定します。

# Testing your MCP server locally
export PORT=3000
your-mcp-server-command

📜 ライセンス

以下のいずれかのライセンスの下でライセンスされています。

• Apache License, Version 2.0 (LICENSE-APACHE または http://www.apache.org/licenses/LICENSE-2.0)
• MIT ライセンス (LICENSE-MIT または http://opensource.org/licenses/MIT)

どちらを選択するかは任意です。

📬 フィードバックとコントリビューション

このブループリントの改善に向けたフィードバックやコントリビューションをお待ちしています。 GitHub リポジトリでイシューを作成するか、プルリクエストを送信してください。 このブループリントをフォークして拡張した場合も、ぜひお知らせください。

別途明示されない限り、Apache-2.0 ライセンスで定義されているとおり、あなたが本作品への収録を目的として意図的に提出したコントリビューションは、追加の条件や制約なしに、上記のデュアルライセンスの下でライセンスされます。