Skip to main content
Glama
deenesjakoruzh
k0ry

Shop MCP Server

by k0ry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Shop MCP Server

ローカルMCPサーバー。ECサイトのSQLiteデータベースを分析するためのものです。AIエージェントがMCPツールを呼び出し、サーバーがリクエストを安全なSQL SELECT に変換し、shop.db を直接読み取り、構造化された結果を返します。

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

機能

  • HTTPや専用DBサーバーなしでSQLiteに直接接続。

  • MCPトランスポート stdio。

  • tools/list による query_shop と inspect_database の検出。

  • 説明とツールのJSON Schemaに8つのサンプルタスク。

  • プレーンテキスト、JSON intent、または準備済みの安全な SELECT。

  • すべての分析から cancelled 注文を除外。

  • ページネーションと結果の制限。

  • 多層的な読み取り専用保護。

Related MCP server: Read-Only SQLite Shop Database MCP Server

インストール

Python 3.11以降が必要です。

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

準備済みのデータベースは data/shop.db にあります。150人の顧客がおり、customers.country フィールドは全顧客に入力され、45人の顧客が Germany に属しています。

データベースの再準備

元のデータベースは変更されません。コマンドは新しい作業用コピーを作成し、再現可能な合成値を持つ country TEXT NOT NULL を追加します：

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

分布は customers.id のみに依存するため、再準備しても同じ値になります。国はテストデータであり、顧客の実際の所在地を表すものではありません。

パスの設定

パスは次の順序で決定されます：

  1. SHOP_DB_PATH。

  2. SHOP_MCP_CONFIG または config/shop_mcp.json のJSONファイル。

  3. 作業ディレクトリからの相対パス data/shop.db。

環境変数の例は .env.example にあり、MCPクライアントの設定は config/mcp.example.json にあります。/absolute/path/to/MCPDeveloper をプロジェクトの絶対パスに置き換えてください。

起動

通常、サーバーはMCPクライアントを自身の設定から起動します。プロセスを手動で起動する場合：

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout はMCP JSON-RPC用に予約されています。診断情報はプロトコルストリームに出力されません。

ツール

inspect_database

引数：

{"action": "list_tables"}

または：

{"action": "describe_table", "table": "customers"}

query_shop

引数：

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

tools/list で宣言される例：

  1. データベースにはどのテーブルがあり、各テーブルにはどのフィールドがありますか？

  2. ドイツからの顧客は何人ですか？

  3. 最も顧客が多い国はどこですか？

  4. 最も多く使った顧客は誰ですか？名前、メール、合計金額を返してください。

  5. 販売数量と売上でトップ5の商品を表示してください。

  6. 売上でトップ3のカテゴリを表示してください。

  7. 2025年の売上はいくらでしたか？

  8. 最も多くの注文をした顧客は誰ですか？

構造化されたintentを渡すこともできます：

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

または準備済みのクエリ：

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

ビジネスルール

  • orders.status = 'cancelled' はメトリクスに含まれません。

  • 顧客の支出と年間売上は orders.total_amount で計算されます。

  • 商品とカテゴリの売上は quantity * unit_price で計算されます。

  • 年の間隔は半開区間です：1月1日を含み、翌年の1月1日を含みません。

  • 提供されたデータベースでは、すべての注文が2026年に属するため、2025年の売上は 0 です。

セキュリティ

サーバーはSQLiteを mode=ro で開き、query_only を有効にし、SQLite authorizerを設定し、複数の式、DML、DDL、ATTACH、変更を伴う PRAGMA、拡張機能のロードを禁止し、実行時間を制限します。

SELECT 以外の操作を実行しようとすると、正確な応答が返されます：

Не доступный вариант запроса

SQLiteの内部エラー、スタックトレース、ローカルパスはクライアントに返されません。

検証

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

テストには、MCPサーバーの実際のsubprocess起動、stdio を介した ClientSession 接続、tools/list、両方のツールの呼び出し、分析シナリオ、データベース変更の試みが含まれます。

完全な承認済み仕様は docs/specification.md にあります。

Available Tools

2 tools
inspect_databaseПросмотр структуры базы интернет-магазинаB

Возвращает список таблиц или поля выбранной таблицы. Используйте action=list_tables либо action=describe_table.

NameRequiredDescriptionDefault
tableNoНазвание таблицы для describe_table
actionYesДействие: list_tables или describe_table

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description carries full responsibility for behavioral disclosure. It only states that it returns tables or fields, which is basic. It does not disclose any side effects, permission requirements, error behaviors, or what happens when the table does not exist. For a read-only inspection tool this is relatively benign, but the coverage is minimal.

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 sentence that fully conveys the essential information. It is front-loaded with the primary function and immediately outlines the two actions. No redundancy or filler.

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 that an output schema exists, the return format is likely covered elsewhere. The description is sufficient for a simple schema-inspection tool, but it lacks any mention of error handling or the distinction from query_shop. It is adequate but not comprehensive.

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 already provides 100% coverage: 'action' is described as 'list_tables or describe_table' and 'table' as 'table name for describe_table'. The description repeats this mapping without adding new information, so it meets the baseline but does not exceed it.

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 clearly states the tool's purpose: it returns a list of tables or fields of a selected table. This is a specific verb-resource combination and distinguishes it from the sibling query_shop, which presumably queries data rather than schema. The two modes (list_tables, describe_table) are explicitly mentioned.

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 instructions on how to use the tool (choose action) but does not explain when to use this tool versus the sibling query_shop. It offers no context about typical scenarios, prerequisites, or exclusions. The usage guidance is limited to internal action selection, not selection among alternatives.

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

query_shopЗапрос к базе интернет-магазинаA

Выполняет аналитический запрос к базе интернет-магазина только для чтения. MCP преобразует запрос в безопасный SQL SELECT. Отменённые заказы не учитываются. Примеры: 1) Какие таблицы есть в базе и какие в них поля? 2) Сколько клиентов из Германии? 3) В какой стране больше всего клиентов? 4) Какой клиент потратил больше всего? Верни имя, email и общую сумму. 5) Покажи топ-5 товаров по проданному количеству и выручке. 6) Покажи топ-3 категории по выручке. 7) Какая выручка была в 2025 году? 8) Какой клиент сделал больше всего заказов?

NameRequiredDescriptionDefault
limitNoМаксимальное число строк
offsetNoСмещение для пагинации
requestYesАналитический запрос обычным текстом, JSON intent или SQL SELECT.

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/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 explicitly states the tool is read-only, that MCP converts queries into safe SQL SELECT, and that canceled orders are excluded from results. This is useful and goes beyond minimal. It does not mention error handling or response format, but the core behavior is well disclosed.

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 fairly long because it contains eight examples, but those examples are practical and illustrate valid request formats that are directly relevant to the tool. The purpose statement is front-loaded, and each example adds value, so the length is justified. It is well-structured and not overly verbose.

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 natural-language query tool that has an output schema (indicated by the schema signals), the description covers essential context: what the tool does, how it handles queries, and what data is excluded (canceled orders). It could add more about limitations or error behavior, but given the output schema exists and the description is already thorough, it is largely complete.

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% — every parameter has a clear description. The description itself adds little beyond the schema: it repeats the request examples but does not elaborate on limit or offset semantics, which the schema already covers adequately. The baseline of 3 is appropriate because the schema handles the heavy lifting.

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 clearly states the verb and resource: 'performs a read-only analytical query to the online store database' and explains the MCP converts queries to safe SQL SELECT. It is specific about being read-only and analytical, which differentiates it from a generic database tool and gives a clear sense of its function, though it does not explicitly name the sibling tool.

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?

Usage is implied through a set of concrete examples that show typical analytical questions (e.g., 'which country has most customers?'). However, the description does not explicitly state when to use this tool versus the sibling 'inspect_database', nor does it provide any exclusions or when-not-to-use guidance. It relies on the reader to infer that this is for read-only analytical queries.

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 updatesv0.1.0
    • First observedinspect_database
    • First observedquery_shop
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

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one handles database schema inspection (list tables/describe fields), the other executes analytical queries. There is no overlap in their functional boundaries, making selection unambiguous for an agent.

Naming Consistency5/5

Both tools follow a consistent verb_noun snake_case pattern ('inspect_database', 'query_shop'), using clear, descriptive verbs. Naming style is uniform and predictable.

Tool Count3/5

With only 2 tools, the server feels minimal for a shop analytics domain. While the query tool is versatile, a more granular set (e.g., get_customers, get_orders) might be expected. The count is borderline, not excessive but thin.

Completeness5/5

The tool surface fully covers the stated purpose: schema discovery via inspect_database and arbitrary read-only analytical queries via query_shop. There are no obvious gaps for a read-only analytics server, as the query tool can address any data retrieval need.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Shop Analytics MCP Server

    bogdaamn
    F
    license
    A
    quality
    C
    maintenance
    Enables AI agents to answer analytical questions about an online store's SQLite database through specialized read-only tools, without any risk of modifying the underlying data.
    8
    -

  • Read-Only SQLite Shop Database

    alimbux
    F
    license
    A
    quality
    C
    maintenance
    Enables AI agents to safely inspect and query an SQLite e-commerce database with tools for listing tables, describing schemas, and running read-only SQL queries while blocking destructive operations.
    4
    -

  • 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-mcp

    AndrewKonst
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to read-only analyze a SQLite e-commerce database, exploring schema and running analytical SQL queries over stdio.
    -