Karakuri MCP

このプロジェクトは、AIエージェントから複数の特定APIを効率よく呼び出せるように設計された、モジュール式の MCP (Model Context Protocol) サーバー です。 「何でもできるサーバー」ではなく、必要なAPI（プラグイン）を少しずつ個別に追加し、管理できるように作られています。

📦 現在インストールされているプラグイン

現在、以下のサービスが組み込まれています。

1. PiAPI Seedance (piapi-seedance)

   • PiAPIの seedance-2 (動画生成AI) を利用して動画を生成するプラグインです。

   • ツール: create_seedance_task, get_seedance_task

   • 利用するには .env に SEEDDANCE2.0_API_KEY を設定する必要があります。

2. File Utils (file-utils)

   • 動画ファイルなどを指定したURLからローカルの downloads/ フォルダへ自動保存する共通ツールです。

   • ツール: download_file

3. Logger Service (logger-service)

   • すべてのツール呼び出しを mcp-audit.log に自動記録し、AIエージェント自身が過去の実行履歴を読み出せる監査ログツールです。

   • ツール: get_audit_logs

Related MCP server: MCP Plus

🚀 セットアップ方法

1. 依存関係のインストール

   npm install

2. 環境変数の設定 プロジェクト直下に .env ファイルを作成（または .env.example をコピー）し、APIキーを設定してください。

   SEEDDANCE2.0_API_KEY=your_piapi_seedance_api_key_here

3. ビルド TypeScriptコードをコンパイルします。

   npm run build

4. テスト実行 同梱されているテストクライアントを使って、サーバーの動作確認が可能です。

   npx tsx test-client.ts

🛠️ プラグイン（新API）の追加方法

このサーバーは、新しいAPIを簡単に追加できる「プラガブル（着脱可能）」なアーキテクチャを採用しています。 新しいAPIを追加するには、以下の3ステップを行うだけです。

Step 1: サービスモジュールの作成

src/services/ フォルダ内に新しいディレクトリを作成し、index.ts を配置します。 （例: src/services/my-new-api/index.ts）

src/types.ts で定義されている McpService インターフェースを満たすオブジェクトを作成し、エクスポートします。

import { Tool } from "@modelcontextprotocol/sdk/types.js";
import { McpService } from "../../types.js";

export const myNewApiService: McpService = {
  name: "my-new-api",
  getTools(): Tool[] {
    return [
      {
        name: "my_tool_name",
        description: "新しいツールの説明",
        inputSchema: { /* JSON Schema */ }
      }
    ];
  },
  async handleToolCall(name: string, args: any): Promise<{ content: any[]; isError?: boolean }> {
    if (name === "my_tool_name") {
      return { content: [{ type: "text", text: "Success!" }] };
    }
    throw new Error(`Unknown tool: ${name}`);
  }
};

Step 2: 環境変数の準備

新しいAPIに認証キーが必要な場合は、他のモジュールと干渉しないように独自の環境変数（例: MY_NEW_API_KEY）を .env に追加し、モジュール内でそれを利用するようにしてください。

Step 3: ルーター (src/index.ts) への登録

作成したモジュールを src/index.ts でインポートし、services 配列に追加します。

// src/index.ts
import { myNewApiService } from "./services/my-new-api/index.js";

const services: McpService[] = [
  piapiSeedanceService,
  fileUtilsService,
  loggerService,
  myNewApiService // ← これを追加するだけ！
];

これで作業は完了です！ 再ビルド (npm run build) すれば、AIエージェントは自動的に新しいツールを認識し、利用できるようになります。ツールの実行履歴も自動的に logger-service によって記録されます。