Prisma MCP Server

Prisma MCP Server

このパッケージは、Prisma ORM で管理されたデータベースへのインターフェースとして機能する、Model Context Protocol（MCP）サーバーを提供します。MCP に対応したクライアント（AI アシスタントやその他のアプリケーションなど）が、リソースのクエリやツールの実行を通じてデータベースとやり取りできるようにします。

このサーバーは fastmcp を使用して、Prisma のモデルと操作を公開します。

機能

• リソースの読み込み： Prisma のモデルを、読み取り可能な MCP リソースとして公開します（例：resource://users/{user_id}、resource://projects）。
• ツールの実行： Prisma のモデルに対する一般的な CRUD（作成、読み取り、更新、削除）操作用の MCP ツールを提供します（例：create_user、update_project）。
• データベースとのやり取り： MCP リクエストと Prisma Client のデータベースクエリ間の変換を処理します。
• 設定可能なトランスポート： stdio と sse（HTTP 経由の Server-Sent Events）の両方のトランスポートモードに対応しています。
• 拡張性： 複雑な操作や他のアプリケーションサービスとのやり取りに対応するため、カスタムリソースやツールを簡単に追加できます。

前提条件

• Node.js： 最近のバージョン（指定がある場合は package.json の engines を確認してください）。
• Yarn または npm： パッケージマネージャー。
• Prisma Client： このパッケージを利用するプロジェクトに、@prisma/client がインストールされており、対象のデータベース用に設定された prisma/schema.prisma ファイルが必要です。
• データベース： Prisma がサポートする稼働中のデータベースインスタンス（例：PostgreSQL、MySQL、SQLite）。

インストール

# Using yarn
yarn add cadcamfun-db-mcp-server @prisma/client

# Using npm
npm install cadcamfun-db-mcp-server @prisma/client

注： このサーバーパッケージを使用するプロジェクトでは、@prisma/client をピア依存関係として必ずインストールしてください。

利用プロジェクトでのセットアップ

1. Prisma スキーマ： プロジェクトのルートに、有効なデータベース接続とモデルを定義した prisma/schema.prisma ファイルがあることを確認してください。
2. 環境変数： 必要な環境変数を設定してください（例：.env ファイル内）。DATABASE_URL などの機密情報をバージョン管理に直接コミットしないでください。
   • DATABASE_URL：（必須） データベースへの接続文字列（例：postgresql://user:password@host:port/database）。
   • TRANSPORT_TYPE：（任意）HTTP 経由の Server-Sent Events を使用する場合は、sse に設定します。デフォルトは stdio です。
   • PORT：（任意、TRANSPORT_TYPE=sse が必要）SSE サーバーのポートです。デフォルトは 8080 です。
   • MAIN_APP_URL：（任意）trigger_main_app_notification など、メインアプリケーションへのコールバックが必要なツールを使用する場合の、メインアプリケーションのベース URL です。デフォルトは http://localhost:3000 です。
   • LOG_LEVEL：（任意）ログの詳細度を制御します。DEBUG、INFO、WARN、ERROR のいずれかを設定します。動作は、パッケージ内のロガー実装（使用されている場合）によって異なります。
3. Prisma Client の生成： サーバーを実行する前に、スキーマに基づいて Prisma Client を必ず生成してください。

   npx prisma generate
   

   サーバーは node_modules/@prisma/client 内の生成済みクライアントに依存しているため、この手順は非常に重要です。

使用方法

// Example: index.ts in your consuming project

// Import the server creation function
import { createPrismaMcpServer } from 'prisma-mcp-server';
import { PrismaClient } from '@prisma/client'; // Make sure Prisma Client is installed

// Ensure required environment variables are set
if (!process.env.DATABASE_URL) {
  console.error("Error: DATABASE_URL environment variable is not set.");
  process.exit(1);
}

// Optional: Configure transport type and port via environment variables
// process.env.TRANSPORT_TYPE = 'sse';
// process.env.PORT = '8081';

async function main() {
  // Ensure Prisma Client is generated (Best done in a build step)
  try {
    // Check if client exists, generate if not (simple check)
    require.resolve('@prisma/client'); 
  } catch (e) {
      console.log('Prisma Client not found, attempting to generate...');
      try {
          const { execSync } = require('child_process');
          execSync('npx prisma generate', { stdio: 'inherit' });
          console.log('Prisma Client generated.');
      } catch (error) {
          console.error('Error generating Prisma Client:', error);
          process.exit(1);
      }
  }

  // Create the server instance
  const server = createPrismaMcpServer({
    // Optional: Override default server info if needed
    // name: "MyCustomServerName",
    // version: "2.0.0",
    // instructions: "Custom instructions..."
  });

  console.log(`Starting Prisma MCP Server...`);

  // Determine transport options based on environment variables
  const transportType = process.env.TRANSPORT_TYPE === 'sse' ? 'sse' : 'stdio';
  const port = parseInt(process.env.PORT || "8080");
  const sseEndpoint = "/sse"; // Assuming hardcoded endpoint

  const startOptions: any = { transportType }; // Use 'any' temporarily if exact type is complex
  if (transportType === 'sse') {
    startOptions.sse = { endpoint: sseEndpoint, port: port };
  }

  // Start the server using the options derived from environment variables
  server.start(startOptions);

  console.log(`Server started with transport: ${transportType}`);
  if (transportType === 'sse') {
      console.log(`SSE endpoint available at http://localhost:${port}${sseEndpoint}`);
  }
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

これで、設定したトランスポート方式（stdio または /sse エンドポイント）を使用して、実行中のサーバーに MCP クライアントを接続できます。

Claude Desktop との接続

Claude Desktop（または同様の MCP クライアント）は、stdio または sse のトランスポート方式を使ってこのサーバーに接続できます。

1. トランスポートの設定：

   • サーバーを起動する前に、利用側プロジェクトの環境（.env ファイルやシステム環境など）で TRANSPORT_TYPE 環境変数を設定します。
     • TRANSPORT_TYPE=stdio（デフォルト）：サーバーは標準入力と標準出力を介して通信します。
     • TRANSPORT_TYPE=sse：サーバーは Server-Sent Events 用の HTTP サーバーを起動します。
   • sse を使用する場合は、PORT 環境変数も設定できます（デフォルトは 8080 です）。

2. サーバーの起動：

   • 使用方法のセクションに示すように、prisma-mcp-server を作成して起動するコードを含む、利用側アプリケーションのエントリーポイント（例：node your-app-entrypoint.js）を実行します。

3. Claude Desktop への接続：

   • stdio を使用する場合： サーバープロセスを直接起動するように Claude Desktop を設定します。通常は、アプリケーションを起動するコマンド（例：node /path/to/your-app-entrypoint.js、または起動スクリプトがある場合は yarn start）を指定します。
   • sse を使用する場合： HTTP エンドポイントに接続するように Claude Desktop を設定します。デフォルトの URL は http://localhost:8080/sse です。PORT を変更した場合は、それに合わせて調整してください。

4. サーバーの識別：

   • Claude Desktop でサーバーを識別する必要がある場合があります。デフォルト名は PrismaAPI_Server（バージョン 1.1.0）ですが、createPrismaMcpServer の呼び出し時に変更できます。

Claude Desktop 用 mcp.json の設定例：

• stdio を使用する場合：

  {
    "mcpServers": {
      "prisma_api_stdio": {
        "name": "Prisma API Server (stdio)", // 任意の表示名
        // オプション 1：スクリプト名／パッケージ名を使って npx を使用
        "command": "npx",
        "args": [
          "cadcamfun-db-mcp-server" // 実際のスクリプト名／パッケージ名に置き換えてください
        ],
        // オプション 2：yarn/npm の実行スクリプトを使用
        // "command": "yarn", 
        // "args": ["start:prisma-mcp"], // 'start:prisma-mcp' という名前のスクリプトがあることを前提としています
        "workingDirectory": "" // 利用側プロジェクトのルートへのパスに置き換えてください
      }
    }
  }
  

• sse を使用する場合：

  {
    "mcpServers": {
      "prisma_api_sse": {
        "name": "Prisma API Server (SSE)", // 任意の表示名
        // サーバーが起動しており、ポート 8080（デフォルト）で待ち受けていることを前提としています
        // サーバー起動時に PORT 環境変数でポートを変更できます。
        "url": "http://localhost:8080/sse" 
      }
    }
  }
  

新しい MCP サーバー接続を追加して設定する具体的な手順については、お使いの MCP クライアントのドキュメントを参照してください。

利用可能なリソースとツール

このサーバーは、内部スキーマ（パッケージ内の prisma/schema.prisma。ただし、利用側のプロジェクトで生成されたクライアントを使用します）で定義された Prisma モデルに対応する MCP リソースとツールを公開します。

リソース（例）：

• resource://users
• resource://users/{user_id}
• resource://projects
• resource://projects/{project_id}
• resource://drawings?project_id={project_id}
• resource://drawings/{drawing_id}
• resource://components?project_id={project_id}
• resource://components/{component_id}
• resource://materials
• resource://materials/{material_id}
• resource://tools
• resource://tools/{tool_id}
• resource://machine-configs
• resource://machine-configs/{machine_config_id}
• resource://toolpaths?project_id={project_id}
• resource://toolpaths/{toolpath_id}
• resource://library-items
• resource://library-items/{library_item_id}

(一覧と引数の詳細については、src/resources.ts を参照してください)

ツール（例）：

• create_user、update_user、delete_user
• create_subscription、update_subscription、delete_subscription
• create_organization、update_organization、delete_organization
• create_project、update_project、delete_project
• create_drawing、update_drawing、delete_drawing
• create_component、update_component、delete_component
• create_material、update_material、delete_material
• create_tool_prisma、update_tool_prisma、delete_tool_prisma
• create_machine_config、update_machine_config、delete_machine_config
• create_toolpath、update_toolpath、delete_toolpath
• create_library_item、update_library_item、delete_library_item
• trigger_main_app_notification（カスタムツールの例）

(Zod を使用して定義された一覧とパラメーターの詳細については、src/tools.ts を参照してください)

拡張

このパッケージをフォークするか、ベースとして使用し、src/resources.ts と src/tools.ts を変更して独自のカスタムリソースとツールを追加できます。変更後は、忘れずに再ビルド（yarn build）してください。

デプロイ

1. データベースの設定： 本番環境の DATABASE_URL 環境変数が、デプロイ環境（サーバーの環境変数、シークレットマネージャーなど）で正しく設定されていることを確認してください。これをリポジトリにコミットしないでください。
2. 環境変数： デプロイ環境で TRANSPORT_TYPE（sse または stdio）を設定し、必要に応じて PORT と MAIN_APP_URL も設定してください。
3. ビルドと実行：

   # プロジェクトディレクトリ（prisma-mcp-server が依存関係に含まれている場所）に移動します
   
   # 依存関係をインストールします
   yarn install --production # または npm install --omit=dev
   
   # Prisma Client を生成します（重要！DATABASE_URL が必要です）
   npx prisma generate
   
   # マイグレーションを適用します（DATABASE_URL が必要です。使用する方針に合わせて置き換えてください）
   # 例：
   # npx prisma migrate deploy 
   
   # アプリケーション（サーバーコードを含む）をビルドします
   yarn build # または使用するビルドコマンド
   
   # アプリケーション（MCP サーバーを起動します）を起動します
   # 本番環境では pm2 などのプロセスマネージャーを使用してください
   # 例：
   # pm2 start your-app-entrypoint.js 
   # または
   # node your-app-entrypoint.js 
   

ライセンス

[MIT]