MCP

🚀 Index Network MCP Server

Index NetworkのディスカバリープロトコルとChatGPTを統合するModel Context Protocol (MCP) サーバーです。

🚀 クイックスタート

前提条件

• Node.js: バージョン22.12.0以上
• オペレーティングシステム: macOS、Linux、またはWindows (WSL2推奨)
• メモリ: 最小2GB RAM (開発には4GB推奨)
• ポート: 3002番ポートが利用可能 ( MCP_SERVER_PORT で設定可能)
• ネットワーク: npmパッケージとngrokトンネリングのためのインターネットアクセス

インストール

npm install
cd widgets && npm install && cd ..

# 環境を設定する
cp env.example .env
# .envをngrokの認証トークンで編集する (オプション)

開発

npm run dev

これにより、Viteがウォッチモードで起動し、MCPサーバーが自動再起動します。widgets/src/echo/echo.css を編集 → 保存 → 約2秒で変更が反映されます。

テスト

npm test  # MCPインスペクターを起動する

✨ 主な機能

• 🔥 ホットリロード - ウィジェットを編集すると、開発中にすぐに変更が反映されます
• ⚡ 最新のツール - Vite + Reactによる高速ビルドと最適なパフォーマンス
• 🎨 カスタムフック - useWidgetProps、useOpenAiGlobal、useWidgetState を使用して、ChatGPTとのシームレスな統合を実現します
• 🛠️ MCPインスペクター - ChatGPTとの統合なしでウィジェットをテストおよびデバッグできます
• 📦 TypeScript 5.7.2 - コードベースが完全に型付けされており、開発体験が向上します
• 🚀 開発準備完了 - ハッシュ化されたアセットを使用した最適化されたビルドと、適切なMCPプロトコルの実装
• 📝 クリーンなコード - JSDocドキュメントを使用して、TypeScriptのコメントベストプラクティスに従っています

💻 使用例

基本的な使用法

# 前提条件のインストール
npm install
cd widgets && npm install && cd ..

# 環境設定
cp env.example .env
# .envをngrokの認証トークンで編集する (オプション)

# 開発モードで起動
npm run dev

高度な使用法

カスタムウィジェットの開発

// widgets/src/my-widget/MyWidget.tsx
import { useWidgetProps } from '../use-widget-props';
import { useOpenAiGlobal } from '../use-openai-global';

interface MyWidgetProps {
  title: string;
  data: any[];
}

export function MyWidget() {
  const props = useWidgetProps<MyWidgetProps>({ 
    title: '', 
    data: [] 
  });
  const theme = useOpenAiGlobal('theme');
  
  return (
    <div className={`widget ${theme}`}>
      <h3>{props.title}</h3>
      <ul>
        {props.data.map((item, index) => (
          <li key={index}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

環境設定

# 開発環境
NODE_ENV=development npm run dev

# カスタムポートで本番環境
MCP_SERVER_PORT=8080 NODE_ENV=production npm start

# ngrokの認証トークンを使用する
NGROK_AUTHTOKEN=your_token npm run dev

🔧 技術詳細

アーキテクチャ

src/server.ts          # ツール登録付きのMCPサーバー
widgets/src/           # フック付きのReactウィジェット
widgets/dist/          # ビルドされたアセット (ハッシュ化されたファイル名)

ホットリロードパイプライン

ファイル変更 → Vite再ビルド → Nodemon再起動 → 更新されたウィジェット

重要なファイル:

• nodemon.json - ファイル監視設定
• widgets/vite.config.ts - ビルド設定
• package.json - スクリプトと依存関係

📚 ドキュメント

環境変数

ngrokの認証トークンを取得するには: ngrok.com でサインアップし、ngrok config add-authtoken YOUR_TOKEN を実行します。

ChatGPTへの接続

1. ビルド: npm run build
2. 起動: npm start
3. 公開: ngrok http 3002 (または .env で NGROK_AUTHTOKEN を設定する)
4. ChatGPTを次のURLで設定する: https://your-url.ngrok-free.app/mcp

新しいウィジェットの追加

1. ウィジェットの作成

mkdir widgets/src/my-widget

以下のファイルを作成します:

• MyWidget.tsx - Reactコンポーネント
• my-widget.css - スタイル
• index.tsx - エントリーポイント
• index.html - <div id="my-widget-root"> を含むテンプレート

2. Vite設定の更新

widgets/vite.config.ts にエントリを追加します:

input: {
  echo: './src/echo/index.html',
  myWidget: './src/my-widget/index.html'
}

3. ツールの登録

src/server.ts で:

const myWidgetHtml = readFileSync(
  join(__dirname, '../widgets/dist/src/my-widget/index.html'),
  'utf-8'
);

server.registerTool("my-tool", {
  title: "My Tool",
  description: "Tool description",
  inputSchema: z.object({ data: z.string() })
}, async (params) => ({
  content: [{ type: "text", text: "Result" }],
  structuredContent: params,
  _meta: {
    "openai/widgetAccessible": true,
    "openai.com/widget": {
      type: "resource",
      resource: {
        uri: "ui://widget/my-widget.html",
        mimeType: "text/html+skybridge",
        text: myWidgetHtml
      }
    }
  }
}));

ウィジェットフック

import { useWidgetProps } from '../use-widget-props';
import { useOpenAiGlobal } from '../use-openai-global';
import { useWidgetState } from '../use-widget-state';

function MyWidget() {
  const props = useWidgetProps<{ message: string }>();
  const theme = useOpenAiGlobal('theme');
  const [state, setState] = useWidgetState({ count: 0 });
  
  return <div>{props.message}</div>;
}

パフォーマンス

最適化のヒント

• ホットリロード: 開発中の変更は約2秒で反映されます
• ビルド最適化: Viteによる高速ビルドと、キャッシュバスティングのためのハッシュ化されたアセット
• メモリ使用量: node --trace-sync-io を使用して開発中のメモリ消費量を監視します
• バンドルサイズ: ウィジェットは最適な読み込みのために個別のチャンクとしてビルドされます

監視

# 同期I/O操作を監視する
node --trace-sync-io dist/server.js

# メモリ使用量を確認する
node --inspect dist/server.js

開発パフォーマンス

• 静的アセット: ウィジェットのアセットは適切なキャッシュヘッダーで提供されます
• ホットリロード: Viteによる高速な開発反復
• ビルド最適化: キャッシュバスティングのためのハッシュ化されたアセット
• ロギング: 開発デバッグのためのコンソールロギング

トラブルシューティング

一般的な問題

ポート3002がすでに使用されていますか？

# ポート3002を使用しているプロセスを殺す
lsof -ti:3002 | xargs kill -9

# または別のポートを使用する
MCP_SERVER_PORT=3003 npm run dev

ホットリロードが機能していませんか？

• ターミナルで [nodemon] restarting due to changes... が表示されることを確認します
• Viteが実行されていることを確認します: cd widgets && npm run dev
• ビルドキャッシュをクリアします: rm -rf widgets/dist && npm run build

ウィジェットがChatGPTに表示されない場合

• ngrokトンネルがアクティブであることを確認します: ngrok http 3002
• MCPエンドポイントがアクセス可能であることを確認します: curl https://your-url.ngrok-free.app/mcp
• ウィジェットのHTMLがビルドされていることを確認します: npm run build

TypeScriptエラーが発生する場合

• 型チェックを実行します: npm run type-check
• TypeScriptのキャッシュをクリアします: rm -rf node_modules/.cache
• 依存関係を再インストールします: rm -rf node_modules && npm install

環境変数が読み込まれない場合

• .env ファイルが存在することを確認します: cp env.example .env
• 変数名が正確に一致することを確認します (大文字と小文字を区別します)
• 変更後に開発サーバーを再起動します

🤝 コントリビュート

Index NetworkのMCPサーバーの改善にご協力いただけることを歓迎します！以下は始める方法です:

開発環境のセットアップ

1. リポジトリをフォークします
2. あなたのフォークをクローンします: git clone https://github.com/your-username/index-network-mcp.git
3. 依存関係をインストールします: npm install && cd widgets && npm install && cd ..
4. 機能ブランチを作成します: git checkout -b feature/your-feature-name
5. 私たちのコーディング標準に従って変更を加えます
6. 明確な説明付きでプルリクエストを送信します

コーディング標準

• すべての新しいコードにTypeScriptを使用します
• 既存のコードスタイルとパターンに従います
• 新しい機能にはテストを追加します
• 必要に応じてドキュメントを更新します
• すべてのリントが通過することを確認します: npm run lint

コメントのベストプラクティス

このプロジェクトはクリーンなコードのコメント原則に従っています:

• 公開APIのJSDoc: すべてのエクスポートされた関数、クラス、および型は、@param、@returns、および @example タグを使用したJSDocを使用します
• 自己説明的なコード: 説明的なコメントよりも、明確な変数名と小さな関数を優先します
• 最小限のインラインコメント: 明白でないビジネスロジックまたはアーキテクチャ上の決定にのみ // コメントを使用します
• 冗長なコメントを避ける: 明らかなことを述べたり、コードがすでに示していることを繰り返したりしないでください
• 保守可能なドキュメント: コメントをコードの変更と同期させます

良好なコメントの例は以下のファイルにあります:

• widgets/src/use-widget-props.ts - 例付きの包括的なJSDoc
• widgets/src/use-widget-state.ts - 実際の使用例
• src/server.ts - エクスポートされたアイテムとルートハンドラーのJSDoc

問題の報告

バグを見つけた場合や機能要求がある場合は、以下の手順を実行してください:

1. まず既存の問題を確認します
2. 再現手順を明確に記載した新しい問題を作成します
3. 環境の詳細 (Node.js 22.12.0以上、OSなど) を含めます

📄 ライセンス

MIT - LICENSE を参照してください

🔗 参考資料

• Index Network - Web3のディスカバリープロトコル
• ngrok - ローカルホストへの安全なトンネリング
• OpenAI Apps SDK - ChatGPTアプリを構築するためのフレームワーク
• OpenAI Apps SDK Examples - 実装例
• Model Context Protocol TypeScript SDK - 公式MCP SDK
• MCP Inspector - MCPサーバーの視覚的なテストツール