SingleStore MCP 服务器

一个用于与 SingleStore 数据库交互的 Model Context Protocol (MCP) 服务器。该服务器提供了查询表、描述模式和生成 ER 图的工具。

功能

• 列出数据库中的所有表
• 执行自定义 SQL 查询
• 获取包括模式和示例数据在内的详细表信息
• 生成数据库模式的 Mermaid ER 图
• 支持 SSL 并自动获取 CA 包
• 正确的错误处理和 TypeScript 类型安全

先决条件

• Node.js 16 或更高版本
• npm 或 yarn
• 访问 SingleStore 数据库
• SingleStore CA 包（从门户自动获取）

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 SingleStore MCP 服务器：

npx -y @smithery/cli install @madhukarkumar/singlestore-mcp-server --client claude

1. 克隆仓库：

git clone <repository-url>
cd mcp-server-singlestore

1. 安装依赖项：

npm install

1. 构建服务器：

npm run build

环境变量

必需的环境变量

服务器需要以下环境变量来连接数据库：

SINGLESTORE_HOST=your-host.singlestore.com
SINGLESTORE_PORT=3306
SINGLESTORE_USER=your-username
SINGLESTORE_PASSWORD=your-password
SINGLESTORE_DATABASE=your-database

所有这些环境变量都是服务器建立与您的 SingleStore 数据库连接所必需的。连接使用 SSL 和 SingleStore CA 包，该包会自动从 SingleStore 门户获取。

可选的环境变量

对于 SSE（Server-Sent Events）协议支持：

SSE_ENABLED=true       # Enable the SSE HTTP server (default: false if not set)
SSE_PORT=3333          # HTTP port for the SSE server (default: 3333 if not set)

设置环境变量

1. 在 Shell 中：
   在运行服务器之前，在终端中设置这些变量：

   export SINGLESTORE_HOST=your-host.singlestore.com
   export SINGLESTORE_PORT=3306
   export SINGLESTORE_USER=your-username
   export SINGLESTORE_PASSWORD=your-password
   export SINGLESTORE_DATABASE=your-database
   

2. 在客户端配置文件中：
   将变量添加到您的 MCP 客户端配置文件中，如下面的集成部分所示。

使用

协议支持

此服务器支持两种客户端集成协议：

1. MCP 协议：使用 stdio 通信的标准 Model Context Protocol，由 Claude Desktop、Windsurf 和 Cursor 使用。
2. SSE 协议：基于 HTTP 的 Server-Sent Events，适用于需要实时数据流的 Web 客户端和应用程序。

这两种协议都暴露相同的工具和功能，允许您根据用例选择最佳的集成方法。

可用工具

1. list_tables

   • Lists all tables in the database
   • No parameters required

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "list_tables",
     arguments: {}
   })
   

2. query_table

   • Executes a custom SQL query
   • Parameters:
     • query: SQL query string

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "query_table",
     arguments: {
       query: "SELECT * FROM your_table LIMIT 5"
     }
   })
   

3. describe_table

   • Gets detailed information about a table
   • Parameters:
     • table: Table name

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "describe_table",
     arguments: {
       table: "your_table"
     }
   })
   

4. generate_er_diagram

   • Generates a Mermaid ER diagram of the database schema
   • No parameters required

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "generate_er_diagram",
     arguments: {}
   })
   

5. run_read_query

   • Executes a read-only (SELECT) query on the database
   • Parameters:
     • query: SQL SELECT query to execute

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "run_read_query",
     arguments: {
       query: "SELECT * FROM your_table LIMIT 5"
     }
   })
   

6. create_table

   • Create a new table in the database with specified columns and constraints
   • Parameters:
     • table_name: Name of the table to create
     • columns: Array of column definitions
     • table_options: Optional table configuration

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "create_table",
     arguments: {
       table_name: "new_table",
       columns: [
         {
           name: "id",
           type: "INT",
           nullable: false,
           auto_increment: true
         },
         {
           name: "name",
           type: "VARCHAR(255)",
           nullable: false
         }
       ],
       table_options: {
         shard_key: ["id"],
         sort_key: ["name"]
       }
     }
   })
   

7. generate_synthetic_data

   • Generate and insert synthetic data into an existing table
   • Parameters:
     • table: Name of the table to insert data into
     • count: Number of rows to generate (default: 100)
     • column_generators: Custom generators for specific columns
     • batch_size: Number of rows to insert in each batch (default: 1000)

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "generate_synthetic_data",
     arguments: {
       table: "customers",
       count: 1000,
       column_generators: {
         "customer_id": {
           "type": "sequence",
           "start": 1000
         },
         "status": {
           "type": "values",
           "values": ["active", "inactive", "pending"]
         },
         "signup_date": {
           "type": "formula",
           "formula": "NOW() - INTERVAL FLOOR(RAND() * 365) DAY"
         }
       },
       batch_size: 500
     }
   })
   

8. optimize_sql

   • Analyze a SQL query using PROFILE and provide optimization recommendations
   • Parameters:
     • query: SQL query to analyze and optimize

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "optimize_sql",
     arguments: {
       query: "SELECT * FROM customers JOIN orders ON customers.id = orders.customer_id WHERE region = 'west'"
     }
   })
   

   • The response includes:
     • Original query
     • Performance profile summary (total runtime, compile time, execution time)
     • List of detected bottlenecks
     • Optimization recommendations with impact levels (high/medium/low)
     • Suggestions for indexes, joins, memory usage, and other optimizations

独立运行

1. 构建服务器：

npm run build

1. 仅使用MCP协议运行服务器：

node build/index.js

1. 同时使用MCP和SSE协议运行服务器：

SSE_ENABLED=true SSE_PORT=3333 node build/index.js

使用 SSE 协议

当启用SSE时，服务器会暴露以下HTTP端点：

1. 根端点

   GET /
   

   返回服务器信息及可用端点。

2. 健康检查

   GET /health
   

   返回有关服务器状态的信息。

3. SSE连接

   GET /sse
   

   建立Server-Sent Events连接以实现实时更新。

4. 工具列表

   GET /tools
   

   返回所有可用工具的列表，与MCP的list_tools功能相同。

   同时支持POST请求以便与MCP Inspector兼容：

   POST /tools
   Content-Type: application/json
   
   {
     "jsonrpc": "2.0",
     "id": "request-id",
     "method": "mcp.list_tools",
     "params": {}
   }
   

5. 调用工具

   POST /call-tool
   Content-Type: application/json
   
   {
     "name": "tool_name",
     "arguments": {
       "param1": "value1",
       "param2": "value2"
     },
     "client_id": "optional_sse_client_id_for_streaming_response"
   }
   

   使用提供的参数执行工具。

   • 如果提供了client_id，则响应将流式传输到该SSE客户端。
   • 如果省略了client_id，则响应直接在HTTP响应中返回。

   同样支持标准MCP格式以便与MCP Inspector兼容：

   POST /call-tool
   Content-Type: application/json
   
   {
     "jsonrpc": "2.0",
     "id": "request-id",
     "method": "mcp.call_tool",
     "params": {
       "name": "tool_name",
       "arguments": {
         "param1": "value1",
         "param2": "value2"
       },
       "_meta": {
         "client_id": "optional_sse_client_id_for_streaming_response"
       }
     }
   }
   

SSE 事件类型

使用SSE连接时，服务器发送以下类型的事件：

1. message (未命名事件)：当SSE连接成功建立时发送。
2. open：附加连接建立事件。
3. message：用于所有MCP协议消息，包括工具启动、结果和错误事件。

所有事件遵循MCP协议使用的JSON-RPC 2.0格式。系统使用标准的message事件类型来与MCP Inspector以及大多数SSE客户端库兼容。

示例JavaScript客户端

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:3333/sse');
let clientId = null;

// Handle connection establishment via unnamed event
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'connection_established') {
    clientId = data.clientId;
    console.log(`Connected with client ID: ${clientId}`);
  }
};

// Handle open event
eventSource.addEventListener('open', (event) => {
  console.log('SSE connection opened via open event');
});

// Handle all MCP messages
eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.jsonrpc === '2.0') {
    if (data.result) {
      console.log('Tool result:', data.result);
    } else if (data.error) {
      console.error('Tool error:', data.error);
    } else if (data.method === 'mcp.call_tool.update') {
      console.log('Tool update:', data.params);
    }
  }
});

// Call a tool with streaming response (custom format)
async function callTool(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      arguments: args,
      client_id: clientId
    })
  });
  return response.json();
}

// Call a tool with streaming response (MCP format)
async function callToolMcp(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'request-' + Date.now(),
      method: 'mcp.call_tool',
      params: {
        name: name,
        arguments: args,
        _meta: {
          client_id: clientId
        }
      }
    })
  });
  return response.json();
}

// Example usage
callTool('list_tables', {})
  .then(response => console.log('Request accepted:', response));

与 MCP Inspector 一起使用

MCP Inspector是一个基于浏览器的工具，用于测试和调试MCP服务器。要与此服务器一起使用：

1. 通过一条命令同时启动服务器和MCP检查器：

   npm run inspector
   

   或者仅启动服务器：

   npm run start:inspector
   

2. 单独安装并运行MCP检查器：

   npx @modelcontextprotocol/inspector
   

   检查器将在您的默认浏览器中打开。

3. 当MCP检查器打开时：

   a. 在连接字段中输入URL：

   http://localhost:8081
   

   注意：实际端口号可能根据您的配置有所不同。请检查服务器启动日志以获取实际使用的端口。服务器将输出：

   MCP SingleStore SSE server listening on port XXXX
   

   b. 确保选择了"SSE"作为传输类型

   c. 点击“连接”

4. 如果遇到连接问题，请尝试以下替代方案：

   a. 尝试连接到特定的端点：

   http://localhost:8081/stream
   

   b. 尝试使用您的机器的实际IP地址：

   http://192.168.1.x:8081
   

   c. 如果在Docker中运行：

   http://host.docker.internal:8081
   

5. 调试连接问题：

   a. 通过访问http://localhost:8081来验证服务器是否正在运行

   b. 检查服务器日志中的连接尝试记录

   c. 尝试重新启动服务器和检查器

   d. 确保没有其他服务占用8081端口

   e. 使用提供的脚本测试SSE连接：

   npm run test:sse
   

   或者手动使用curl：

   curl -N http://localhost:8081/sse
   

   f. 确认防火墙设置允许连接到8081端口

6. 连接成功后，检查器将显示所有可用工具，并允许您交互式地测试它们。

⚠️ 注意：在使用MCP检查器时，必须使用完整的URL，包括http://前缀。

MCP客户端集成

在Claude Desktop中安装

1. 将服务器配置添加到位于以下位置的Claude Desktop配置文件中：
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED 和 SSE_PORT 变量是可选的。如果您希望启用支持SSE的标准MCP协议HTTP服务器，请包含这些变量。

1. 重启Claude Desktop应用程序

2. 在与Claude的对话中，现在可以使用SingleStore MCP服务器了：

use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

在Windsurf中安装

1. 将服务器配置添加到位于以下位置的Windsurf配置文件中：
   • macOS: ~/Library/Application Support/Windsurf/config.json
   • Windows: %APPDATA%\Windsurf\config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED 和 SSE_PORT 变量是可选的，但可以通过SSE HTTP服务器启用额外功能。

1. 重启 Windsurf

2. 在你与 Windsurf 中的 Claude 对话时，当 Claude 需要访问数据库信息时，SingleStore MCP 工具将自动可用。

在 Cursor 中安装

1. 将服务器配置添加到你的 Cursor 设置中：
   • 打开 Cursor
   • 转到设置（齿轮图标）> 扩展 > Claude AI > MCP 服务器
   • 使用以下配置添加一个新的 MCP 服务器：

{
  "singlestore": {
    "command": "node",
    "args": ["path/to/mcp-server-singlestore/build/index.js"],
    "env": {
      "SINGLESTORE_HOST": "your-host.singlestore.com",
      "SINGLESTORE_PORT": "3306",
      "SINGLESTORE_USER": "your-username",
      "SINGLESTORE_PASSWORD": "your-password",
      "SINGLESTORE_DATABASE": "your-database",
      "SSE_ENABLED": "true",
      "SSE_PORT": "3333"
    }
  }
}

SSE_ENABLED 和 SSE_PORT 变量允许 Web 应用程序通过 HTTP 连接到服务器并通过 Server-Sent Events 接收实时更新。

1. 重启 Cursor

2. 当在 Cursor 中使用 Claude AI 时，SingleStore MCP 工具可用于数据库操作。

安全考虑

1. 永远不要将凭证提交到版本控制系统
2. 使用环境变量或安全配置管理
3. 考虑在生产环境中使用连接池机制
4. 在 SingleStore 中实现适当的访问控制和用户权限
5. 保持 SingleStore CA 包是最新的

开发

项目结构

mcp-server-singlestore/
├── src/
│   └── index.ts      # Main server implementation
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

构建

npm run build

测试

npm test

故障排除

1. 连接问题

   • 验证环境变量中的凭证和主机信息
   • 检查 SSL 配置
   • 确保可以从你的网络访问数据库
   • 检查防火墙设置，以允许向外连接到你的 SingleStore 数据库

2. 构建问题

   • 清除 node_modules 并重新安装依赖项
   • 验证 TypeScript 配置
   • 检查 Node.js 版本兼容性（应为 16+）

3. MCP 集成问题

   • 验证客户端配置中服务器的 build/index.js 文件路径是否正确
   • 检查所有环境变量是否已在客户端配置中正确设置
   • 在进行配置更改后重启客户端应用程序
   • 检查客户端日志中与 MCP 服务器相关的任何错误消息
   • 尝试先独立运行服务器，以验证它在客户端之外是否正常工作

贡献

1. 分叉仓库
2. 创建一个功能分支
3. 提交你的更改
4. 推送到该分支
5. 创建一个 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件