单库服务器

Name: 单库服务器
Author: madhukarkumar

作者：madhukarkumar4 星标更新：2025-03-12

安装使用来源：spider==github.com

项目介绍

SingleStore MCP Server

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

功能

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

预备条件

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

安装

通过Smithery安装

要通过Smithery自动安装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门户获取SingleStore CA捆绑包。

可选的环境变量

支持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协议：标准的Model Context Protocol，使用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功能相同。

还支持MCP Inspector兼容性的POST请求：

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": "可选的sse客户端ID以进行流式响应"
}

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

如果提供了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": "可选的sse客户端ID以进行流式响应"
    }
  }
}

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(`已连接，客户端ID：${clientId}`);
  }
};

// 处理open事件
eventSource.addEventListener('open', (event) => {
  console.log('通过open事件打开SSE连接');
});

// 处理所有MCP消息
eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.jsonrpc === '2.0') {
    if (data.result) {
      console.log('工具结果：', data.result);
    } else if (data.error) {
      console.error('工具错误：', data.error);
    } else if (data.method === 'mcp.call_tool.update') {
      console.log('工具更新：', 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('请求已接受：', response));

与MCP Inspector一起使用

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

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

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

c. 点击“连接”
如果遇到连接问题，请尝试以下替代方案：

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. 尝试重新启动服务器和检查器

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

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

⚠️ 注意：使用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变量是可选的。如果希望启用带有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
- 转到设置（齿轮图标）> 扩展 > 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