MCP TypeScript SDK

MCP TypeScript SDK

目次

• 概要
• インストール
• クイックスタート
• MCP とは？
• 主な概念
  • サーバー
  • リソース
  • ツール
  • プロンプト
• サーバーの実行
  • stdio
  • SSE を使用した HTTP
  • テストとデバッグ
• 例
  • エコーサーバー
  • SQLite エクスプローラー
• 高度な使い方
  • 低レベルサーバー
  • MCP クライアントの作成
  • サーバーの機能

概要

Model Context Protocol を使用すると、アプリケーションはコンテキストの提供と実際の LLM とのやり取りを分離し、標準化された方法で LLM にコンテキストを提供できます。この TypeScript SDK は MCP 仕様全体を実装しており、次のことを簡単に行えます。

• 任意の MCP サーバーに接続できる MCP クライアントの構築
• リソース、プロンプト、ツールを公開する MCP サーバーの作成
• stdio や SSE などの標準的なトランスポートの使用
• すべての MCP プロトコルメッセージとライフサイクルイベントの処理

インストール

npm install @modelcontextprotocol/sdk

クイックスタート

計算ツールといくつかのデータを公開する、シンプルな MCP サーバーを作成してみましょう。

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create an MCP server
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Add an addition tool
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Add a dynamic greeting resource
server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

MCP とは？

Model Context Protocol（MCP）を使うと、LLM アプリケーションにデータや機能を安全かつ標準化された方法で公開するサーバーを構築できます。LLM とのやり取りに特化した Web API のようなものと考えてください。MCP サーバーでは、次のことができます。

• リソースを通じてデータを公開する（GET エンドポイントのようなもので、情報を LLM のコンテキストに読み込むために使用します）
• ツールを通じて機能を提供する（POST エンドポイントのようなもので、コードを実行したり、それ以外の副作用を発生させたりするために使用します）
• プロンプトを通じてやり取りのパターンを定義する（LLM とのやり取りに使用する再利用可能なテンプレートです）
• その他さまざまな機能を提供する

主な概念

サーバー

McpServer は MCP プロトコルの中核となるインターフェースです。接続管理、プロトコルへの準拠、メッセージのルーティングを処理します。

const server = new McpServer({
  name: "My App",
  version: "1.0.0"
});

リソース

リソースを使用して、LLM にデータを公開します。REST API の GET エンドポイントに似ており、データを提供しますが、負荷の高い計算や副作用を伴う処理は行わないことが想定されています。

// Static resource
server.resource(
  "config",
  "config://app",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: "App configuration here"
    }]
  })
);

// Dynamic resource with parameters
server.resource(
  "user-profile",
  new ResourceTemplate("users://{userId}/profile", { list: undefined }),
  async (uri, { userId }) => ({
    contents: [{
      uri: uri.href,
      text: `Profile data for user ${userId}`
    }]
  })
);

ツール

ツールを使うと、LLM はサーバーを通じてアクションを実行できます。リソースとは異なり、ツールは計算を実行し、副作用を伴うことが想定されています。

// Simple tool with parameters
server.tool(
  "calculate-bmi",
  {
    weightKg: z.number(),
    heightM: z.number()
  },
  async ({ weightKg, heightM }) => ({
    content: [{
      type: "text",
      text: String(weightKg / (heightM * heightM))
    }]
  })
);

// Async tool with external API call
server.tool(
  "fetch-weather",
  { city: z.string() },
  async ({ city }) => {
    const response = await fetch(`https://api.weather.com/${city}`);
    const data = await response.text();
    return {
      content: [{ type: "text", text: data }]
    };
  }
);

プロンプト

プロンプトは、LLM がサーバーと効果的にやり取りするための再利用可能なテンプレートです。

server.prompt(
  "review-code",
  { code: z.string() },
  ({ code }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Please review this code:\n\n${code}`
      }
    }]
  })
);

サーバーの実行

TypeScript の MCP サーバーがクライアントと通信するには、トランスポートに接続する必要があります。サーバーの起動方法は、選択するトランスポートによって異なります。

stdio

コマンドラインツールや直接的な統合に使用します。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "example-server",
  version: "1.0.0"
});

// ... set up server resources, tools, and prompts ...

const transport = new StdioServerTransport();
await server.connect(transport);

SSE を使用した HTTP

リモートサーバーの場合は、Server-Sent Events（SSE）エンドポイントを備えた Web サーバーと、クライアントがメッセージを送信するための別のエンドポイントを起動します。

import express, { Request, Response } from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

const server = new McpServer({
  name: "example-server",
  version: "1.0.0"
});

// ... set up server resources, tools, and prompts ...

const app = express();

// to support multiple simultaneous connections we have a lookup object from
// sessionId to transport
const transports: {[sessionId: string]: SSEServerTransport} = {};

app.get("/sse", async (_: Request, res: Response) => {
  const transport = new SSEServerTransport('/messages', res);
  transports[transport.sessionId] = transport;
  res.on("close", () => {
    delete transports[transport.sessionId];
  });
  await server.connect(transport);
});

app.post("/messages", async (req: Request, res: Response) => {
  const sessionId = req.query.sessionId as string;
  const transport = transports[sessionId];
  if (transport) {
    await transport.handlePostMessage(req, res);
  } else {
    res.status(400).send('No transport found for sessionId');
  }
});

app.listen(3001);

テストとデバッグ

サーバーをテストするには、MCP Inspectorを使用できます。詳しくは、その README を参照してください。

例

エコーサーバー

リソース、ツール、プロンプトの使用例を示すシンプルなサーバーです。

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "Echo",
  version: "1.0.0"
});

server.resource(
  "echo",
  new ResourceTemplate("echo://{message}", { list: undefined }),
  async (uri, { message }) => ({
    contents: [{
      uri: uri.href,
      text: `Resource echo: ${message}`
    }]
  })
);

server.tool(
  "echo",
  { message: z.string() },
  async ({ message }) => ({
    content: [{ type: "text", text: `Tool echo: ${message}` }]
  })
);

server.prompt(
  "echo",
  { message: z.string() },
  ({ message }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Please process this message: ${message}`
      }
    }]
  })
);

SQLite エクスプローラー

データベースとの連携を示す、より複雑な例です。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import sqlite3 from "sqlite3";
import { promisify } from "util";
import { z } from "zod";

const server = new McpServer({
  name: "SQLite Explorer",
  version: "1.0.0"
});

// Helper to create DB connection
const getDb = () => {
  const db = new sqlite3.Database("database.db");
  return {
    all: promisify<string, any[]>(db.all.bind(db)),
    close: promisify(db.close.bind(db))
  };
};

server.resource(
  "schema",
  "schema://main",
  async (uri) => {
    const db = getDb();
    try {
      const tables = await db.all(
        "SELECT sql FROM sqlite_master WHERE type='table'"
      );
      return {
        contents: [{
          uri: uri.href,
          text: tables.map((t: {sql: string}) => t.sql).join("\n")
        }]
      };
    } finally {
      await db.close();
    }
  }
);

server.tool(
  "query",
  { sql: z.string() },
  async ({ sql }) => {
    const db = getDb();
    try {
      const results = await db.all(sql);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (err: unknown) {
      const error = err as Error;
      return {
        content: [{
          type: "text",
          text: `Error: ${error.message}`
        }],
        isError: true
      };
    } finally {
      await db.close();
    }
  }
);

高度な使い方

低レベルサーバー

より細かく制御するには、低レベルの Server クラスを直接使用できます。

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  {
    name: "example-server",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {}
    }
  }
);

server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [{
      name: "example-prompt",
      description: "An example prompt template",
      arguments: [{
        name: "arg1",
        description: "Example argument",
        required: true
      }]
    }]
  };
});

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name !== "example-prompt") {
    throw new Error("Unknown prompt");
  }
  return {
    description: "Example prompt",
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: "Example prompt text"
      }
    }]
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

MCP クライアントの作成

SDK には、高レベルのクライアントインターフェースが用意されています。

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["server.js"]
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

await client.connect(transport);

// List prompts
const prompts = await client.listPrompts();

// Get a prompt
const prompt = await client.getPrompt("example-prompt", {
  arg1: "value"
});

// List resources
const resources = await client.listResources();

// Read a resource
const resource = await client.readResource("file:///example.txt");

// Call a tool
const result = await client.callTool({
  name: "example-tool",
  arguments: {
    arg1: "value"
  }
});

ドキュメント

• Model Context Protocol のドキュメント
• MCP 仕様
• サーバーの例

貢献

GitHub（https://github.com/modelcontextprotocol/typescript-sdk）での Issue とプルリクエストを歓迎します。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。