mcp-server-plus

はじめに

mcp-server-plus は、MCP サーバーツールキットです。繰り返しのボイラープレートを書かずに Model Context Protocol サーバーを構築するための小さな TypeScript フレームワークです。

パッケージ名に関する注記: mcp-server-toolkit は npm で既に使用されているため、このパッケージは mcp-server-plus として公開されています。

Related MCP server: MCP Framework

このパッケージが存在する理由

MCP サーバーを始める開発者は、ツール登録、プロンプト、リソース、認証、ロギング、テストを何度も実装し直しています。Express や Hono のような人気ライブラリは、ハッピーパスを明確にすることで成功しています。mcp-server-plus は、公式の @modelcontextprotocol/sdk の上で同じ DX を目指しています。

インストール

npm install mcp-server-plus zod

Node.js 18+ が必要です。

機能

• ツール登録

• プロンプトレジストリ

• リソース

• 認証 / 認可

• ロギング

• メトリクス

• ストリーミング（MCP stdio トランスポート経由）

• ミドルウェア

• CLI スキャフォルダー

• テストヘルパー

クイックスタート

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

API リファレンス

createServer(options) / createMcpServer(options)

McpKitServer を作成します。

server.tool(name, definition)

ツールを登録します（MCP SDK にも接続されます）。

server.prompt(name, definition)

プロンプトテンプレートを登録します。

server.resource(uri, definition)

リソースを登録します。

server.use(middleware)

ツール呼び出しの周りにミドルウェアを追加します。

server.start()

MCP stdio トランスポートを接続します（ストリーミングは SDK が処理します）。

server.invokeTool(name, args, meta?)

テストやスクリプト用のプロセス内呼び出し。

テストヘルパー

import { callTool, expectText } from "mcp-server-plus/testing";

例

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

高度な例

認証 + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  // MCP_API_KEY is the expected secret only. Callers must still send meta.apiKey.
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

ミドルウェア + メトリクス

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

フレームワーク統合

stdio サーバーをサポートする任意の MCP ホストで動作します。ホストを node dist/index.js（または npm start）プロセスに向けてください。

MCP ホスト設定の例:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

TypeScript の使用

ファーストクラスの TypeScript サポート。ハンドラーを明示的に型指定すると、ツール引数は Zod の inputSchema から推論されます。最良の結果を得るには strict を有効にしてください。

エラーハンドリング

型付きエラー: McpKitError、AuthError、ForbiddenError。
ツールの失敗は { isError: true, content: [...] } を返すため、ホストは安全に表示できます。

パフォーマンス

• 公式 SDK の薄いラッパー（追加のネットワークホップなし）

• ミドルウェアはツール呼び出し時のみ

• メトリクスはシンプルなカウンター（オーバーヘッド低）

ベストプラクティス

• ツールは小さく、副作用を意識する

• Zod スキーマで入力を検証する

• ローカル/開発では optional 認証、共有ホストでは required を使用する

• 単体テストでは invokeTool を優先し、統合テストでは stdio を使用する

FAQ

これは公式 SDK ですか?
いいえ — @modelcontextprotocol/sdk の上に、より良い DX を提供するものです。

ストリーミングはサポートしていますか?
はい、server.start() が使用する MCP stdio トランスポート経由でサポートしています。

CJS または ESM?
デュアル公開しています。ESM ファーストです。

移行ガイド

生の SDK McpServer から

registerTool のボイラープレートを server.tool(name, definition) に置き換え、Zod スキーマはそのまま使用します。StdioServerTransport を手動で配線する代わりに server.start() を呼び出します。

SemVer

破壊的変更はメジャーバージョンで行われ、CHANGELOG.md に記載されます。

トラブルシューティング

貢献

CONTRIBUTING.md を参照してください。

ライセンス

MIT