JS MCP Server

JS MCP サーバー

簡単に統合・デプロイできる、WASM SDK を備えた JavaScript MCP サーバーコンポーネントです。

セットアップ

JS MCP サーバーを使い始めるには、次の手順に従ってください。

git clone https://github.com/justin-echternach/js-mcp-server.git
cd js-mcp-server
npm install -g @bytecodealliance/componentize-js @bytecodealliance/jco
npm install

ビルド

プロジェクトをビルドして WebAssembly モジュールを生成するには、次の手順に従ってください。

npm run build

これにより、Vite を使って JavaScript コードがバンドルされ、dist/js-mcp-server.wasm にコンポーネント化されます。

カスタマイズ

ハンドラー（ツールとも呼ばれます）を追加または変更して、サーバーをカスタマイズできます。ハンドラーは server.js ファイルに登録され、handlers ディレクトリに配置されています。新しいハンドラーを追加するには、次の手順に従ってください。

1. handlers ディレクトリに、ハンドラーの実装を記述した新しい JavaScript ファイルを作成します。
2. server.js でハンドラーをインポートします。
3. EchoTool、KgTool、FetchDogTool を追加する方法と同様に、createMcpServer 関数の呼び出しで tools オブジェクトにハンドラーを追加します。

たとえば、MyCustomTool という名前の新しいハンドラーを追加する場合は、次のようにします。

// In server.js
import { MyCustomTool } from './handlers/index.js';

createMcpServer({
  serverInfo: {
    name: "JavaScript MCP Server",
    version: "1.0.0"
  },
  tools: {
    [EchoTool.name]: EchoTool,
    [KgTool.name]: KgTool,
    [MyCustomTool.name]: MyCustomTool
  },
  handlers: {
    // Custom handlers (optional)
  }
});

カスタムハンドラーの作成

ハンドラー（ツール）は、サーバーの機能の中核です。各ハンドラーは次のものをエクスポートする必要があります。

• リクエストを処理して結果を返す async ハンドラー関数。
• 入力の検証とドキュメント作成に使う 名前（文字列）、説明、スキーマ。

最小限の例

FetchDogTool をもとにした最小限のハンドラーの例を示します。

// handlers/fetch_dog_tool.js
export async function handleTool(parameters) {
  try {
    // Perform your logic (e.g., HTTP request)
    return { result: 'success!' };
  } catch (error) {
    return { error: error.message };
  }
}

export function getToolName() {
  return 'fetch_dog';
}

export function getToolDescription() {
  return 'Fetches a random dog image from the Dog API';
}

export function getToolSchema() {
  return { type: 'object', properties: {} };
}

export const FetchDogTool = {
  handler: handleTool,
  name: getToolName(),
  description: getToolDescription(),
  schema: getToolSchema()
};

ハンドラーの登録

1. handlers/index.js でエクスポートします。

   import { FetchDogTool } from './fetch_dog_tool.js';
   export { FetchDogTool };
   // ...add to tools map if needed
   

2. server.js の tools オブジェクトに追加します。

   import { FetchDogTool } from './handlers/fetch_dog_tool.js';
   createMcpServer({
     tools: {
       [FetchDogTool.name]: FetchDogTool,
       // ...other tools
     }
   });
   

ベストプラクティス

• ハンドラーは async にでき、プレーンオブジェクトを返せます。
• エラーは常に適切に処理し、明確なエラーオブジェクトを返してください。
• schema プロパティを使って、想定される入力を記述してください。
• 見つけやすくするため、意味のある name と description フィールドを設定してください。

タイムアウト、再試行、より詳細なエラー処理などの高度な機能が必要な場合は、それに応じてハンドラーのロジックを拡張してください。

---

Postgres および HTTP インターフェースの使用

MCP サーバーは、堅牢で開発者にとって使いやすい抽象化を利用して、HTTP API や Postgres データベースなどの外部サービスとやり取りできます。

Postgres インターフェース（Async）

comapi:postgres/[email protected] インターフェースの query 関数を使って、Postgres データベースにクエリを実行できます。これは、ナレッジグラフやデータに基づくツールに便利です。

例：

import { query } from "comapi:postgres/[email protected]";

export async function handleTool(parameters) {
  const entityFilter = parameters?.entityFilter || "";
  const sqlQuery = `
    SELECT id, name FROM my_table
    WHERE name ILIKE $1
    LIMIT 10
  `;
  const inputValue = `%${entityFilter}%`;
  // PgValue enum/variant: { tag: 'text', val: value }
  const params = [{ tag: 'text', val: inputValue }];
  const result = await query(sqlQuery, params);
  return { rows: result.rows };
}

ベストプラクティス：

• WIT で定義された列挙型／バリアントは、テキスト入力の場合、{ tag: 'text', val: value } としてラップする必要があります。
• 入力は必ず検証してサニタイズしてください。
• 必要に応じて try/catch でエラーを処理してください。

HTTP クライアント関数

SDK は、WASI HTTP の複雑さをラップした、送信 HTTP リクエスト用の開発者にとって使いやすい HTTP クライアント抽象化を提供します。

例：

import { get } from '../sdk/http/index.js';

export async function handleTool(parameters) {
  try {
    // Simple GET request with JSON response
    const response = await get('https://dog.ceo/api/breeds/image/random', { json: true });
    return { image_url: response.message, status: response.status };
  } catch (error) {
    return { error: error.message };
  }
}

利用可能な HTTP メソッド：

• get(url, options)
• post(url, data, options)
• put(url, data, options)
• patch(url, data, options)
• del(url, options)（別名：deleteRequest）
• head、options、postJson、putJson、patchJson、postForm、putForm
• createHttpClient を使ってカスタム HTTP クライアントを作成することもできます。

ベストプラクティス：

• json: true オプションを使うと、JSON レスポンスを自動的に解析できます。
• try/catch でエラーを処理し、明確なエラーオブジェクトを返してください。