MCP Server (Model Context Protocol)

MCP サーバー（Model Context Protocol）

Model Context Protocol（MCP）を実装するための、汎用的でモジュール式のサーバーです。このサーバーは、標準化された API を通じてさまざまなモデルを制御し、連携するためのフレームワークを提供します。

ホスティングされたデプロイ

Fr​​onteir AI でホスティングされたデプロイを利用できます。

特徴

• 拡張が容易なモジュール式アーキテクチャ
• 動的なモジュールの読み込み
• 中核となるモデル管理機能
• モデルコンテキスト用の標準化された API
• シンプルな設定システム
• ロギングユーティリティ
• 関心事を適切に分離した、強化されたモジュール構造
• 依存関係管理に対応した、モジュール用の Package.json サポート
• Mocha と Chai による包括的なテスト基盤
• 強力なモジュール検索機能
• API レスポンスでのモジュールメタデータ表示
• 実際の AI モデルプロバイダー（OpenAI、Stability AI、Anthropic、Hugging Face）との統合
• テキスト生成、画像生成、音声テキスト変換モデルのサポート
• 対応モデルでのストリーミング推論のサポート

はじめに

前提条件

• Node.js 18.x 以降
• pnpm 10.x 以降

このプロジェクトでは ES Modules（ESM）のみを使用します。すべてのインポートで require() ではなく import 構文を使用します。

インストール

# Clone the repository
git clone https://github.com/yourusername/mcp-server.git
cd mcp-server

# Install dependencies
pnpm install

サーバーの起動

# Install dependencies
pnpm install

# Start the server
pnpm start

# Start the server in development mode (with auto-reload)
pnpm dev

サーバーはデフォルトで http://localhost:3000 で起動します。

設定

サンプル環境ファイルをコピーし、API キーを設定します。

# Copy the sample environment file
cp sample.env .env

# Edit the file with your favorite editor
nano .env

最低限、使用するモデルプロバイダーの API キーを追加する必要があります。

# OpenAI API (for GPT-4 and Whisper)
OPENAI_API_KEY=your_openai_api_key_here

# Stability AI API (for Stable Diffusion)
STABILITY_API_KEY=your_stability_api_key_here

# Anthropic API (for Claude models)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

API キーは以下から取得できます。

• OpenAI：https://platform.openai.com/api-keys
• Stability AI：https://platform.stability.ai/account/keys
• Anthropic：https://console.anthropic.com/settings/keys

セキュリティ

サーバーにはグローバルな認証レイヤーがないため、ポートに到達できるものはすべて、あらゆるモジュールのルートを呼び出せます。ファイルシステムにアクセスしたり、外部へのリクエストを発行したりするモジュールには、以下の制約が適用されます。

モジュールトークン。 副作用のあるルートは、Authorization: Bearer <token> または X-API-Key: <token> でトークンを受け付けます。変数が設定されていない場合、ルートは認証なしで利用でき、起動時に警告がログに記録されます。

変数	保護対象
SCANNER_API_TOKEN	/scanner/scan、/scanner/reports/:id/export、/tools/scanner
README_BADGES_API_TOKEN	/readme-badges/update、/readme-badges/detect、/tools/readme-badges

パスの制限。 readme-badges は readmePath と rootDir を README_BADGES_ROOT（デフォルト：作業ディレクトリ）を基準に解決し、その範囲外に出るパス、Markdown 以外のファイルを対象とするパス、またはシンボリックリンク経由で範囲外に到達するパスを拒否します。scanner も同様に、エクスポート先をレポートディレクトリ内に制限します。

外部リクエストの許可リスト。 呼び出し元が指定した URL を取得するモジュールは、ループバック、リンクローカル（クラウドメタデータ）、RFC1918、CGNAT、その他のパブリックでないアドレスを拒否し、ホスト名を解決して返されたすべてのアドレスを確認し、リダイレクトの各段階で再検証します。モジュールが既知のサービスと通信する場合は、ホストも許可リストに登録されます。

変数	許可リストに追加される対象
CONVERT2DOC_ALLOWED_HOSTS	convert2doc の baseUrl（デフォルト：convert2doc.com）
CRAIGSLIST_ALLOWED_HOSTS	/craigslist/details（デフォルト：*.craigslist.org）

クロスオリジンリクエスト。 CSRF_PROTECTION_ENABLED（デフォルト true）は、別のオリジンを示す Origin ヘッダーを含む状態変更リクエストを拒否します。これにより、悪意のあるウェブページが localhost にバインドされたサーバーをブラウザー経由で操作することを防ぎます。Origin を送信しないクライアント（curl、MCP クライアント、サーバー間の呼び出し）には影響しません。信頼するブラウザーのオリジンは CORS_ORIGINS に指定してください。

localhost の範囲を超えてサーバーを公開する場合は、認証を行うリバースプロキシの背後で実行してください。

サーバーのテスト

このリポジトリには、Mocha と Chai を使用した包括的なテストが含まれています。

# Run all tests
pnpm test

# Run only module tests
pnpm test:modules

# Run all tests (both core and modules)
pnpm test:all

テスト基盤には以下が含まれます。

1. モジュールの読み込み、ルーティング、その他のコア機能を対象とするコアサーバーテスト
2. 各モジュールの機能を対象とするモジュール固有のテスト
3. テストでの ES モジュールのサポート
4. Sinon によるモックおよびスタブ用ユーティリティ

テストは次のように体系的に整理されています。

• コアテストは /test/core/
• モジュールテストは各モジュールの test/ ディレクトリ

この包括的なテストにより、コード品質を確保し、変更時にリグレッションを検出しやすくなります。

コミット前フック

このリポジトリには、Husky と lint-staged を使用したコミット前フックが含まれています。

# The hooks are automatically installed when you run
pnpm install

コミット前フックでは、以下を実行します。

1. JavaScript ファイルに対して ESLint を実行
2. ステージングされたすべてのファイルに対して Prettier を実行

これにより、リポジトリにコミットされるすべてのコードがコーディング規約に従い、コード品質が維持されます。テストスイートは、カバレッジと信頼性を高めるため継続的に改善されており、より安定した段階でコミット前フックに組み込まれる予定です。

Docker のサポート

このリポジトリには、コンテナー化とデプロイを簡単に行うための Docker サポートが含まれています。

# Build and run with Docker
docker build -t mcp-server .
docker run -p 3000:3000 mcp-server

# Or use Docker Compose
docker-compose up

Docker の設定は以下のとおりです。

• ベースイメージとして Node.js 20 Alpine を使用
• ポート 3000 を公開
• モジュールを簡単に管理できるよう、modules ディレクトリをボリュームとしてマウント
• ヘルスチェックを含む

標準 MCP メソッド

MCP サーバーは、すべての MCP サーバーが提供すべき標準化されたメソッドを実装しています。

サーバー情報

• GET / - 基本的なサーバー情報
• GET /status - 詳細なサーバー状態
• GET /health - ヘルスチェックエンドポイント
• GET /metrics - サーバーメトリクス

モデル管理

• GET /models - 利用可能なモデルを一覧表示します
• GET /model/:modelId - モデル情報を取得します
• POST /model/:modelId/activate - 特定のモデルを有効化します
• POST /model/deactivate - 現在のモデルを無効化します
• GET /model/active - 有効なモデルに関する情報を取得します

推論

• POST /model/infer - 有効なモデルで推論を実行します
• POST /model/:modelId/infer - 特定のモデルで推論を実行します

対応モデル

MCP サーバーは、次の種類のモデルに対応しています。

モデルの種類	プロバイダー	機能	ID の例
GPT モデル	OpenAI	テキスト生成	gpt-4, gpt-3.5-turbo
Whisper	OpenAI	音声からテキストへの変換	whisper, whisper-1
Stable Diffusion	Stability AI	画像生成	stable-diffusion-xl-1024-v1-0
Claude モデル	Anthropic	テキスト生成	claude-3-opus, claude-3-sonnet
カスタムモデル	Hugging Face	さまざまな機能	(任意の Hugging Face モデル ID)

推論の例

GPT-4 によるテキスト生成：

# Activate the model
curl -X POST http://localhost:3000/model/gpt-4/activate \
  -H "Content-Type: application/json" \
  -d '{"config": {"temperature": 0.7}}'

# Perform inference
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain quantum computing in simple terms",
    "temperature": 0.5,
    "max_tokens": 200
  }'

Stable Diffusion による画像生成：

# Activate the model
curl -X POST http://localhost:3000/model/stable-diffusion/activate \
  -H "Content-Type: application/json" \
  -d '{}'

# Generate an image
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "height": 1024,
    "width": 1024,
    "steps": 30
  }'

ストリーミングによるテキスト生成：

# Enable streaming
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a short story about a robot",
    "stream": true
  }'

モジュール管理

• GET /modules - インストール済みモジュールを一覧表示します
• GET /modules/:moduleId - モジュール情報を取得します
• GET /modules/search/:query - モジュールの package.json またはメタデータの任意のフィールドを対象に検索します

ツールとリソース

• GET /tools - 利用可能なツールを一覧表示します
• GET /resources - 利用可能なリソースを一覧表示します

これらのメソッドの詳細については、MCP 標準メソッドを参照してください。

設定

設定は環境変数から読み込まれ、src/core/config.js に保存されます。サーバーを設定する最も簡単な方法は、プロジェクトのルートにある .env ファイルを編集することです。

環境変数

主な環境変数は次のとおりです。

変数	説明	デフォルト
PORT	サーバーのポート	3000
HOST	サーバーのホスト	localhost
NODE_ENV	環境（開発／本番）	development
OPENAI_API_KEY	OpenAI API キー	（OpenAI モデルで必要）
STABILITY_API_KEY	Stability AI API キー	（Stable Diffusion で必要）
ANTHROPIC_API_KEY	Anthropic API キー	（Claude モデルで必要）
HUGGINGFACE_API_KEY	Hugging Face API キー	（Hugging Face モデルで必要）

設定オプションの完全な一覧については、sample.env を参照してください。

例

このリポジトリには、使い始める際に役立つ例がいくつか含まれています。

• クライアントの例：examples/client.js では、クライアントアプリケーションから MCP サーバーとやり取りする方法を示します。
• カスタムモジュールの例：examples/custom-module/ では、サーバーに計算機ツールを追加するカスタムモジュールの作成方法を示します。

クライアントの例を実行するには：

node examples/client.js

カスタムモジュールの例を使用するには、modules ディレクトリにコピーします。

cp -r examples/custom-module mcp_modules/calculator

モジュールの作成

モジュールは、MCP サーバーを拡張する主な方法です。各モジュールは、サーバーに新しい機能を追加できる自己完結型のパッケージです。

モジュール構成

モジュールは、整理しやすくなるよう改良された構成に従います。

mcp_modules/your-module/
├── assets/          # Static assets (images, CSS, etc.)
├── docs/            # Documentation files
├── examples/        # Example usage
├── src/             # Source code
│   ├── controller.js  # HTTP route handlers
│   ├── service.js     # Business logic
│   └── utils.js       # Utility functions
├── test/            # Test files
│   ├── controller.test.js
│   └── service.test.js
├── index.js         # Main module file with register function
├── package.json     # Module metadata, dependencies, and scripts
└── README.md        # Module documentation

各モジュールには、次の項目を含む package.json ファイルが必要です。

• 名前、バージョン、説明
• 作成者とライセンス情報
• 依存関係と開発用依存関係
• スクリプト（特にテスト用）
• キーワードおよびその他のメタデータ

この構成により、関心事をより適切に分離でき、テストが容易になり、モジュールを見つけやすくなります。

モジュールの実装

メインモジュールファイル（index.js）では、モジュールの読み込み時に呼び出される register 関数をエクスポートする必要があります。

/**
 * Register this module with the Hono app
 * @param {import('hono').Hono} app - The Hono app instance
 */
export async function register(app) {
  // Register routes, middleware, etc.
  app.get('/your-module/endpoint', c => {
    return c.json({ message: 'Your module is working!' });
  });
}

// Optional: Export module metadata
export const metadata = {
  name: 'Your Module',
  version: '1.0.0',
  description: 'Description of your module',
  author: 'Your Name',
};

モジュールの例

• モジュールの作成方法を示すシンプルな例が mcp_modules/example/ にあります。
• 計算機ツールを含む、より複雑な例が examples/custom-module/ にあります。
• システム監視用のヘルスチェックモジュールが mcp_modules/health-check/ にあります。
• 新しいモジュールを作成するためのテンプレートが mcp_modules/template/ にあります。

新しいモジュールの作成

用意されているスクリプトを使って、新しいモジュールを作成できます。

# Create a new module
pnpm create-module

# Or with a module name
pnpm create-module my-module

このスクリプトは次の処理を行います。

1. mcp_modules/ に新しいモジュールディレクトリを作成します
2. テンプレートファイルをコピーします
3. プレースホルダーをモジュール情報に置き換えます
4. モジュールを実装するための次の手順を提示します

モジュール検索

MCP サーバーには、package.json またはメタデータ内のあらゆる情報をもとにモジュールを検索できる、高度な検索機能が含まれています。

検索エンドポイント

• GET /modules/search/:query - いずれかのフィールドに指定したクエリ文字列を含むモジュールを検索します

検索例

# Find modules by name or description
curl http://localhost:3000/modules/search/craigslist

# Find modules by dependency
curl http://localhost:3000/modules/search/jsdom

# Find modules by keyword
curl http://localhost:3000/modules/search/mcp

# Find modules by author
curl http://localhost:3000/modules/search/"MCP Server Team"

# Find modules by license
curl http://localhost:3000/modules/search/ISC

JavaScript の例

// Function to search modules by any field
async function searchModules(query) {
  const response = await fetch(`http://localhost:3000/modules/search/${query}`);
  const data = await response.json();

  console.log(`Found ${data.count} modules matching "${query}":`);
  data.results.forEach(module => {
    console.log(`- ${module.name} (${module.directoryName}): ${module.description}`);
  });

  return data.results;
}

この検索は網羅的で、依存関係、キーワード、その他のメタデータなど、ネストされたオブジェクトを含むあらゆるフィールドから一致するものを見つけます。

モデルプロバイダー

MCP サーバーは、複数の AI モデルプロバイダーと連携します。

OpenAI

OpenAI は、テキスト生成用の GPT モデルと、音声からテキストへの変換用の Whisper を提供しています。

// Text generation example
const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Write a poem about artificial intelligence',
    temperature: 0.7,
    max_tokens: 200,
  }),
});

// Speech-to-text example (requires multipart form data)
const formData = new FormData();
formData.append('file', audioFile);
formData.append('model', 'whisper-1');
formData.append('language', 'en');

const response = await fetch('http://localhost:3000/model/whisper/infer', {
  method: 'POST',
  body: formData,
});

Stability AI

Stability AI は、画像生成用の Stable Diffusion を提供しています。

const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'A photorealistic image of a futuristic city',
    height: 1024,
    width: 1024,
    steps: 30,
    cfg_scale: 7,
  }),
});

// The response includes base64-encoded images
const result = await response.json();
const imageBase64 = result.response[0].base64;

Anthropic

Anthropic は、テキスト生成用の Claude モデルを提供しています。

const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Explain how neural networks work',
    temperature: 0.5,
    max_tokens: 300,
  }),
});

Hugging Face

Hugging Face では、何千ものオープンソースモデルを利用できます。

const response = await fetch('http://localhost:3000/model/custom-model-name/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Input for the model',
    parameters: {
      // Model-specific parameters
    },
  }),
});

ドキュメント

• MCP 標準メソッド：すべての MCP サーバーが実装すべき標準メソッドのドキュメントです。
• MCP インターフェース：MCP プロトコルの TypeScript インターフェース定義です。
• アーキテクチャ：MCP サーバーアーキテクチャの概要です。

ライセンス

ISC