Prisma MCP Server

Prisma MCP 服务

此软件包提供了一个 Model Context Protocol（MCP）服务，作为 Prisma ORM 管理的数据库的接口。它允许兼容 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 Schema： 确保项目根目录中有有效的 prisma/schema.prisma 文件，其中定义了数据库连接和模型。
2. 环境变量： 配置必要的环境变量（例如，在 .env 文件中）。请勿将 DATABASE_URL 等敏感变量直接提交到版本控制中。
   • DATABASE_URL：**（必需）**数据库连接字符串（例如，postgresql://user:password@host:port/database）。
   • TRANSPORT_TYPE：（可选）设置为 sse，以使用基于 HTTP 的 Server-Sent Events。默认为 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： 运行服务之前，必须 根据 schema 生成 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. 配置传输方式：

   • 启动服务前，在使用该服务的项目环境中设置 TRANSPORT_TYPE 环境变量（例如，在 .env 文件或系统环境变量中）：
     • TRANSPORT_TYPE=stdio（默认）：服务将通过标准输入和输出进行通信。
     • TRANSPORT_TYPE=sse：服务将启动一个用于服务器发送事件的 HTTP 服务。
   • 如果使用 sse，还可以设置 PORT 环境变量（默认值为 8080）。

2. 启动服务：

   • 运行使用该服务的应用程序入口点（例如，node your-app-entrypoint.js），其中包含创建并启动 prisma-mcp-server 的代码（如用法部分所示）。

3. 连接 Claude Desktop：

   • 如果使用 stdio： 将 Claude Desktop 配置为直接启动服务进程。通常需要提供启动应用程序的命令（例如，node /path/to/your-app-entrypoint.js，或者如果你有启动脚本，则使用 yarn start）。
   • 如果使用 sse： 将 Claude Desktop 配置为连接到 HTTP 端点。默认 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 模型对应的 MCP 资源和工具（位于软件包内的 prisma/schema.prisma，但使用的是使用该软件包的项目生成的客户端）。

资源（示例）：

• 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. 构建并运行：

   # Navigate to your project directory (where prisma-mcp-server is a dependency)
   
   # Install dependencies
   yarn install --production # Or npm install --omit=dev
   
   # Generate Prisma Client (Important! Needs DATABASE_URL)
   npx prisma generate
   
   # Apply Migrations (Needs DATABASE_URL - Replace with your strategy)
   # Example:
   # npx prisma migrate deploy 
   
   # Build your application (which includes the server code)
   yarn build # Or your specific build command
   
   # Start your application (which starts the MCP server)
   # Use a process manager like pm2 in production
   # Example:
   # pm2 start your-app-entrypoint.js 
   # OR
   # node your-app-entrypoint.js 
   

许可证

[MIT]