MCP Framework

MCP フレームワーク

MCP-Framework は、TypeScript で Model Context Protocol（MCP）サーバーをスマートに構築するためのフレームワークです。

MCP-Framework にはすぐに使えるアーキテクチャが備わっており、ツール、リソース、プロンプトをディレクトリベースで自動検出します。強力な MCP 抽象化を使って、ツール、リソース、プロンプトをスマートに定義できます。CLI を使えば、独自の MCP サーバーを簡単に使い始められます。

特長

• 🛠️ ツール、リソース、プロンプトの自動検出と読み込み
• 複数のトランスポートをサポート（stdio、SSE、HTTP Stream）
• 型安全性を完全に備えた TypeScript ファーストの開発
• 公式 MCP SDK を基盤として構築
• ツール、プロンプト、リソース向けの使いやすい基底クラス
• SSE エンドポイントの認証をすぐに利用可能（OAuth 2.1、JWT、API Key）

MCP Framework で構築されたプロジェクト

以下のプロジェクトおよびサービスは、MCP Framework を使用して構築されています。

• tip.md

AI アシスタントがチャットインターフェースからコンテンツクリエイターへ暗号通貨のチップを直接送れるようにする、暗号通貨の投げ銭サービスです。この MCP サービスでは、次のことができます。

• ユーザーのウォレットの種類を確認する
• ユーザー／エージェントが完了できるよう、暗号通貨のチップを準備する Cursor、Sage、Claude Desktop など、さまざまなクライアント向けのセットアップ手順は、MCP サーバーのドキュメントで確認できます。

私たちの活動を支援する

ドキュメント全文はこちら

mcp-framework でリポジトリを作成する

CLI を使用する（推奨）

# Install the framework globally
npm install -g mcp-framework

# Create a new MCP server project
mcp create my-mcp-server

# Navigate to your project
cd my-mcp-server

# Your server is ready to use!

CLI の使い方

このフレームワークには、MCP サーバープロジェクトを管理するための強力な CLI が用意されています。

プロジェクトの作成

# Create a new project
mcp create <your project name here>

# Create a new project with the new EXPERIMENTAL HTTP transport
Heads up: This will set cors allowed origin to "*", modify it in the index if you wish
mcp create <your project name here> --http --port 1337 --cors

オプション：

--http: デフォルトの stdio の代わりに HTTP トランスポートを使用します

--port : HTTP ポートを指定します（デフォルト：8080）

--cors: ワイルドカード（*）アクセスで CORS を有効にします

ツールの追加

# Add a new tool
mcp add tool price-fetcher

ビルドと検証

このフレームワークには、ツールが適切に文書化され、機能することを確認するための包括的な検証機能が備わっています。

# Build with automatic validation (recommended)
npm run build

# Build with custom validation settings
MCP_SKIP_TOOL_VALIDATION=false npm run build  # Force validation (default)
MCP_SKIP_TOOL_VALIDATION=true npm run build   # Skip validation (not recommended)

ツールの検証

# Validate all tools have proper descriptions (for Zod schemas)
mcp validate

このコマンドは、Zod スキーマを使用するすべてのツールについて、各フィールドに説明があることを確認します。検証はビルド時に自動的に実行されますが、単独で実行することもできます。

• ✅ ビルド時：npm run build でツールが自動的に検証されます
• ✅ 単独実行：手動で検証するには mcp validate を実行します
• ✅ 開発時：defineSchema() ヘルパーを使うと、すぐにフィードバックを得られます
• ✅ 実行時：サーバーは起動時にツールを検証します

検証エラーの例：

❌ Tool validation failed:
  ❌ PriceFetcher.js: Missing descriptions for fields in price_fetcher: symbol, currency. 
All fields must have descriptions when using Zod object schemas. 
Use .describe() on each field, e.g., z.string().describe("Field description")

検証を CI/CD に統合する：

{
  "scripts": {
    "build": "tsc && mcp-build",
    "test": "jest && mcp validate",
    "prepack": "npm run build && mcp validate"
  }
}

プロンプトの追加

# Add a new prompt
mcp add prompt price-analysis

リソースの追加

# Add a new resource
mcp add resource market-data

開発ワークフロー

1. プロジェクトを作成する：

   mcp create my-mcp-server
   cd my-mcp-server
   

2. ツールを追加する：

   mcp add tool data-fetcher
   mcp add tool data-processor
   mcp add tool report-generator
   

3. 自動検証を使ってツールのスキーマを定義する：

   // tools/DataFetcher.ts
   import { MCPTool, MCPInput as AddToolInput } from "mcp-framework";
   

import { z } from "zod";

const AddToolSchema = z.object({ a: z.number().describe("First number to add"), b: z.number().describe("Second number to add"), });

class AddTool extends MCPTool { name = "add"; description = "Add tool description"; schema = AddToolSchema;

async execute(input: AddToolInput) { const result = input.a + input.b; return Result: ${result}; } } export default AddTool;

4. **自動検証を使ってビルドする：**
```bash
npm run build  # Automatically validates schemas and compiles

5. 任意：検証を単独で実行する：

   mcp validate  # Check all tools independently
   

6. サーバーをテストする：

   node dist/index.js  # Server validates tools on startup
   

7. MCP クライアントに追加する（下記の Claude Desktop の例を参照）

プロのヒント：

• 開発時には defineSchema() を使うと、すぐにフィードバックを得られます
• ビルドプロセスで説明の不足が自動的に検出されます
• サーバーは接続を受け付ける前に、起動時にすべてのツールを検証します
• TypeScript の MCPInput<this> による自動補完を使うと、開発者体験が向上します

Claude Desktop での使用

ローカル開発

次の設定を Claude Desktop の設定ファイルに追加します。

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"${projectName}": {
      "command": "node",
      "args":["/absolute/path/to/${projectName}/dist/index.js"]
}
}
}

公開後

次の設定を Claude Desktop の設定ファイルに追加します。

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"${projectName}": {
      "command": "npx",
      "args": ["${projectName}"]
}
}
}

ビルドとテスト

1. ツールを変更します
2. npm run build を実行してコンパイルします
3. サーバーは起動時にツールを自動的に読み込みます

環境変数

フレームワークでは、設定に次の環境変数を使用できます。

変数	説明	デフォルト
MCP_ENABLE_FILE_LOGGING	ファイルへのログ出力を有効にします（true/false）	false
MCP_LOG_DIRECTORY	ログファイルの保存先ディレクトリ	logs
MCP_DEBUG_CONSOLE	デバッグレベルのメッセージをコンソールに表示します（true/false）	false

使用例：

# Enable file logging
MCP_ENABLE_FILE_LOGGING=true node dist/index.js

# Specify a custom log directory
MCP_ENABLE_FILE_LOGGING=true MCP_LOG_DIRECTORY=my-logs node dist/index.js

# Enable debug messages in console
MCP_DEBUG_CONSOLE=true node dist/index.js

クイックスタート

ツールの定義

MCP Framework では、Zod スキーマを使ってツールの入力を定義します。これにより、型安全性、検証、自動ドキュメント生成が実現します。

import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

const AddToolSchema = z.object({
  a: z.number().describe("First number to add"),
  b: z.number().describe("Second number to add"),
});

class AddTool extends MCPTool {
  name = "add";
  description = "Add tool description";
  schema = AddToolSchema;

  async execute(input: MCPInput<this>) {
    const result = input.a + input.b;
    return `Result: ${result}`;
  }
}

export default AddTool;

主なメリット：

• ✅ 信頼できる唯一の情報源 - 型と検証を1か所で定義できます
• ✅ 型の自動推論 - スキーマから TypeScript の型が推論されます
• ✅ 高度な検証 - Zod の強力な検証機能を活用できます
• ✅ 説明の必須化 - フレームワークによってドキュメントの記述が必須になります
• ✅ IDE サポートの向上 - 完全な自動補完と型チェックを利用できます
• ✅ コードの簡潔化 - 型定義の重複がなくなります

Zod スキーマの高度な機能

フレームワークは、すべての Zod 機能をサポートしています。

import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

const AdvancedSchema = z.object({
  // String constraints and formats
  email: z.string().email().describe("User email address"),
  name: z.string().min(2).max(50).describe("User name"),
  website: z.string().url().optional().describe("Optional website URL"),
  
  // Number constraints
  age: z.number().int().positive().max(120).describe("User age"),
  rating: z.number().min(1).max(5).describe("Rating from 1 to 5"),
  
  // Arrays and objects
  tags: z.array(z.string()).describe("List of tags"),
  metadata: z.object({
    priority: z.enum(['low', 'medium', 'high']).describe("Task priority"),
    dueDate: z.string().optional().describe("Due date in ISO format")
  }).describe("Additional metadata"),
  
  // Default values
  status: z.string().default('pending').describe("Current status"),
  
  // Unions and enums
  category: z.union([
    z.literal('personal'),
    z.literal('work'),
    z.literal('other')
  ]).describe("Category type")
});

class AdvancedTool extends MCPTool {
  name = "advanced_tool";
  description = "Tool demonstrating advanced Zod features";
  schema = AdvancedSchema;

  async execute(input: MCPInput<this>) {
    // TypeScript automatically knows all the types!
    const { email, name, website, age, rating, tags, metadata, status, category } = input;
    
    console.log(input.name.toUpperCase()); // ✅ TypeScript knows this is valid
    console.log(input.age.toFixed(2));     // ✅ Number methods available
    console.log(input.tags.length);       // ✅ Array methods available
    console.log(input.website?.includes("https")); // ✅ Optional handling
    
    return `Processed user: ${name}`;
  }
}

型の自動推論

MCPInput<this> 型は、スキーマから正しい入力型を自動的に推論するため、手動で型を定義する必要がありません。

class MyTool extends MCPTool {
  schema = z.object({
    name: z.string().describe("User name"),
    age: z.number().optional().describe("User age"),
    tags: z.array(z.string()).describe("User tags")
  });

  async execute(input: MCPInput<this>) {
    // TypeScript automatically knows:
    // input.name is string
    // input.age is number | undefined  
    // input.tags is string[]
    
    console.log(input.name.toUpperCase()); // ✅ TypeScript knows this is valid
    console.log(input.age?.toFixed(2));    // ✅ Handles optional correctly
    console.log(input.tags.length);       // ✅ Array methods available
  }
}

インターフェースやジェネリック型パラメーターを重複して定義する必要はありません。

スキーマの検証と説明

すべてのスキーマフィールドに説明を記述する必要があります。これにより、ツールのドキュメントが充実し、MCP クライアントでのユーザーエクスペリエンスが向上します。

フレームワークでは、複数の段階で説明を検証します。

1. ビルド時の検証（推奨）

npm run build  # Automatically validates during compilation

2. 開発時の検証

defineSchema ヘルパーを使用すると、すぐにフィードバックを得られます。

import { defineSchema } from "mcp-framework";

// This will throw an error immediately if descriptions are missing
const MySchema = defineSchema({
  name: z.string(),  // ❌ Error: Missing description
  age: z.number().describe("User age")  // ✅ Good
});

3. 単独での検証

mcp validate  # Check all tools for proper descriptions

4. 実行時の検証

サーバーの起動時に、ツールが自動的に検証されます。

検証をスキップするには（推奨されません）：

# Skip during build
MCP_SKIP_TOOL_VALIDATION=true npm run build

# Skip during development
NODE_ENV=production npm run dev

サーバーのセットアップ

import { MCPServer } from "mcp-framework";

const server = new MCPServer();

// OR (mutually exclusive!) with SSE transport
const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      port: 8080            // Optional (default: 8080)
    }
  }
});

// Start the server
await server.start();

トランスポートの設定

stdio トランスポート（デフォルト）

トランスポート設定が指定されていない場合、デフォルトで stdio トランスポートが使用されます。

const server = new MCPServer();
// or explicitly:
const server = new MCPServer({
  transport: { type: "stdio" }
});

SSE トランスポート

Server-Sent Events（SSE）トランスポートを使用するには：

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      port: 8080,            // Optional (default: 8080)
      endpoint: "/sse",      // Optional (default: "/sse")
      messageEndpoint: "/messages", // Optional (default: "/messages")
      cors: {
        allowOrigin: "*",    // Optional (default: "*")
        allowMethods: "GET, POST, OPTIONS", // Optional (default: "GET, POST, OPTIONS")
        allowHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
        exposeHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
        maxAge: "86400"      // Optional (default: "86400")
      }
    }
  }
});

HTTP Stream トランスポート

HTTP Stream トランスポートを使用するには：

const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      port: 8080,                // Optional (default: 8080)
      endpoint: "/mcp",          // Optional (default: "/mcp") 
      responseMode: "batch",     // Optional (default: "batch"), can be "batch" or "stream"
      batchTimeout: 30000,       // Optional (default: 30000ms) - timeout for batch responses
      maxMessageSize: "4mb",     // Optional (default: "4mb") - maximum message size
      
      // Session configuration
      session: {
        enabled: true,           // Optional (default: true)
        headerName: "Mcp-Session-Id", // Optional (default: "Mcp-Session-Id")
        allowClientTermination: true, // Optional (default: true)
      },
      
      // Stream resumability (for missed messages)
      resumability: {
        enabled: false,          // Optional (default: false)
        historyDuration: 300000, // Optional (default: 300000ms = 5min) - how long to keep message history
      },
      
      // CORS configuration
      cors: {
        allowOrigin: "*"         // Other CORS options use defaults
      }
    }
  }
});

レスポンスモード

HTTP Stream トランスポートでは、次の2つのレスポンスモードをサポートしています。

1. バッチモード（デフォルト）：レスポンスをまとめて、1つの JSON-RPC レスポンスとして送信します。一般的なリクエストとレスポンスのパターンに適しており、ほとんどのユースケースで効率的です。

2. ストリームモード：各リクエストで開かれる永続的な SSE 接続を通じて、すべてのレスポンスを送信します。長時間実行される操作や、1つのリクエストに対してサーバーが複数のメッセージを送信する必要がある場合に最適です。

用途に応じて、レスポンスモードを設定できます。

// For batch mode (default):
const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      responseMode: "batch"
    }
  }
});

// For stream mode:
const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      responseMode: "stream"
    }
  }
});

HTTP Stream トランスポートの機能

• セッション管理：セッションの追跡と管理を自動で行います
• ストリームの再開：接続が切断された後にストリームを再開するためのオプションのサポート
• バッチ処理：JSON-RPC のバッチリクエスト／レスポンスをサポートします
• 包括的なエラー処理：JSON-RPC エラーコードを含む詳細なエラーレスポンス

認証

MCP Framework では、SSE エンドポイント向けのオプション認証を利用できます。JWT、API キー、OAuth 2.1 認証のほか、独自のカスタム認証プロバイダーを実装することもできます。

JWT 認証

import { MCPServer, JWTAuthProvider } from "mcp-framework";
import { Algorithm } from "jsonwebtoken";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new JWTAuthProvider({
          secret: process.env.JWT_SECRET,
          algorithms: ["HS256" as Algorithm], // Optional (default: ["HS256"])
          headerName: "Authorization"         // Optional (default: "Authorization")
        }),
        endpoints: {
          sse: true,      // Protect SSE endpoint (default: false)
          messages: true  // Protect message endpoint (default: true)
        }
      }
    }
  }
});

クライアントは、Authorization ヘッダーに有効な JWT トークンを含める必要があります。

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API キー認証

import { MCPServer, APIKeyAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new APIKeyAuthProvider({
          keys: [process.env.API_KEY],
          headerName: "X-API-Key" // Optional (default: "X-API-Key")
        })
      }
    }
  }
});

クライアントは、X-API-Key ヘッダーに有効な API キーを含める必要があります。

X-API-Key: your-api-key

OAuth 2.1 認証

MCP Framework は、Protected Resource Metadata（RFC 9728）や JWKS による適切なトークン検証を含め、MCP 仕様（2025-06-18）に準拠した OAuth 2.1 認証をサポートしています。

OAuth 認証は SSE と HTTP Stream の両方のトランスポートで利用でき、2 つの検証方式をサポートしています。

JWT 検証（パフォーマンスを重視する場合に推奨）

JWT 検証では、認可サーバーの JWKS エンドポイントから公開鍵を取得し、トークンをローカルで検証します。リクエストごとに認証サーバーとの往復が不要なため、最も高速な方式です。

import { MCPServer, OAuthAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      port: 8080,
      auth: {
        provider: new OAuthAuthProvider({
          authorizationServers: [
            process.env.OAUTH_AUTHORIZATION_SERVER
          ],
          resource: process.env.OAUTH_RESOURCE,
          validation: {
            type: 'jwt',
            jwksUri: process.env.OAUTH_JWKS_URI,
            audience: process.env.OAUTH_AUDIENCE,
            issuer: process.env.OAUTH_ISSUER,
            algorithms: ['RS256', 'ES256'] // Optional (default: ['RS256', 'ES256'])
          }
        }),
        endpoints: {
          initialize: true,  // Protect session initialization
          messages: true     // Protect MCP messages
        }
      }
    }
  }
});

環境変数：

OAUTH_AUTHORIZATION_SERVER=https://auth.example.com
OAUTH_RESOURCE=https://mcp.example.com
OAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://mcp.example.com
OAUTH_ISSUER=https://auth.example.com

トークンイントロスペクション（集中管理を重視する場合に推奨）

トークンイントロスペクションでは、認可サーバーのイントロスペクションエンドポイントを呼び出してトークンを検証します。これにより一元管理が可能になり、トークンの失効をリアルタイムで反映する必要がある場合に便利です。

import { MCPServer, OAuthAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new OAuthAuthProvider({
          authorizationServers: [
            process.env.OAUTH_AUTHORIZATION_SERVER
          ],
          resource: process.env.OAUTH_RESOURCE,
          validation: {
            type: 'introspection',
            audience: process.env.OAUTH_AUDIENCE,
            issuer: process.env.OAUTH_ISSUER,
            introspection: {
              endpoint: process.env.OAUTH_INTROSPECTION_ENDPOINT,
              clientId: process.env.OAUTH_CLIENT_ID,
              clientSecret: process.env.OAUTH_CLIENT_SECRET
            }
          }
        })
      }
    }
  }
});

環境変数：

OAUTH_AUTHORIZATION_SERVER=https://auth.example.com
OAUTH_RESOURCE=https://mcp.example.com
OAUTH_AUDIENCE=https://mcp.example.com
OAUTH_ISSUER=https://auth.example.com
OAUTH_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OAUTH_CLIENT_ID=mcp-server
OAUTH_CLIENT_SECRET=your-client-secret

OAuth の機能

• RFC 9728 準拠：/.well-known/oauth-protected-resource に Protected Resource Metadata エンドポイントを自動で用意します
• RFC 6750 WWW-Authenticate ヘッダー：チャレンジヘッダーを含む適切な OAuth エラーレスポンスを返します
• JWKS キーのキャッシュ：公開鍵を 15 分間キャッシュします（設定可能）
• トークンイントロスペクションのキャッシュ：イントロスペクション結果を 5 分間キャッシュします（設定可能）
• セキュリティ：クエリ文字列内のトークンは自動的に拒否されます
• クレームの抽出：AuthResult を介して、ツールハンドラー内でアクセストークンのクレームを利用できます

主な OAuth プロバイダー

この OAuth プロバイダーは、RFC に準拠するあらゆる OAuth 2.1 認可サーバーで利用できます。

• Auth0：Auth0 テナントの JWKS URI と発行者を使用します
• Okta：Okta 認可サーバーの設定を使用します
• AWS Cognito：Cognito ユーザープールの JWKS エンドポイントを使用します
• Azure AD / Entra ID：Microsoft Entra ID のエンドポイントを使用します
• カスタム：OAuth 2.1 に準拠するあらゆる認可サーバー

各プロバイダーの詳細な設定手順については、OAuth 設定ガイドを参照してください。

クライアントの使用方法

クライアントは Authorization ヘッダーに有効な OAuth アクセストークンを含める必要があります。

# Make a request with OAuth token
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Discover OAuth configuration
curl http://localhost:8080/.well-known/oauth-protected-resource

セキュリティのベストプラクティス

• 本番環境では必ず HTTPS を使用してください - OAuth トークンを暗号化されていない接続で送信してはいけません
• audience クレームを検証してください - 異なるサービス間でトークンが再利用されるのを防ぎます
• 有効期間の短いトークンを使用してください - トークンが侵害された場合のリスクを軽減します
• トークンイントロスペクションのキャッシュを有効にしてください - セキュリティを維持しながら、認可サーバーの負荷を軽減します
• トークンエラーを監視してください - セキュリティ分析に役立つよう、認証の失敗を記録します

カスタム認証

AuthProvider インターフェースを実装することで、独自の認証プロバイダーを実装できます。

import { AuthProvider, AuthResult } from "mcp-framework";
import { IncomingMessage } from "node:http";

class CustomAuthProvider implements AuthProvider {
  async authenticate(req: IncomingMessage): Promise<boolean | AuthResult> {
    // Implement your custom authentication logic
    return true;
  }

  getAuthError() {
    return {
      status: 401,
      message: "Authentication failed"
    };
  }
}

ドキュメント MCP サーバー（@mcpframework/docs）

任意の Fumadocs サイト、または llms.txt があるサイトから MCP ドキュメントサーバーを起動できます。AI エージェントは、ドキュメントを検索、閲覧、取得するツールを利用できます。

クイックスタート（CLI）

# Scaffold a new docs MCP server project
npx create-docs-mcp my-api-docs
cd my-api-docs

# Configure your docs site URL
cp .env.example .env
# Edit .env → set DOCS_BASE_URL=https://docs.myapi.com

# Build and run
npm run build
npm start

クイックスタート（プログラムからの利用）

import { DocsServer, FumadocsRemoteSource } from "@mcpframework/docs";

const source = new FumadocsRemoteSource({
  baseUrl: "https://docs.myapi.com",
});

const server = new DocsServer({
  source,
  name: "my-api-docs",
  version: "1.0.0",
});

server.start();

ソースアダプター

アダプター	最適な用途	検索
FumadocsRemoteSource	Fumadocs サイト	Orama によるネイティブ検索とフォールバック
LlmsTxtSource	llms.txt がある任意のサイト	ローカルでのテキスト照合
カスタム DocSource	任意のドキュメントバックエンド	独自の実装

組み込み MCP ツール

ツール	説明
search_docs	キーワードまたはフレーズでドキュメントを検索します
get_page	ページの Markdown 全文を取得します
list_sections	ドキュメントのツリー構造を閲覧します

MCP クライアントへの追加

# Claude Code
claude mcp add my-api-docs -- node /path/to/my-api-docs/dist/index.js

# Or with environment variable
claude mcp add my-api-docs -e DOCS_BASE_URL=https://docs.myapi.com -- node /path/to/my-api-docs/dist/index.js

Claude Desktop / Cursor の設定とドキュメント全文については、@mcpframework/docs READMEを参照してください。

ライセンス

MIT