MCP 服务器

SingleStore MCP Server

一个用于与 SingleStore 数据库交互的服务器，支持表格查询、模式描述和 ER 图生成，并提供安全的 SSL 支持和 TypeScript 安全性。

数据库交互

访问服务器

Tools

query_table

Execute a query on a table

generate_er_diagram

Generate a Mermaid ER diagram of the database schema

list_tables

List all tables in the database

describe_table

Get detailed information about a table

run_read_query

Execute a read-only (SELECT) query on the database

create_table

Create a new table in the database with specified columns and constraints

generate_synthetic_data

Generate and insert synthetic data into an existing table

optimize_sql

Analyze a SQL query using PROFILE and provide optimization recommendations

README

SingleStore MCP 服务器

用于与 SingleStore 数据库交互的模型上下文协议 (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

克隆存储库：

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

安装依赖项：

npm install

构建服务器：

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       # 启用 SSE HTTP 服务器（如果未设置，则默认为 false）
SSE_PORT=3333          # SSE 服务器的 HTTP 端口（如果未设置，则默认为 3333）

设置环境变量

在您的 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

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

用法

协议支持

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

MCP 协议：使用 stdio 通信的标准模型上下文协议，由 Claude Desktop、Windsurf 和 Cursor 使用。
SSE 协议：通过 HTTP 的服务器发送事件，适用于需要实时数据流的基于 Web 的客户端和应用程序。

两种协议都公开相同的工具和功能，允许您为您的用例选择最佳集成方法。

可用工具

list_tables

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

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

query_table

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

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

describe_table

获取有关表的详细信息
参数：
- table：表名

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

generate_er_diagram

生成数据库模式的 Mermaid ER 图
无需参数

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

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

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

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

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'"
  }
})
```
- 响应包括：
  - 原始查询
  - 性能分析摘要（总运行时间、编译时间、执行时间）
  - 检测到的瓶颈列表
  - 优化建议，包括影响级别（高/中/低）
  - 关于索引、连接、内存使用和其他优化的建议

独立运行

构建服务器：

npm run build

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

node build/index.js

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

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

使用 SSE 协议

启用 SSE 后，服务器会公开以下 HTTP 端点：

根端点
```
GET /
```
返回服务器信息和可用端点。
健康检查
```
GET /health
```
返回有关服务器的状态信息。
SSE 连接
```
GET /sse
```
建立用于实时更新的服务器发送事件连接。

列出工具

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": {}
}

调用工具

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 Inspector 兼容性的标准 MCP 格式：

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 连接时，服务器会发送以下事件类型：

message（未命名事件）：在成功建立 SSE 连接时发送。
open：其他连接建立事件。
message：用于所有 MCP 协议消息，包括工具启动、结果和错误事件。

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

JavaScript 客户端示例

// 连接到 SSE 端点
const eventSource = new EventSource('http://localhost:3333/sse');
let clientId = null;

// 通过未命名事件处理连接建立
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'connection_established') {
    clientId = data.clientId;
    console.log(`Connected with client ID: ${clientId}`);
  }
};

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

// 处理所有 MCP 消息
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);
    }
  }
});

// 使用流式响应调用工具（自定义格式）
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();
}

// 使用流式响应调用工具（MCP 格式）
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();
}

// 用法示例
callTool('list_tables', {})
  .then(response => console.log('Request accepted:', response));

与 MCP Inspector 一起使用

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

在一个命令中启动服务器和 MCP inspector：
```
npm run inspector
```
或者仅启动服务器：
```
npm run start:inspector
```
要单独安装和运行 MCP Inspector：
```
npx @modelcontextprotocol/inspector
```
inspector 将在您的默认浏览器中打开。
当 MCP Inspector 打开时：

a. 在连接字段中输入 URL：
```
http://localhost:8081
```
注意：实际端口可能因您的配置而异。检查服务器启动日志以获取正在使用的实际端口。服务器将输出：
```
MCP SingleStore SSE server listening on port XXXX
```
b. 确保选择 "SSE" 作为传输类型

c. 单击 "Connect"
如果遇到连接问题，请尝试以下替代方法：

a. 尝试连接到特定端点：
```
http://localhost:8081/stream
```
b. 尝试使用您机器的实际 IP 地址：
```
http://192.168.1.x:8081
```
c. 如果在 Docker 中运行：
```
http://host.docker.internal:8081
```
调试连接问题：

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

b. 检查服务器日志以获取连接尝试

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

d. 确保没有其他服务正在使用端口 8081

e. 使用提供的脚本测试 SSE 连接：
```
npm run test:sse
```
或者手动使用 curl：
```
curl -N http://localhost:8081/sse
```
f. 验证您的防火墙设置是否允许连接到端口 8081
连接后，inspector 将显示所有可用工具，并允许您以交互方式测试它们。

⚠️ 注意：使用 MCP Inspector 时，必须使用完整 URL，包括 http:// 前缀。

MCP 客户端集成

在 Claude Desktop 中安装

将服务器配置添加到您的 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 服务器，请包含它们。

重新启动 Claude Desktop 应用程序
在您与 Claude 的对话中，您现在可以使用 SingleStore MCP 服务器：

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

在 Windsurf 中安装

将服务器配置添加到您的 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 服务器启用其他功能。

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

在 Cursor 中安装

将服务器配置添加到您的 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 连接到服务器，并通过服务器发送事件接收实时更新。

重新启动 Cursor
在 Cursor 中使用 Claude AI 时，SingleStore MCP 工具将可用于数据库操作。

安全注意事项

永远不要将凭据提交到版本控制
使用环境变量或安全配置管理
考虑为生产用途使用连接池机制
在 SingleStore 中实施适当的访问控制和用户权限
保持 SingleStore CA 捆绑包为最新

开发

项目结构

mcp-server-singlestore/
├── src/
│   └── index.ts      # 主服务器实现
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

构建

npm run build

测试

npm test

故障排除

连接问题
- 验证环境变量中的凭据和主机信息
- 检查 SSL 配置
- 确保可以从您的网络访问数据库
- 检查您的防火墙设置以允许出站连接到您的 SingleStore 数据库
构建问题
- 清除 node_modules 并重新安装依赖项
- 验证 TypeScript 配置
- 检查 Node.js 版本兼容性（应为 16+）
MCP 集成问题
- 验证客户端配置中服务器的 build/index.js 文件的路径是否正确
- 检查客户端配置中是否正确设置了所有环境变量
- 在进行配置更改后重新启动客户端应用程序
- 检查客户端日志中是否有与 MCP 服务器相关的任何错误消息
- 首先尝试独立运行服务器以验证它在客户端外部是否有效

贡献

Fork 存储库
创建一个功能分支
提交您的更改
推送到分支
创建一个 Pull Request

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件