Skip to main content
Glama
enesjakozh
madhukarkumar

SingleStore MCP Server

by madhukarkumar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

单店 MCP 服务器

铁匠徽章

用于与 SingleStore 数据库交互的模型上下文协议 (MCP) 服务器。该服务器提供用于查询表、描述模式和生成 ER 图的工具。

特征

  • 列出数据库中的所有表

  • 执行自定义 SQL 查询

  • 获取详细的表信息，包括架构和示例数据

  • 生成数据库模式的 Mermaid ER 图

  • SSL 支持，可自动获取 CA 包

  • 正确的错误处理和 TypeScript 类型安全

Related MCP server: SingleStore MCP Server

先决条件

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

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 通信的标准模型上下文协议，由 Claude Desktop、Windsurf 和 Cursor 使用。

  2. SSE 协议：通过 HTTP 向需要实时数据流的基于 Web 的客户端和应用程序发送服务器发送事件。

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

可用工具

  1. 列表表

    • 列出数据库中的所有表

    • 无需参数 GXP8

  2. 查询表

    • 执行自定义 SQL 查询

    • 参数：

      • 查询：SQL 查询字符串 GXP9

  3. 描述表

    • 获取表的详细信息

    • 参数：

      • 表：表名GXP10

  4. 生成图表

    • 生成数据库模式的 Mermaid ER 图

    • 无需参数 GXP11

  5. 运行读取查询

    • 在数据库上执行只读（SELECT）查询

    • 参数：

      • 查询：执行 GXP12 的 SQL SELECT 查询

  6. 创建表

    • 在数据库中创建具有指定列和约束的新表

    • 参数：

      • table_name：要创建的表的名称

      • columns：列定义数组

      • table_options：可选表配置 GXP13

  7. 生成合成数据

    • 生成合成数据并将其插入现有表中

    • 参数：

      • table：要插入数据的表的名称

      • count：要生成的行数（默认值：100）

      • column_generators：针对特定列的自定义生成器

      • batch_size：每批插入的行数（默认值：1000）GXP14

  8. 优化SQL

    • 使用 PROFILE 分析 SQL 查询并提供优化建议

    • 参数：

      • 查询：用于分析和优化 GXP15 的 SQL 查询

    • 响应内容包括：

      • 原始查询

      • 性能概况摘要（总运行时间、编译时间、执行时间）

      • 检测到的瓶颈列表

      • 具有影响级别（高/中/低）的优化建议

      • 有关索引、连接、内存使用和其他优化的建议

独立运行

  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. 上交所连接

    GET /sse

    建立服务器发送事件连接以进行实时更新。

  4. 列表工具

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

  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. 消息（未命名事件）：当 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 Inspector：

    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桌面应用程序

  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. 重启风帆冲浪

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

在光标处安装

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

  1. 重启光标

  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. 创建拉取请求

执照

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

Available Tools

8 tools
create_tableC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
columnsYesList of columns to create
table_nameYesName of the table to create
table_optionsNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention important behavioral aspects: whether this requires specific database permissions, if it's a destructive operation that might overwrite existing tables, what happens on success/failure, or any rate limits. The description is minimal and doesn't compensate for the lack of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose ('Create a new table in the database') and adds necessary qualification ('with specified columns and constraints'). Every word serves a purpose with zero waste or redundancy. It's appropriately sized for a creation operation with moderate complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a database mutation tool with no annotations, no output schema, and moderate parameter complexity (3 parameters including nested objects), the description is insufficient. It doesn't address critical context: what permissions are needed, whether the operation is idempotent, what happens if a table already exists, what the return value looks like, or error conditions. The agent lacks necessary operational context for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'columns and constraints' which aligns with the 'columns' and 'table_options' parameters in the schema, providing some semantic context beyond the schema's technical descriptions. However, with 67% schema description coverage (2 of 3 parameters have descriptions), the description doesn't fully compensate for the coverage gap - it doesn't explain what 'table_options' encompasses or provide examples of constraint types. The baseline is appropriate given partial schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create a new table') and the resource ('in the database'), with additional context about what gets created ('with specified columns and constraints'). It distinguishes from siblings like 'list_tables' or 'describe_table' by being a creation operation rather than querying existing tables. However, it doesn't explicitly differentiate from other potential table-related operations that might exist in other contexts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., database permissions, existing schema), when not to use it (e.g., for temporary tables vs permanent), or refer to sibling tools like 'generate_er_diagram' for design planning or 'optimize_sql' for performance considerations. The agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_tableC

Get detailed information about a table

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesName of the table to describe

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get detailed information') but doesn't describe what 'detailed information' includes (e.g., schema, columns, constraints), whether it requires specific permissions, or how errors are handled. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose ('Get detailed information about a table'), making it easy to parse quickly. Every word earns its place, and there's no unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a tool that likely returns complex metadata. It doesn't explain what 'detailed information' entails (e.g., column types, indexes), leaving the agent uncertain about the return value. For a tool with such contextual gaps, more detail is needed to be fully helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'table' parameter clearly documented as 'Name of the table to describe'. The description doesn't add any meaning beyond this, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('detailed information about a table'), making the purpose immediately understandable. It distinguishes from siblings like 'list_tables' (which lists tables) and 'query_table' (which queries data), though it doesn't explicitly differentiate them. The description is specific but lacks explicit sibling differentiation for a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to use 'describe_table' instead of 'list_tables' (for metadata vs. listing) or 'query_table' (for data vs. structure), nor does it specify prerequisites like needing an existing table. Usage is implied from the name but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_er_diagramB

Generate a Mermaid ER diagram of the database schema

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but does not reveal any behavioral traits such as whether it requires database permissions, if it's read-only or mutative, potential rate limits, or what the output format entails beyond 'Mermaid ER diagram'. This leaves significant gaps for an agent to understand how to invoke it safely and effectively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function with zero waste. It is front-loaded and appropriately sized for a tool with no parameters, making it easy for an agent to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no annotations, and no output schema, the description is minimally adequate by stating what it does. However, it lacks details on output format (e.g., Mermaid syntax specifics), behavioral context, or usage compared to siblings, which are important for a tool that generates diagrams. This makes it complete enough for basic understanding but with clear gaps in practical guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the schema description coverage is 100%, so there is no need for parameter details in the description. The baseline for such cases is 4, as the description appropriately focuses on the tool's purpose without redundant parameter information, though it could slightly improve by noting the lack of parameters explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Generate' and the resource 'Mermaid ER diagram of the database schema', making the purpose specific and actionable. However, it does not explicitly differentiate from sibling tools like 'describe_table' or 'list_tables', which might also provide schema information, so it falls short of a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'describe_table' for detailed table info or 'list_tables' for a simple overview. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer usage based on the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_synthetic_dataC

Generate and insert synthetic data into an existing table

ParametersJSON Schema
NameRequiredDescriptionDefault
batch_sizeNoNumber of rows to insert in each batch
column_generatorsNoCustom generators for specific columns (optional)
countNoNumber of rows to generate and insert
tableYesName of the table to insert data into

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'insert' implying a write operation, but lacks details on permissions needed, whether data overwrites existing rows, transaction behavior, or error handling. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action. It wastes no words, though it could be slightly more informative given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after insertion (e.g., success confirmation, row count returned), error conditions, or dependencies on existing table structure, leaving significant gaps for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional meaning beyond implying data generation and insertion, which is already clear from the tool name. Baseline 3 is appropriate when the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Generate and insert synthetic data') and the target resource ('into an existing table'), which distinguishes it from siblings like create_table or query_table. However, it doesn't explicitly differentiate from all siblings (e.g., run_read_query might also involve data manipulation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., table must exist), when not to use it (e.g., for production data), or refer to sibling tools like create_table for table creation first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesB

List all tables in the database

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description must fully disclose behavior. It merely states 'List all tables', which implies a read operation, but omits details on permissions, output format, or performance implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no unnecessary words. It is appropriately front-loaded but lacks any structural enhancement like bullet points that could aid readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description should explain what 'list' returns (e.g., table names, schemas). Without this, an agent may not know how to use the result. Sibling tools like 'describe_table' suggest additional context might be needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description cannot add parameter meaning. Baseline for zero parameters is 4, and the description is sufficient for the parameterless case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all tables in the database. While it distinguishes from 'describe_table' by listing instead of describing, it does not explicitly differentiate from potential siblings like 'query' or 'execute'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (describe_table, execute, query). It is implied that it retrieves table names, but no context on prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

optimize_sqlB

Analyze a SQL query using PROFILE and provide optimization recommendations

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSQL query to analyze and optimize

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool uses 'PROFILE' (implying a profiling mechanism) and provides recommendations, but doesn't specify whether this is a read-only analysis, if it requires specific permissions, what the output format looks like, or any rate limits. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core functionality ('analyze a SQL query') and adds key details ('using PROFILE and provide optimization recommendations') without any wasted words. Every part of the sentence contributes directly to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (analysis with optimization recommendations), no annotations, no output schema, and a single well-documented parameter, the description is adequate but incomplete. It covers the basic purpose but lacks details on behavioral traits, output format, and usage context relative to siblings, which are needed for a more complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'query' well-documented in the schema ('SQL query to analyze and optimize'). The description adds minimal value beyond this, only reiterating that it analyzes and optimizes the query. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('analyze' and 'provide optimization recommendations') and identifies the resource ('SQL query'). It distinguishes from siblings like 'query_table' or 'run_read_query' by focusing on analysis rather than execution. However, it doesn't explicitly differentiate from all siblings (e.g., 'describe_table' might also analyze queries).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('analyze a SQL query... and provide optimization recommendations'), suggesting it's for performance tuning rather than data retrieval or schema operations. However, it lacks explicit guidance on when to use this tool versus alternatives like 'run_read_query' for execution or 'describe_table' for schema analysis, and doesn't mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_tableC

Execute a query on a table

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSQL query to execute

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states the action without disclosing behavioral traits such as whether it's read-only or destructive, permission requirements, rate limits, or response format. It lacks critical context for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste, appropriately sized and front-loaded. It directly states the tool's function without unnecessary elaboration, earning full marks for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (executing queries, potentially with side effects), no annotations, no output schema, and incomplete behavioral disclosure, the description is inadequate. It fails to provide enough context for the agent to understand risks, results, or proper application.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the 'query' parameter as 'SQL query to execute'. The description adds no additional meaning beyond this, such as query syntax examples or constraints, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Execute a query on a table' states a general purpose (verb+resource) but is vague about what type of query (read/write, SQL specifics) and doesn't distinguish from sibling 'run_read_query' or 'optimize_sql'. It minimally meets the requirement but lacks specificity for differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'run_read_query' or 'optimize_sql'. The description implies a general query execution but doesn't specify context, exclusions, or prerequisites, leaving the agent with no usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_read_queryB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSQL SELECT query to execute

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'read-only (SELECT)' which implies non-destructive and safe operations, but fails to address critical aspects like permissions needed, rate limits, error handling, or what the output looks like (e.g., result format, pagination). This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads key information ('Execute a read-only (SELECT) query'). There is no wasted verbiage or redundancy, making it highly concise and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a database query tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., security, performance), output format, and usage guidelines compared to siblings. While concise, it does not provide enough context for an agent to reliably use the tool without additional assumptions or trial-and-error.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'query' parameter clearly documented as 'SQL SELECT query to execute'. The description adds no additional semantic details beyond this, such as syntax examples, supported SQL features, or constraints. Given the high schema coverage, a baseline score of 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Execute') and resource ('read-only (SELECT) query on the database'), making the purpose immediately understandable. It distinguishes from siblings like 'create_table' or 'optimize_sql' by specifying read-only SELECT operations, though it doesn't explicitly contrast with 'query_table' which might have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for executing SELECT queries, but provides no explicit guidance on when to use this tool versus alternatives like 'query_table' or 'optimize_sql'. It mentions 'read-only' which suggests safety, but lacks details on prerequisites, limitations, or specific scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedcreate_table
    • First observeddescribe_table
    • First observedgenerate_er_diagram
    • First observedgenerate_synthetic_data
    • First observedlist_tables
    • First observedoptimize_sql
    • First observedquery_table
    • First observedrun_read_query
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 8 tools

Disambiguation4/5

Most tools have distinct purposes, but query_table and run_read_query overlap significantly as both execute SELECT queries, which could cause confusion. The other tools target clear, separate operations like table management, schema visualization, and query optimization.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, such as create_table, list_tables, and optimize_sql. This predictability makes it easy for agents to understand and navigate the tool set without confusion.

Tool Count5/5

With 8 tools, this server is well-scoped for database operations, covering essential tasks like table management, query execution, and schema analysis. Each tool serves a clear purpose, and the count is neither too sparse nor overwhelming for the domain.

Completeness4/5

The tool set provides strong coverage for core database workflows, including CRUD-like operations (create, list, describe, query) and utilities like optimization and data generation. A minor gap is the lack of update or delete operations, which agents might need to work around, but the surface is largely complete for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • PostgreSQL MCP Server

    cesarvarela
    A
    license
    B
    quality
    D
    maintenance
    A TypeScript-based Model Context Protocol server that enables AI assistants to perform secure database operations on PostgreSQL databases through structured tool interfaces.
    8
    10 npm
    MIT

  • sql-mcp

    NakiriYuuzu
    A
    license
    Not graded
    quality
    C
    maintenance
    A Model Context Protocol server for interacting with MSSQL and PostgreSQL databases, offering tools for schema exploration and SQL execution. It features configurable query modes for safety and supports advanced authentication methods like Windows Auth and SSL.
    9 npm
    MIT

Appeared in Searches