Obyte MCP

obyte-mcp

AI ツールから Obyte に問い合わせるためのローカル stdio MCP サーバーです。1 つのサーバーでメインネットとテストネットの両方に対応します。各ツールで network を省略可能なため、サーバーを 2 つ起動する必要はありません。

obyte-mcp は、Obyte ハブの読み取り、自律エージェントの調査、AA のドライラン、トークンシンボルのヘルパーを、Cursor、VS Code、Codex、Claude Desktop、Claude Code などの MCP クライアントに提供します。

クイックスタート

上のボタンを使うか、お使いのクライアントに対応したコマンドを実行します。

claude mcp add --transport stdio obyte -- npx -y obyte-mcp                    # Claude Code
codex mcp add obyte -- npx -y obyte-mcp                                       # Codex CLI
code --add-mcp '{"name":"obyte","command":"npx","args":["-y","obyte-mcp"]}'   # VS Code
npx -y obyte-mcp install                                                      # every client on this machine

Node.js >=20 が必要です。それ以外の設定は不要です。アカウント、API キー、ネットワークごとの設定は必要ありません。最初からメインネットとテストネットの両方に対応しています。その後、クライアントを再起動し、「この Obyte アドレスの GBYTE 残高は？」のように質問してください。

network を省略した呼び出しのデフォルトをテストネットにするには（両方とも引き続き利用可能です）、上記のコマンドに --network testnet を追加します。

インストール（1 コマンド）

このマシンで検出されたすべての MCP クライアントにサーバーを登録します。各クライアント独自の CLI（code --add-mcp、codex mcp add、claude mcp add）を実行し、Cursor と Claude Desktop の設定ファイルを直接書き換えます。

インストールされていないクライアントは通知なしでスキップされます。実際に変更された内容と、再起動が必要なクライアントだけが報告されます。--client でクライアントを明示的に指定すると、必ず処理が行われます。そのクライアントが検出されない場合は、正確な手動設定手順が表示されます。

まずプレビューします（変更は行いません）。

npx -y obyte-mcp install --dry-run

検出されたすべてのクライアントにインストールします。

npx -y obyte-mcp install

単一のクライアントを指定するか、デフォルトのネットワークを設定します。

npx -y obyte-mcp install --client vscode
npx -y obyte-mcp install --client claude-desktop --network testnet
npx -y obyte-mcp install --client codex --name obyte-testnet --network testnet

フラグ：--client vscode|cursor|codex|claude-desktop|claude-code（デフォルト：検出されたすべてのクライアント）、--name NAME（サーバー名。デフォルトは obyte）、--dry-run、および以下の表にある設定フラグを指定できます。

チェックアウトからはラッパースクリプトを使用できます（必要に応じて最初にビルドします）。

./scripts/install.sh --dry-run          # macOS / Linux
pwsh ./scripts/install.ps1 --dry-run    # Windows

コピー＆ペーストで設定する場合は、npx -y obyte-mcp setup を実行すると、変更を加えずにすべてのクライアント用の設定スニペットが出力されます。1 つのクライアントだけを対象にするには、--print-only --client <name> を追加します。

VS Code

obyte-mcp install --client vscode は code --add-mcp を実行します。手動で設定するには、.vscode/mcp.json（ワークスペース）またはユーザーの settings.json の "mcp" に追加します。

{
  "servers": {
    "obyte": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obyte-mcp"]
    }
  }
}

VS Code では mcpServers ではなく servers を使い、"type": "stdio" が必要です。

Cursor

Cursor には MCP CLI がないため、obyte-mcp install --client cursor は設定ファイルを直接書き換えます（既存のファイルは *.bak にバックアップし、他のサーバー設定は保持します）。ページ上部のボタンでも、ワンクリックで同じ設定が行えます。手動で設定するには、~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）を編集し、Cursor を再起動します。

{
  "mcpServers": {
    "obyte": {
      "command": "npx",
      "args": ["-y", "obyte-mcp"]
    }
  }
}

Codex CLI

obyte-mcp install --client codex は codex mcp add を実行します。手動で設定するには、~/.codex/config.toml に追加します（Codex は JSON ではなく TOML を使用します）。

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

Claude Desktop

Claude Desktop には CLI がないため、obyte-mcp install --client claude-desktop は設定ファイルを直接編集します（既存ファイルを *.bak にバックアップしてマージし、他のサーバー設定は保持します）。手動で設定するには、claude_desktop_config.json を編集し、Claude Desktop を再起動します。

{
  "mcpServers": {
    "obyte": {
      "command": "npx",
      "args": ["-y", "obyte-mcp"]
    }
  }
}

設定ファイルのパス：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Claude Code

obyte-mcp install --client claude-code を実行します。

claude mcp add --transport stdio obyte -- npx -y obyte-mcp

npx の前にある -- は必須です。これがないと、Claude Code が --network などのサーバーフラグを Claude Code のフラグとして解析することがあります。便利なコマンド：claude mcp list、claude mcp get obyte、および Claude Code 内での /mcp。

Claude Desktop / Claude Code 向けワンクリックバンドル（.mcpb）

Anthropic の MCP Bundle 形式（.mcpb、以前は .dxt）を使うと、Claude Desktop、Claude Code、MCP for Windows にワンクリックでインストールできます（VS Code と Codex は .mcpb をサポートしていません）。このリポジトリには manifest.json が含まれています。次のコマンドでバンドルをビルドします。

npm ci --omit=dev   # keep the bundle small (runtime deps only)
npm run bundle      # builds, then runs `mcpb pack` -> obyte-mcp.mcpb

次に、obyte-mcp.mcpb を Claude Desktop で開き、「インストール」をクリックします。バンドルでは、インストール画面に「デフォルトネットワーク」オプションと、任意のテストネットトークンレジストリが表示されます。

これは何か

• stdio のみで通信するローカル MCP サーバーです。
• Obyte のメインネットとテストネットを同時に読み取り／照会／ドライランするためのコネクターです。
• 残高、ユニット、ウィットネス、AA の状態変数、AA ゲッター、AA のドライラン、トークンシンボル、エージェント向けサマリーを扱うツールセットです。

これは何ではないか

• ウォレットではありません。
• 署名ツールではありません。
• トランザクションをブロードキャストするものではありません。
• ローカル TCP ポートを開くサービスではありません。
• 秘密鍵、シードフレーズ、ニーモニック、xprv 値、パスフレーズなどの秘密情報を貼り付ける場所ではありません。

サーバーは stdio のみを使用します。HTTP サーバーを起動せず、ローカル TCP ポートで待ち受けることもありません。

必要条件

• Node.js >=20
• npm / npx
• ローカル stdio サーバーをサポートする MCP クライアント

Obyte の公式ドキュメント：

• https://developer.obyte.org/
• https://developer.obyte.org/autonomous-agents

ネットワークの選択

これが主な特長です。サーバーの起動時にネットワークを選ぶのではなく、呼び出しごとに選択します。

• すべてのツールで、任意の network 引数（"mainnet" または "testnet"）を指定できます。
• 呼び出しで network を省略すると、サーバーはデフォルトネットワークを使用します（--network testnet / OBYTE_NETWORK=testnet を設定していない場合はメインネット）。
• 応答の meta.network と meta.hub には、実際に応答したネットワークが常に示されます。
• 「この残高をテストネットで確認して」 や 「この AA をメインネットでドライランして」 のようにクライアントに依頼すると、適切な network が渡されます。ネットワークが不明確な場合、ツールは先に確認するようドキュメントで定められています。

obyte_get_network_info を使えば、いつでも両ネットワークの現在の設定を確認できます。

金額と小数桁数

ハブから取得した生データ（残高、AA の状態変数、支払い出力、AA の応答）では、金額はアセットの最小単位による整数で表されます。基軸アセットの小数桁数は 9 です。2500000000 bytes = 2.5 GBYTE です。この処理を省くとエージェントが誤った数値を報告するため、サーバーでは次の 3 つの方法でこれを徹底しています。

• 複合ツールが自動的に換算します。 obyte_analyze_address、obyte_analyze_aa、obyte_get_portfolio_summary は、symbol、decimals、raw_total、display_total（すでに 10^decimals で割った値）を含む totals_by_asset / balance_summary ブロックを返します。解決できないアセット（例：テストネットにレジストリがない場合）は unresolved_assets に display_total: null として一覧表示され、換算済みの値として示されることはありません。
• サーバーの指示とツールの説明では、生の整数を決して表示しないこと、まず obyte_resolve_asset / obyte_get_decimals_by_symbol_or_asset で小数桁数を解決すること、AA トリガーを作成する際はユーザー向けの金額を最小単位に換算することを、エージェントに指示しています。
• 基軸アセットの別名はレジストリなしで使えます。base / GBYTE / MBYTE / KBYTE / BYTE の小数桁数は、レジストリが設定されていないテストネット上でもローカルで取得できます。

アセット保有者

obyte_get_asset_holders は、任意のアセット（シンボルまたはアセット ID を指定）の上位保有者を、残高の多い順に返します。生の数量と表示用の数量、および総供給量が含まれ、1 回の呼び出しで最大 100 人の保有者を取得できます。データは Obyte エクスプローラー（ハブとは別の、利便性を目的とした中央集権型サービス）から取得されるため、台帳の状態が反映されるまで多少遅れることがあります。

人が閲覧しやすい表示用に、アセット関連ツールは explorer_asset_url も返します。 https://explorer.obyte.org/asset/<symbol|asset>（テストネット： https://testnetexplorer.obyte.org/asset/<symbol|asset>）。注：エクスプローラーのウェブページに表示される数量はすでに表示単位です。小数桁の換算が必要なのは、ハブのツール出力だけです。

エージェントに自動的に使用させる

エージェントにこのサーバーを使うよう指示する必要はありません。エージェントが積極的に使用するよう、2 つの仕組みを用意しています。

1. MCP サーバーの指示。 initialize 時に、サーバーはホスト（Claude Desktop、Claude Code など）に指示を送信します。ホストはその指示をエージェントのコンテキストに追加します。指示には、ユーザーが Obyte、GBYTE/bytes、自律エージェントに言及した場合、または Obyte 識別子（アドレスは 32 文字の base32 文字列、ユニットハッシュとアセット ID は通常 = で終わる 44 文字の base64 文字列）を貼り付けた場合に、ネットワークと小数桁のルールとともに obyte_* ツールを使うよう記載されています。
2. 利用条件が明記されたツールの説明。 各ツールの説明に、どのような場合に使うかが記載されているため、説明のみを表示するホストでも正しくルーティングできます。

サーバーの指示を無視するホストを使う場合（または特定のプロジェクトでより確実にする場合）は、プロジェクトのメモリファイルである CLAUDE.md（Claude Code）または AGENTS.md（Codex）に次の行を追加してください。

For anything involving Obyte, GBYTE, bytes, autonomous agents (AAs), Obyte units/addresses,
or Obyte token symbols, use the obyte MCP server tools (obyte_analyze_address,
obyte_analyze_unit, obyte_analyze_aa, obyte_resolve_asset, obyte_get_portfolio_summary,
obyte_prepare_aa_dry_run) without being asked. Pass network:"testnet" for testnet questions.
Never show raw smallest-unit amounts: use display_total fields or resolve decimals first.

設定

優先順位の高い順：

1. ネットワークごとの環境変数（例：OBYTE_TESTNET_HUB_ADDRESS）
2. ネットワークごとの CLI フラグ（例：--testnet-hub）
3. 通常の環境変数／CLI フラグ（デフォルトのネットワークにのみ適用）
4. 組み込みのデフォルト値

環境変数	CLI フラグ	適用対象	デフォルト値	説明
OBYTE_NETWORK	--network	デフォルトのネットワーク	mainnet	呼び出しで network が省略された場合に使用するネットワーク
OBYTE_HUB_ADDRESS	--hub	デフォルトのネットワーク	ネットワークのデフォルト値	カスタムハブ URL
OBYTE_TOKEN_REGISTRY_ADDRESS	--token-registry	デフォルトのネットワーク	Mainnet のレジストリ／未設定	トークンレジストリ AA
OBYTE_MAINNET_HUB_ADDRESS	--mainnet-hub	mainnet	https://obyte.org/api	カスタム Mainnet ハブ
OBYTE_TESTNET_HUB_ADDRESS	--testnet-hub	testnet	https://testnet.obyte.org/api	カスタム Testnet ハブ
OBYTE_MAINNET_TOKEN_REGISTRY_ADDRESS	--mainnet-token-registry	mainnet	公式レジストリ	Mainnet レジストリ AA
OBYTE_TESTNET_TOKEN_REGISTRY_ADDRESS	--testnet-token-registry	testnet	未設定	Testnet レジストリ AA
OBYTE_REQUEST_TIMEOUT_MS	--timeout-ms	両方	20000	ハブリクエストのタイムアウト、1000..120000
OBYTE_MAX_CONCURRENCY	--max-concurrency	両方	4	同時に実行するハブリクエスト数、1..10
OBYTE_MAX_OUTPUT_BYTES	--max-output-bytes	両方	262144	ツール出力の最大バイト数、16384..1048576
OBYTE_NO_UPDATE_CHECK	—	—	未設定	npm のバージョンチェックを無効にする場合に設定します（NO_UPDATE_NOTIFIER も尊重されます）

デフォルトのハブ：

• Mainnet：https://obyte.org/api
• Testnet：https://testnet.obyte.org/api

カスタムハブ URL のポリシー（ハブの上書き設定すべてに適用）：

• https: は許可されます。
• http: は localhost、127.0.0.1、::1 の場合にのみ許可されます。
• URL の認証情報は拒否されます。
• HTTP 以外のプロトコルは拒否されます。

更新

ユーザーへの更新情報の通知方法

サーバーはプロセスごとに一度、npm レジストリを確認します（タイムアウトは3秒、失敗しても通知せず、OBYTE_NO_UPDATE_CHECK=1で無効化できます）。結果は次の3か所に表示されます。

• obyte_get_network_infoはupdateブロック（current、latest、update_available）を返します — エージェントには、利用可能な更新があればユーザーに知らせるよう指示されています。
• obyte-mcp doctorはupdateチェック行を表示します（情報提供のみで、doctorが失敗することはありません）。
• 起動時にupdate_available診断情報がstderrに書き込まれます（クライアントのMCPログで確認できます）。

デフォルトのバージョンを固定しないnpx -y obyte-mcp設定を使っているユーザーは、次回クライアントを再起動すると新しいバージョンが自動的に適用されます。通知が主に関係するのは、バージョンを固定している場合、.mcpbバンドルを使っている場合、グローバルインストールの場合です。変更履歴を確認するには、GitHubリポジトリの（Releases）をウォッチしてください。

更新方法

サーバーはnpx経由で実行され、公開済みの最新バージョンが解決されます。新しいリリースに更新する方法は、登録方法によって異なります。

• npxベースの設定（上記のすべてのスニペットでのデフォルト）。 npxはパッケージをキャッシュします。次回の起動時に最新バージョンを取得できるようキャッシュをクリアし、クライアントを再起動してください。

  npx -y obyte-mcp@latest --version     # fetch + print the newest version
  npm cache clean --force               # optional: force-drop the npx cache
  

  設定でバージョンを固定することもできます。たとえば["-y", "[email protected]"]のように指定し、更新する際にバージョンを上げます。

• Claude Desktop / Claude Code / VS Code / Codex。 再登録は不要です。同じnpxコマンドを呼び出します。上記のとおりパッケージを更新して、クライアントを再起動してください。インストーラーを再実行する場合（たとえばフラグを変更した後）は、--nameを使って同じエントリを上書きします。

  npx -y obyte-mcp@latest install
  

• .mcpbバンドル。 新しいソースからバンドルを再構築し（npm ci --omit=dev && npm run bundle）、Claudeに新しいobyte-mcp.mcpbを再インストールします。以前のバージョンは置き換えられます。

• グローバルインストール（npm i -g obyte-mcpを使った場合）。 npm update -g obyte-mcpを実行します。

実行中のバージョンはnpx -y obyte-mcp --versionとnpx -y obyte-mcp doctorで確認できます。

推奨ツール

エージェント向けのタスクでは、まずこれらを使用してください。すべてnetworkを任意で指定できます。

• obyte_analyze_address：小数桁を考慮したbalance_summaryを含む残高、プロフィールの単位、定義、アテステーション、任意の履歴を返します。
• obyte_analyze_unit：ジョイントと、任意のAAレスポンスチェーンを返します。
• obyte_analyze_aa：balance_summaryを含むAAの残高、選択した状態変数、任意のレスポンスを返します。
• obyte_resolve_asset：1回の呼び出しでアセット／シンボル／小数桁を解決し、explorer_asset_url（保有者ページ）を返します。
• obyte_get_asset_holders：アセットの上位保有者（エクスプローラーのデータを参照）、生の数量と表示用数量、供給量を返します。1回の呼び出しにつき最大100件です。
• obyte_prepare_aa_dry_run：AAトリガーを検証し、ドライランを実行します。
• obyte_get_portfolio_summary：最大20件のアドレスの残高と、totals_by_assetによる表示用合計を返します。

Raw Hubツール

Obyteのハブ／クライアントメソッドを反映する高度なツールです（それぞれnetworkを任意で指定できます）。

• obyte_get_network_info（両方のネットワークの設定を返します）
• obyte_get_last_mci
• obyte_get_peers
• obyte_get_witnesses
• obyte_get_joint
• obyte_get_balances
• obyte_get_profile_units
• obyte_get_definition
• obyte_get_data_feed
• obyte_get_history
• obyte_get_attestation
• obyte_get_attestations
• obyte_get_aa_response_chain
• obyte_get_aa_responses
• obyte_get_aas_by_base_aas
• obyte_dry_run_aa
• obyte_execute_getter
• obyte_get_aa_balances
• obyte_get_aa_state_vars

Symbol Tools

• obyte_get_official_token_registry_address
• obyte_get_symbol_by_asset
• obyte_get_asset_by_symbol
• obyte_get_decimals_by_symbol_or_asset

レジストリのシンボルは大文字のため、検索前にシンボル入力は大文字に変換されます。ousd と OUSD は同じアセットとして解決されます。アセット ID は base64 形式で、大文字と小文字が区別されます。選択したレジストリにないシンボルは、注記とともに asset: null, symbol: null として返されます。作り出した一致が返されることはありません。

ベースアセットの小数桁数（エイリアスでは大文字と小文字が区別されません）：

• base と GBYTE：9
• MBYTE：6
• KBYTE：3
• BYTE：0

Mainnet のデフォルトのトークンレジストリ：

O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ

testnet でシンボルを検索するには、レジストリを設定するか、呼び出しごとに token_registry_address を渡してください。

npx -y obyte-mcp --testnet-token-registry YOUR_TESTNET_REGISTRY_AA

ツールの動作

すべてのツールの応答は JSON テキストのエンベロープです。meta.network と meta.hub には、呼び出しに応答したネットワークが示されます。

成功：

{
  "ok": true,
  "meta": {
    "network": "testnet",
    "hub": "https://testnet.obyte.org/api",
    "tool": "obyte_get_balances",
    "request_id": "...",
    "duration_ms": 123,
    "retry_count": 0,
    "truncated": false
  },
  "data": {}
}

エラー：

{
  "ok": false,
  "meta": {
    "network": "mainnet",
    "hub": "https://obyte.org/api",
    "tool": "obyte_get_balances",
    "request_id": "...",
    "duration_ms": 123,
    "retry_count": 0,
    "truncated": false
  },
  "error": {
    "code": "HUB_ERROR",
    "message": "...",
    "details": {}
  }
}

エラーコード：

• VALIDATION_ERROR
• CONFIG_ERROR
• HUB_ERROR
• TIMEOUT
• NETWORK_ERROR
• OUTPUT_TOO_LARGE
• SECRET_INPUT_REJECTED
• INTERNAL_ERROR

入力制限

• アドレス配列：最大 20
• オラクル配列：最大 10
• State var のプレフィックス：最大 128 文字
• 汎用 JSON ペイロード：最大 64KB
• すべてのオブジェクトスキーマは厳密で、未知のフィールドを拒否します（省略可能な network を除く）

出力制限と切り詰め

サーバーはシリアライズされた UTF-8 出力のバイト数を測定します。出力が OBYTE_MAX_OUTPUT_BYTES を超える場合、meta や error は変更せず、data のみを切り詰めます。

方針：

• 配列は収まる分の先頭の項目を保持し、{ "__truncated__": true, "omitted_items": N } を追加します。
• オブジェクトは上限に収まるまでキーを保持し、__truncated_keys__: { "omitted_keys": N, "first_omitted_keys": [...] } を追加します（省略されたキーの一覧は要約され、すべてがそのまま列挙されることはありません）。
• 文字列は UTF-8 の安全な境界で切り詰められ、末尾に ...[truncated] が付きます。
• AA の State var や残高マップなどのマップ形式の出力は、返却前にキーでソートされます。
• 安全に切り詰めてもエンベロープが上限に収まらない場合、サーバーは OUTPUT_TOO_LARGE を返します。

切り詰めメタデータ：

• meta.truncated
• meta.output_bytes_before_truncation
• meta.output_bytes_after_truncation
• meta.truncation_reason

再試行ポリシー

サーバーが再試行するのは、純粋な読み取りツールのみです。

デフォルト：

• 最大試行回数：2
• ジッターを加えたバックオフ：約 250ms、続いて 750ms
• 再試行対象：一時的なネットワークエラー、タイムアウト、HTTP 408、429、5xx
• 再試行対象外：検証エラー、ハブの論理エラー、大半の 4xx、シークレットガードによる拒否
• ドライランツールはデフォルトでは再試行されません

Witnesses キャッシュ

Witnesses は次の条件でキャッシュされます。

• メモリ内のみ
• プロセスごと
• network + hub ごと（mainnet と testnet のキャッシュは独立しています）
• TTL：10 minutes

obyte_get_witnesses は update=true を受け付け、強制的に更新できます。obyte_get_history は、明示的に witnesses が渡されるか、update_witnesses=true が指定されない限り、キャッシュされた witnesses を使用します。

ツールのアノテーション

すべてのツールに MCP アノテーションが含まれます。

• title
• readOnlyHint: true
• destructiveHint: false
• openWorldHint: true

純粋な読み取りツールには、次のアノテーションも含まれます。

• idempotentHint: true

ドライランツールには、冪等性のマークが付きません。

セキュリティに関する注意

シークレットガード

サーバーは、必要としない鍵の素材を拒否します。拒否対象のフィールド名：

• private_key / privkey
• secret_key
• seed / seed_phrase
• mnemonic
• xprv / tprv
• passphrase
• wif

フィールド名にかかわらず、拒否される値：xprv/tprv の拡張鍵、およびニーモニックのようなフレーズ。

このガードは、16 進数に対して意図的にフィールド名を基準にしています。AA のトリガーや getter の引数には、Ethereum の txid（0x + 64 桁の 16 進数）、sha256 ハッシュ、secret_hash などのハッシュタイムロックのフィールドといった、不透明なデータが正当に含まれます。そのため、64 文字の 16 進数文字列は、鍵を保持すると明示するフィールド名（key、sk、priv、wif）の下にある場合にのみ拒否され、ハッシュに関する名前の下では拒否されません。公開値が依然として拒否される場合は、ツールを呼び出す前にフィールド名を変更してください。このサーバーがシークレットを必要とすることはありません。

プロンプトインジェクション

Ledger データ、AA の状態変数、トークンの説明、シンボル、プロフィールデータ、ハブからの応答は、信頼できない外部コンテンツです。エージェントはこれらを指示ではなくデータとして扱う必要があります。

シンボルレジストリの信頼モデル

トークンレジストリのマッピングは利便性のためのメタデータであり、資産が正当であることの証明ではありません。カスタムレジストリは、明示的にユーザーが信頼する入力です。選択したレジストリの外では、シンボルは一意ではありません。

診断

MCP の stdio 実行中、stdout は JSON-RPC プロトコルメッセージ専用です。

診断情報は JSON Lines 形式で stderr に書き込まれます。

{"ts":"2026-07-07T12:00:00.000Z","package":"obyte-mcp","level":"error","event":"mcp_stdio_error","message":"..."}

install、setup、doctor、--help、--version は MCP stdio を起動せず、通常の出力を stdout に書き込むことができます。

リソース

サーバーは次のリソースを公開します。

• obyte://docs/overview
• obyte://docs/autonomous-agents
• obyte://docs/tools
• obyte://config/current
• obyte://examples/common-tasks
• obyte://security/trust-model

プロンプト

サーバーは次のプロンプトを公開します。

• analyze_obyte_address
• inspect_obyte_unit
• debug_aa_response
• resolve_obyte_asset
• plan_aa_dry_run
• summarize_portfolio

よくある AI タスク

MCP クライアントに次のように依頼できます。

• 「この Obyte アドレスの testnet 上の残高を確認し、資産について説明してください。」
• 「mainnet 上でこの資産 ID をシンボルと小数桁数に解決してください。」
• 「この資産を保有しているのは誰ですか？」（資産を解決し、エクスプローラーの保有者ページへのリンクを表示します）
• 「この AA トリガーが失敗した理由を調べてください。」
• 「testnet 上でこの AA トリガーをドライランしてください。」
• 「このプレフィックスを持つ AA 状態変数を要約してください。」
• 「このユニットを分析し、AA 応答チェーンを追跡してください。」

MCP Inspector

公開済みパッケージに対して実行します。

npx -y @modelcontextprotocol/inspector npx -y obyte-mcp

ローカルビルドに対して実行します。

npm install
npm run build
npx -y @modelcontextprotocol/inspector node dist/index.js

配布とディレクトリへの登録

すべてのクライアントに MCP サーバーを一度にインストールする、唯一の公式 CLI はありません。 https://github.com/modelcontextprotocol が提供する公式の構成要素は次のとおりです。

• MCP Registry（server.json ＋ mcp-publisher）：検索と配布に使用します。レジストリに対応したクライアントやディレクトリは、ここからクライアントごとのインストール設定を生成します。
• MCP Bundles（.mcpb）：Claude Desktop ／ Claude Code ／ MCP for Windows 用のワンクリックローカルインストールです（上記のバンドルのセクションを参照してください）。

obyte-mcp install コマンドは、各クライアント独自の CLI を実行して残りの課題を補い、1 つのコマンドで VS Code、Cursor、Codex、Claude Desktop、Claude Code に対応します。

公式 MCP Registry

レジストリがホストするのはメタデータであり、パッケージの成果物ではありません。npm パッケージはあらかじめ公開されている必要があり、npm の所有権は package.json の mcpName フィールドで検証されます。

{
  "mcpName": "io.github.Taump/obyte-mcp"
}

対応するレジストリのメタデータは server.json にあります。新しい npm バージョンを公開してから、mcp-publisher を使用します。

npm run typecheck
npm test
npm run build
npm publish

# macOS/Linux via release tarball
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

mcp-publisher login github
mcp-publisher publish

公開を確認します。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Taump/obyte-mcp"

GitHub 認証を使用する場合、レジストリの名前空間は GitHub オーナーと大文字・小文字も含めて完全に一致する必要があります。レジストリは GitHub のログイン名をそのまま使用して権限を構築し、大文字・小文字を区別して照合するためです（レジストリの Issue #689）。オーナーは Taump なので、名前は io.github.Taump/obyte-mcp となり、package.json の mcpName も一字一句一致させる必要があります。npm の所有権検証では、両者が完全に一致するかが比較されます。Taump/obyte-mcp を所有するアカウントで認証して公開するか、そのリポジトリ内の GitHub Action から公開してください。

ローカル開発

git clone https://github.com/Taump/obyte-mcp.git
cd obyte-mcp
npm install
npm run typecheck
npm test
npm run build
node dist/index.js --help

プロジェクト構成：

• src/index.ts：CLI エントリーポイント（サーバー／インストール／セットアップ／診断）
• src/cliArgs.ts：引数の解析
• src/config.ts：デュアルネットワーク実行時設定と URL ポリシー
• src/server.ts：stdio MCP ランタイム（ネットワークごとにハブクライアントを 1 つ使用）
• src/obyteClient.ts：Obyte ハブの HTTP クライアント
• src/tools.ts：MCP ツールの登録と呼び出しごとのネットワークルーティング
• src/install.ts：クライアント CLI インストーラー／Claude Desktop 設定の書き込み
• src/configSnippets.ts：クライアントごとの設定とコマンドの生成
• src/resources.ts、src/prompts.ts、src/symbols.ts、src/schemas.ts
• scripts/sync-version.mjs：package.json のバージョンを manifest.json ／ server.json に反映

互換性マトリクス

コンポーネント	状態
Node.js	>=20
MCP SDK	@modelcontextprotocol/server@^2.0.0
トランスポート	ローカル stdio のみ
VS Code	ワンクリックバッジ / code --add-mcp / .vscode/mcp.json
Cursor	ワンクリックバッジ / ~/.cursor/mcp.json
Codex CLI	codex mcp add / ~/.codex/config.toml
Claude Desktop	設定ファイル / .mcpb バンドル
Claude Code	claude mcp add / .mcpb バンドル
macOS / Linux	対応
Windows	クライアント環境で Node/npx を利用できる場合に対応
Obyte mainnet + testnet	両方を同時に提供
カスタムハブ	HTTPS のみ。開発用の localhost HTTP も利用可能

リリースチェックリスト

バージョンを記載する場所は package.json だけです。src/constants.ts は実行時にその値を読み取り、scripts/sync-version.mjs は（自身では読み取れない）manifest.json と server.json に値を反映します。値が食い違うと npm test は失敗し、npm publish はパッケージ化の前に再同期します。

npm version 0.3.0    # bump package.json, sync manifest.json + server.json, commit, tag
npm publish          # prepublishOnly: sync + typecheck + test + build

package.json を手動で編集しても問題ありません。npm run sync-version を実行するか、そのまま公開してください（公開時に同期されます）。npm run sync-version -- --check は、書き込みを行わずに不整合を報告します。

npm への公開によって更新が届くのは、設定でバージョンを固定せずに npx -y obyte-mcp を使っているユーザーだけです（上記のすべてのスニペットが該当します）。ほかの配布経路は、明示的に更新する必要があります。

mcp-publisher publish    # MCP registry entry is version-pinned
npm run bundle           # rebuild obyte-mcp.mcpb, then attach it to the GitHub release

公開前に：

npm run typecheck
npm test
npm run build
npm pack --dry-run
npx -y ./obyte-mcp-*.tgz --help

また、以下も実施してください。

• パッケージ化した tarball を MCP Inspector でテストします。
• 各クライアントについて obyte-mcp install --dry-run をテストします。
• VS Code、Cursor、Codex、Claude Desktop、Claude Code の設定を確認します。
• Cursor と VS Code のインストールバッジが引き続き有効であることを確認します。
• .mcpb バンドルをビルドし、Claude Desktop にインストールします。
• mcpName を含む npm バージョンを公開します。
• mcp-publisher を使って server.json を Official MCP Registry に公開します。
• README の例が実際の CLI 出力と一致することを確認します。
• 変更履歴と互換性に関する注意事項を記載して GitHub リリースを作成します。