jmd-mcp-sql

Overview Schema Source Related Servers Discussions Admin

read

Query database records and inspect schema using JMD documents. Supports filters, pagination, aggregation, joins, and schema details.

Instructions

Read records or schema via a JMD document (https://github.com/ostermeyer/jmd-spec).

Data (# Label): exact-match lookup.

# Order
id: 42

Query (#? Label): QBE filter; optional pagination, projection, aggregation, and JOIN.

#? Order
status: pending

Schema (#! Label): describe the table — columns, types, modifiers, and any sub-section constraints.

#! Order

Reserved DDL-object labels (dispatch to per-kind shape unless a real table by that name exists):

#! Database              list tables, indexes, triggers, views
#! Index / name: foo     index: table, columns, unique, where
#! Trigger / name: foo   trigger: when, event, condition, body
#! View / name: foo      view: select

QBE operators in #? bodies: = equality (default)

greater than >= greater or equal < less than <= less or equal | alternation (OR), e.g. 'Germany|France' ~ substring (case-insensitive), e.g. '~Corp' ^ regex (implicit full-match anchoring) ! negation, composable with any operator

Frontmatter keys: page-size, page pagination count return only the row count select projection (comma-separated columns) join cross-table JOIN, e.g. 'Table on Col' sum, avg, min, max aggregations with optional 'as alias' group, having, sort GROUP BY / HAVING / ORDER BY

Frontmatter policy: observable tolerance — unknown keys are echoed back as 'ignored-keys: …'. Debug: 'debug: sql, timing, table, plan, filters, resolved, coercions' (composable; 'debug: true' enables all).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`document`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.0Sep 25, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it discloses exact-match vs QBE behavior, frontmatter unknown-key tolerance, debug options, and DDL dispatch rules. It does not explicitly state side-effect safety, but 'read' plus the detailed query semantics make the non-mutating nature clear enough.

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 long, but the content is dense and genuinely needed for a complex DSL. It is well-structured with headers, inline code examples, and tables; the opening line front-loads the core purpose. A small amount of trimming could improve conciseness, but the length is largely justified.

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

Completeness5/5

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

For a single-parameter tool with a complex document format, this description is remarkably complete: it covers the syntax, operators, frontmatter, reserved labels, and debug controls. The presence of an output schema means not explaining return shape is acceptable, and no critical usage detail appears missing.

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

Parameters5/5

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

Schema coverage is 0%, so the description must fully explain the lone 'document' string, and it does so exhaustively: JMD labels, QBE operators, frontmatter keys, aggregation, joins, and debug flags. This transforms an opaque string parameter into a fully specified query language.

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 states a specific verb and resource: 'Read records or schema via a JMD document,' and supports it with concrete syntax examples. This clearly separates it from the write/delete siblings, and the detail makes the tool's purpose unambiguous even without a title.

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 tool's purpose implies it is for reading data or schema, and the sibling names (open, write, delete) provide context. However, the description never explicitly tells an agent when to prefer read over open, nor does it describe exclusion criteria or alternative choices.

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

Deploy Server