SingleStore MCP Server

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 Server：

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

1. 克隆代码库：

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

2. 安装依赖项：

npm install

3. 构建服务：

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（服务器发送事件）协议：

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 传输服务器发送事件，适用于需要实时数据流的 Web 客户端和应用程序。

两种协议提供相同的工具和功能，你可以根据使用场景选择最合适的集成方式。

可用工具

1. list_tables

   • 列出数据库中的所有表
   • 无需参数

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

2. query_table

   • 执行自定义 SQL 查询
   • 参数：
     • query：SQL 查询字符串

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

3. describe_table

   • 获取表的详细信息
   • 参数：
     • table：表名

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

4. generate_er_diagram

   • 生成数据库架构的 Mermaid ER 图
   • 无需参数

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

5. run_read_query

   • 在数据库中执行只读（SELECT）查询
   • 参数：
     • query：要执行的 SQL SELECT 查询

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

6. create_table

   • 使用指定的列和约束在数据库中创建新表
   • 参数：
     • table_name：要创建的表名
     • columns：列定义数组
     • table_options：可选的表配置

   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

   • 在现有表中生成并插入合成数据
   • 参数：
     • table：要插入数据的表名
     • count：要生成的行数（默认值：100）
     • column_generators：针对特定列的自定义生成器
     • batch_size：每批插入的行数（默认值：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

   • 使用 PROFILE 分析 SQL 查询并提供优化建议
   • 参数：
     • query：要分析和优化的 SQL 查询

   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'"
     }
   })
   

   • 响应包括：
     • 原始查询
     • 性能概要（总运行时间、编译时间、执行时间）
     • 检测到的瓶颈列表
     • 附带影响等级（高/中/低）的优化建议
     • 关于索引、联接、内存使用和其他优化的建议

独立运行

1. 构建服务：

npm run build

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

node build/index.js

3. 同时使用 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 Inspector：

   npm run inspector
   

   或者仅启动服务：

   npm run start:inspector
   

2. 单独安装并运行 MCP Inspector：

   npx @modelcontextprotocol/inspector
   

   Inspector 将在默认浏览器中打开。

3. 打开 MCP Inspector 后：

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

   http://localhost:8081
   

   注意：实际端口可能因配置而异。请查看服务启动日志，确认实际使用的端口。服务会输出：

   MCP SingleStore SSE server listening on port XXXX
   

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

   c. 点击 "Connect"

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. 尝试重启服务和 Inspector

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

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

   npm run test:sse
   

   或者使用 curl 手动测试：

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

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

6. 连接成功后，Inspector 会显示所有可用工具，并允许你交互式地测试它们。

⚠️ 注意：使用 MCP Inspector 时，必须使用完整 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 变量为可选项。如果要在标准 MCP 协议之外启用支持 SSE 的 HTTP 服务，请添加这些变量。

2. 重启 Claude Desktop 应用

3. 现在，你可以在与 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 服务启用额外功能。

2. 重启 Windsurf

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

在 Cursor 中安装

1. 将服务配置添加到 Cursor 设置中：
   • 打开 Cursor
   • 前往 Settings（齿轮图标）> Extensions > Claude AI > MCP Servers
   • 使用以下配置添加新的 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 接收实时更新。

2. 重启 Cursor

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

安全注意事项

1. 切勿将凭据提交到版本控制系统
2. 使用环境变量或安全的配置管理方式
3. 考虑在生产环境中使用连接池机制
4. 在 SingleStore 中实施适当的访问控制和用户权限
5. 确保 SingleStore CA bundle 保持最新

开发

项目结构

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. Fork 仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

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