Skip to main content
Glama
melixetian

Shop Database MCP Server

by melixetian
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Shop Database MCP Server

This local stdio MCP server lets an AI agent inspect and analyze shop.db. It is read-only: SQLite is opened read-only, query_only is enabled, and the server rejects anything except one SELECT or WITH ... SELECT query.

Prerequisites

Node.js 20 or newer and the supplied SQLite database.

Related MCP server: shop-database-mcp

Install

npm install

Configure

SHOP_DB_PATH is optional. If set, a relative value is resolved from the process working directory; an absolute value is used directly. Otherwise the server finds shop.db relative to its compiled module, including when launched outside the project directory. See .env.example; it is not loaded automatically.

Build

npm run build

Run manually

npm start

A stdio server normally appears idle because it waits for MCP messages.

Connect to Codex IDE extension and CLI

In the IDE extension: Gear menu → MCP servers → Add server → STDIO. Set command, arguments, and environment from config/codex.config.toml.example, save, and restart the extension.

For a project-scoped setup, copy that example to .codex/config.toml and replace every /ABSOLUTE/PATH/TO/PROJECT placeholder. Codex CLI and the IDE extension share Codex MCP configuration. Do not commit the active configuration file.

Available tools

inspect_database takes no parameters. Use it before querying or when uncertain; it returns tables, columns, primary/foreign keys, relationships, and row counts.

query_database accepts sql (required), params (positional string, finite number, boolean, or null values), limit (1–200; default 100), and offset (default 0). Use ? placeholders; joins and aggregates work. It accepts exactly one read-only SELECT or WITH ... SELECT. Inspect schema before assuming columns, date formats, prices, or statuses. Results contain columns, rows, rowCount, limit, offset, and hasMore; request another page with a new offset.

{"sql":"SELECT country, COUNT(*) AS customer_count FROM customers GROUP BY country ORDER BY customer_count DESC","params":[],"limit":100,"offset":0}

Test

npm test

Tests create temporary fixture databases and never modify shop.db.

Safety design and troubleshooting

Safety layers are read-only file access, SQLite query_only, conservative token-aware validation that ignores comments/strings/quoted identifiers, a single-statement rule, and server-side pagination. Tool errors are concise and do not expose stack traces or local paths.

If startup fails, verify SHOP_DB_PATH names an existing regular SQLite file. If a query fails, call inspect_database, use ? parameters, and verify names and relationships.

Available Tools

2 tools
inspect_databaseA
Read-only

Use before your first query or whenever the schema is uncertain. Returns tables, columns, keys, relationships, and row counts.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
tablesYes

TDQS

A4.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds behavioral context by describing what is returned (tables, columns, keys, relationships, row counts), and its 'returns...' phrasing makes clear this is a read/inspection operation. There is room for more detail about potential performance cost or staleness, but the description is adequate given the 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?

Two sentences, front-loaded with the usage trigger, and every clause earns its place. The list of returned schema elements is efficient and informative without padding.

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 zero-parameter inspection tool with readOnly annotations and an output schema, the description is complete. It tells the agent when to use it and what to expect in return, and no additional information is needed to invoke it correctly.

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 zero parameters, so there is nothing for the description to clarify about inputs. A baseline of 4 is appropriate for a no-parameter tool since parameter-semantics burden is eliminated.

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 ('inspect') and resource ('database'), and its purpose is unmistakable: return schema metadata. It also positions itself as a pre-query reconnaissance step, which distinguishes it from the sibling query_database.

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

Usage Guidelines5/5

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

Explicitly says 'Use before your first query or whenever the schema is uncertain,' giving clear conditions for use. This implicitly excludes using it for data retrieval, which is handled by query_database. The guidance is concrete and actionable.

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

query_databaseA
Read-only

Execute one parameterized read-only SELECT or WITH ... SELECT statement. Use ? placeholders and params for dynamic values. Joins and aggregate queries are supported; schema and data changes are forbidden. Results are paginated: use offset for the next page when hasMore is true. Inspect the schema instead of guessing column names, date formats, price fields, or order status semantics.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes
limitNo
offsetNo
paramsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYes
limitYes
offsetYes
columnsYes
hasMoreYes
rowCountYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces these by stating schema and data changes are forbidden. It adds behavioral detail beyond annotations by explaining pagination (use offset when hasMore is true) and requiring ? placeholders with params. This exceeds the baseline given 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.

Conciseness5/5

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

The description is exceptionally concise and well-structured, front-loading the core purpose, then covering parameter usage, pagination, and schema-inspection advice in just a few sentences. Every sentence adds value with no redundancy or fluff.

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?

Given the output schema handles return values and annotations cover safety, the description is largely complete for a query tool. It covers read-only behavior, parameterization, pagination, and best-practice schema inspection. The main gap is the lack of explicit linkage to the sibling inspect_database tool, which would strengthen the workflow guidance.

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?

With 0% schema description coverage, the description needs to explain parameters, but it only partially does so. It covers sql implicitly, explains params with ? placeholders, and clarifies offset for pagination, but does not describe the limit parameter or its constraints. This partial compensation earns a mid-range score.

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 executes a read-only SELECT or WITH ... SELECT statement, specifying a precise verb and resource. It distinguishes itself as a query tool but does not explicitly differentiate from the sibling inspect_database, so it misses the top score for sibling differentiation.

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 by instructing to inspect the schema before guessing column names or semantics, which suggests a workflow involving schema inspection. However, it does not explicitly state when to use this tool versus alternatives, nor does it name inspect_database as the schema-inspection tool. The guidance is implied rather than explicit.

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. 2 tool updatesv1.0.0
    • First observedinspect_database
    • First observedquery_database
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

inspect_database handles schema metadata while query_database executes read-only SQL queries. There is no functional overlap or ambiguity between the two tools.

Naming Consistency5/5

Both tools follow the same lower_snake_case verb_noun pattern: inspect_database and query_database. The naming is consistent, predictable, and clearly reflects each tool's purpose.

Tool Count4/5

Two tools is lean but well-suited to the server's read-only database purpose: inspect the schema, then query the data. Each tool is essential, and the narrow scope justifies the small count.

Completeness5/5

For a read-only database server, inspect_database plus query_database covers the complete workflow of schema discovery and arbitrary SELECT queries with pagination. Write operations are explicitly out of scope, so their absence is not a gap.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • db-mcp

    denezhkinia
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to safely interact with a SQLite shop database through schema discovery, read-only SQL queries, and pre-built analytics reports like top customers, top products, and revenue summaries.
    6
    47 npm
    MIT

  • shop-database-mcp

    ndovnar
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only exploration and analysis of an included SQLite shop database through tools for listing tables, describing schemas, and running SQL queries.
    -

  • shop-db

    aleksei-antipin
    F
    license
    A
    quality
    C
    maintenance
    Enables AI agents to read-only query an online store's SQLite database, listing tables, inspecting schemas, and running SELECT queries over customers, products, orders, and order items.
    3
    -

  • shop-db MCP Server

    bulychauPI
    F
    license
    A
    quality
    B
    maintenance
    Gives AI agents read-only analytical access to an e-commerce SQLite database (customers, orders, order_items, products) via SQL queries, table listing, and schema inspection.
    3
    -