Skip to main content
Glama
jdbc-mcp-guard

jdbc-mcp-guard

by lyb-java

db_query

Run read-only SQL across JDBC databases to inspect schemas, indexes, and data; submit up to 20 queries in one batch call to avoid repeated round trips.

Instructions

通用只读 SQL 查询(达梦/MySQL 协议族/PostgreSQL 协议族/SQL Server/Oracle/SQLite/DB2/ClickHouse/Trino/H2,任意库也可用 url+driverClass)。查表结构、字段、索引、数据核对、SQL 排查一律用它,禁止另写 Python/Java 查库脚本。只放行 SELECT/WITH/SHOW/DESC/EXPLAIN/VALUES。先用 db_connections 看连接。【重要】只要这次要查的东西不止一条 SQL,就把它们全部放进 sqls 数组一次提交(≤20 条),不要循环单条调用 sql ——每次单条调用都等于一轮完整的模型往返,是真正的时间大头;SQL 执行本身只要 10-30ms。

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "db_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlNo【仅在确实只有一条 SQL 时用】单条只读 SQL(建议带 LIMIT;多语句会被拒绝)
sqlsNo【首选】批量只读 SQL(≤20 条):一次建连顺序执行,每条独立过只读守卫,单条失败只影响该块。要查 2 条以上就一律用这个。
formatNotable=Markdown 表格;json=JSON 数组table
maxRowsNo返回行数上限,默认 200(驱动层截断,两种格式都合法)
timeoutNo语句超时秒数,默认由驱动决定
connectionNo连接名,默认 default(见 db_connections)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full behavioral burden, and it does disclose that the tool is read-only, that an exact statement whitelist is enforced, and that each SQL is checked independently against that whitelist when batched. It does not discuss authentication or permission requirements, connection pooling, or how results are truncated when more rows exist than maxRows allows, and it leaves the remaining behavioral details to the schema.

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 definition is front-loaded with the capability statement, then the whitelist, then the prerequisite, then the batching directive highlighted with 【重要】. The batching justification takes several clauses and partly duplicates what the schema says about the sqls parameter, which is slightly redundant, but the redundant clauses carry real routing value.

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

Completeness4/5

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

For a 6-parameter tool with no output schema and no annotations, the description covers the read-only guarantee, the statement whitelist, the batch-versus-single decision, the cost rationale, and the connection prerequisite. It omits authentication and permission expectations and does not discuss how to paginate beyond maxRows, though the schema covers the truncation mechanism, leaving only minor gaps.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning that the schema cannot easily convey: why sqls is preferred over sql, the model-round-trip cost model (10-30ms execution versus a full round trip), and the rule that multiple statements are rejected in sql. This directly shapes parameter choice rather than restating field definitions.

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

Purpose5/5

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

The description names a concrete verb (query) and resource (database), enumerates the supported engines and the URL+driverClass fallback, and specifies the scope of operations (table structure, columns, indexes, data verification, SQL troubleshooting). It also states the operation is read-only, so an agent can tell it apart from a sibling such as db_connections, which is explicitly named as the prerequisite step.

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

Usage Guidelines4/5

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

The description gives explicit when-to-use guidance ('查表结构、字段、索引、数据核对、SQL 排查一律用它'), a hard exclusion ('禁止另写 Python/Java 查库脚本'), a prerequisite ('先用 db_connections 看连接'), and a routing rule between the sql and sqls parameters. It does not name the sibling write tool (db_execute) as the alternative for non-SELECT work, but it does state that only SELECT/WITH/SHOW/DESC/EXPLAIN/VALUES are permitted, which is enough for an agent to infer that writes belong elsewhere.

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