Xava Labs Typescript MCP テンプレート

xava-labs/typescript-agent-framework の MCP (モデル コンテキスト プロトコル) をブートストラップするためのテンプレート リポジトリ。

はじめる

リポジトリをセットアップする

オプションA: このテンプレートを使用する

1. このリポジトリの上部にある「このテンプレートを使用する」ボタンをクリックします

2. 新しいリポジトリをクローンする

オプションB: CloudFlareへのデプロイボタンを使用する

次のボタンをクリックすると、組織内に新しいリポジトリが作成され、Cloudflare を使用して CI/CD がセットアップされます。

注: Deploy コマンドが機能するには、 npm run deploy設定のみが必要です。

オプションC: cloudflare createを使用する

wrangler を使用して、このテンプレートに基づいて新しいプロジェクトを作成できます。

1. 簡単に次のテキストをコピーしてください

xava-labs/mcp-template

2. 次のコマンドを実行し、対話型プロンプトに従って名前を選択し、「Template from GitHub repo」から開始して、使用するテンプレートの上記のテキストを貼り付けます。

npm create cloudflare@latest  --git https://github.com/xava-labs/mcp-template

上記の方法のいずれかを完了したら、ターミナルで次のコマンドを実行して開始します。

npm install
npm run dev

上記は、次の URL を使用してサーバーレス CloudFlare 互換の MCP サーバーをブートストラップします。

• /ws - Websocket接続エンドポイント

• /sse - SSE接続エンドポイント

Related MCP server: Remote MCP Server (Authless)

特徴

• WebSocketクライアントのサポート：リアルタイム双方向通信のための公式WebSocketクライアントが含まれています

• SSEクライアントサポート: サーバーからクライアントへのストリーミング用のServer-Sent Eventsクライアントが含まれています

• MCP Inspector : 開発中に MCP をデバッグおよび監視します

• Cloudflare Workers 統合: エッジコンピューティング機能のために Cloudflare Workers 上に構築

• 統合テスト スイート: ローカル ミニフレア サービス (D1/KV など) との完全な統合テストを実行するための Websocket および SSE テスト ツール。モックなしで機能を簡単にテストできます。

利用可能なスクリプト

• npm run dev : MCP Inspector（ポート6274）とCloudflare Worker（ポート8787）を同時に実行します。

• npm start : Cloudflare Worker（ポート8787）のみを実行します。

• npm test : Vitestでテストを実行する

• npm run deploy : MCPをCloudflare Workersにデプロイします

• npm run cf-typegen : Cloudflare Workers 用の TypeScript 型を生成します (wrangler.jsonc に新しい変更を追加するたびにこれを実行してください)

発達

このテンプレートは、ステートフル接続のためのDurable Objectsを用いたMCPサーバーを実装します。この基本プロジェクト構造では、機能拡張のための2つの主要なアプローチが提供されています。

McpHonoServerDO 実装

デフォルトでは、テンプレートはMCPサーバーと高速で軽量なウェブフレームワークであるHonoを組み合わせたMcpHonoServerDOを使用します。これにより、クリーンなルーティングシステムとミドルウェア機能が提供されます。

ツール、リソース、プロンプトによる拡張

メインのサーバー実装はsrc/server.tsにあり、 McpHonoServerDO拡張します。

export class ExampleMcpServer extends McpHonoServerDO {
  // Required abstract method implementation
  getImplementation(): Implementation {
    return {
      name: 'ExampleMcpServer',
      version: '1.0.0',
    };
  }

  // Configure server by adding tools, resources, and prompts
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
}

機能を追加するには、次のモジュールを使用します。

1. ツール( src/tools.ts ): クライアントが呼び出せる関数を定義する

export function setupServerTools(server: McpServer) {
  server.tool(
    'tool_name',           // Name of the tool
    'Tool description',    // Description
    {                      // Parameters schema using zod
      param1: z.string().describe('Parameter description'),
    },       
    async ({ param1 }) => {
      // Tool implementation
      return {
        content: [
          {
            type: "text",
            text: `Result: ${param1}`
          }
        ]
      };
    }
  );
}

2. リソース( src/resources.ts ): クライアントがアクセスできる永続的なリソースを定義する

export function setupServerResources(server: McpServer) {
  server.resource(
    'resource_name',
    'resource://path/{id}',
    async (uri: URL) => {
      // Resource implementation
      return {
        contents: [
          {
            text: `Resource data`,
            uri: uri.href
          }
        ]
      };
    }
  );
}

3. プロンプト( src/prompts.ts ): プロンプトテンプレートを定義する

export function setupServerPrompts(server: McpServer) {
  server.prompt(
    'prompt_name',
    'Prompt description',
    () => ({
      messages: [{
        role: 'assistant',
        content: {
          type: 'text',
          text: `Your prompt text here`
        }
      }]
    })
  );
}

Honoでルートをカスタマイズする

McpHonoServerDOを使用してカスタム HTTP エンドポイントを追加するには、 setupRoutesメソッドを拡張します。

export class ExampleMcpServer extends McpHonoServerDO {
  // Other methods...

  protected setupRoutes(app: Hono<{ Bindings: Env }>): void {
    // Call the parent implementation to set up MCP routes
    super.setupRoutes(app);
    
    // Add your custom routes
    app.get('/api/status', (c) => {
      return c.json({ status: 'ok' });
    });
    
    app.post('/api/data', async (c) => {
      const body = await c.req.json();
      // Process data
      return c.json({ success: true });
    });
  }
}

McpServerDO 実装 (ネイティブ Cloudflare ルーティング)

HTTPリクエスト処理をより細かく制御する必要がある場合は、 McpServerDO直接拡張することができます。これにより、 fetchメソッドを完全に制御できます。

export class CustomMcpServer extends McpServerDO {
  // Required abstract method implementations
  getImplementation(): Implementation {
    return {
      name: 'CustomMcpServer',
      version: '1.0.0',
    };
  }
  
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
  
  // Override the fetch method for complete control over routing
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    
    // Handle custom routes
    if (path === '/api/custom') {
      return new Response(JSON.stringify({ custom: true }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    // Pass through MCP-related requests to the parent implementation
    return super.fetch(request);
  }
}

このアプローチは、次のことが必要な場合に役立ちます。

• カスタムロジックで特定のルートを処理する

• 複雑なミドルウェアや認証を実装する

• MCP ハンドラーに到達する前にリクエストを傍受または変更する

• 標準の MCP 実装を超えてカスタム WebSocket または SSE エンドポイントを追加する

例

CRUD ToDoリストの例

完全な動作例については、次の内容を示すCRUD Todo リスト MCP の例を参照してください。

• MCPツールを使用した完全なCRUD操作

• 永続性のためのSQLiteデータベース統合

• WebSocket/SSE経由のリアルタイム更新

• 包括的なエラー処理

• 高度なフィルタリングと並べ替え機能

• 豊富なプロンプトとリソース

関連リソース

コアパッケージ

• MCP パッケージ: 高度な機能とテスト ユーティリティを備えたコア MCP 実装

• TypeScript エージェントフレームワーク: エージェントフレームワークを使用して LLM を活用したインテリジェントエージェントを構築します

ドキュメント

• ドキュメント: 近日公開予定!

コミュニティ

私たちのコミュニティに参加して、サポートを受けたり、アイデアを共有したり、プロジェクトに貢献したりしてください。

• Discord : 機能リクエスト、サポート、ディスカッションについては#mcpチャンネルに参加してください

貢献

このテンプレートを改善するための貢献を歓迎します！貢献方法は次のとおりです。

1. リポジトリをフォークする: 変更を加えるためにフォークを作成する

2. ブランチを作成する: 新しいブランチに変更を加える

   git checkout -b feature/your-feature-name

3. 変更をコミットする: 意味のあるコミットを行う

   git commit -m "Add feature: brief description"

4. フォークにプッシュ: 変更をフォークにプッシュします

   git push origin feature/your-feature-name

5. プルリクエストを作成する: 変更の詳細な説明を記載したPRを開きます

プルリクエストガイドライン

• PRには明確で説明的なタイトルを付けてください

• あなたのPRが何をするのかを詳しく説明してください

• 関連する問題を参照してください

• 該当する場合はスクリーンショットまたは例を含めます

• すべてのテストに合格することを確認する

• PRは単一の機能または修正に焦点を絞る

大規模な変更や機能については、プロジェクトの方向性を一致させるために、まず Discord チャンネルで話し合うことをお勧めします。

または、上記の「Cloudflare にデプロイ」ボタンを使用して、GitHub から直接デプロイすることもできます。

ライセンス

マサチューセッツ工科大学