mcp-shop-server

Servidor MCP que da al agente de IA acceso de solo lectura a la base de datos SQLite de una tienda en línea (customers, products, orders, order_items). A través de él, el agente responde a preguntas analíticas sobre los datos: estructura de la base, agregados por clientes, productos, categorías e ingresos. El transporte es stdio.

La escritura en la base es imposible por diseño: tres capas de protección independientes: conexión mode=ro, validación de la consulta antes de la ejecución (solo SELECT / WITH ... SELECT) y sqlite3-authorizer.

Mediciones, pruebas y desviaciones del pliego de condiciones — en REPORT.md.

Uso

1. Clonar

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

En el repositorio ya está shop.db (150 clientes, 50 productos, 750 pedidos, 1900 posiciones).

2. Instalar dependencias

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

Sin uv — lo mismo con las herramientas estándar:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Se requiere Python 3.11+. Dependencias: mcp (SDK oficial de MCP) y pytest para las pruebas; el trabajo con la base — con sqlite3 de la biblioteca estándar.

3. Configurar en el agente

Forma mínima de configuración:

{
  "command": "python",
  "args": ["/absolute/path/to/mcp-shop-server/server.py"]
}

Ejemplo funcional para un cliente con el bloque mcpServers (Claude Desktop, Cursor y compatibles):

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/mcp-shop-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-shop-server/server.py"],
      "env": {
        "MCP_SHOP_DB": "/absolute/path/to/mcp-shop-server/shop.db"
      }
    }
  }
}

Para Claude Code basta un solo comando:

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DB es opcional: si la variable no está definida, el servidor toma shop.db junto a server.py. Indíquela si la base está en otro lugar. Es mejor indicar el intérprete desde .venv — de lo contrario, el python del sistema puede no encontrar el paquete mcp.

4. Ejecución

El servidor lo inicia el agente; manualmente rara vez se necesita:

.venv/bin/python server.py

El proceso espera en silencio JSON-RPC en stdin; el diagnóstico va a stderr, stdout está ocupado por el protocolo MCP.

5. Verificación y preguntas al agente

.venv/bin/python -m pytest -q

Tras la conexión, el agente ve tres herramientas. Las preguntas se formulan en lenguaje natural.

Ocho tareas del texto de la tarea — son las que conviene ejecutar para la verificación:

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ Las tareas 2, 3 y 7 en la base suministrada no tienen solución, y esto es esperable. En customers no hay columna de país — los 150 clientes tienen teléfonos rusos; los 750 pedidos están fechados en 2026, no hay datos de 2025.

En este caso, el servidor no inventa datos: informa que ese campo no existe en el esquema y enumera las columnas existentes. Nada está codificado — el esquema se lee de la base, por lo que en otra base donde country exista, las mismas preguntas funcionarán con normalidad.

Además se verifican preguntas que la base cubre por completo: top-5 clientes por importe de pedidos, ingresos por categorías, distribución de pedidos por estados, ticket medio, existencias de productos.

Verificación de la protección contra escritura. Ante «Delete all cancelled orders» el agente recibe una negativa clara, no un error: el servidor solo funciona en lectura, los 102 pedidos cancelados permanecen en su lugar.

Herramientas

La salida está limitada: por defecto 100 filas, máximo 1000. Al truncar, la respuesta informa cuántas filas se devolvieron, cuántas se encontraron en total y con qué offset seguir leyendo.

Si el campo solicitado no existe en la base (por ejemplo, el país del cliente), el servidor lo dice honestamente y enumera las columnas existentes — no inventa campos inexistentes.

Related MCP server: Shop Analytics MCP Server

Cómo está hecho

El proyecto se generó con un solo prompt — el archivo SPEC-mcp-shop.md, enviado al agente completo, sin aclaraciones posteriores.

Internamente, el agente trabajó en un ciclo según la habilidad repo-task-proof-loop (Denis Shiryaev, Apache-2.0): congelación de la especificación → construcción → empaquetado de pruebas → verificación con una sesión nueva → corrección mínima → verificación de nuevo, hasta el veredicto PASS.

Las pruebas de la ejecución están en el repositorio, en .agent/tasks/mcp-shop-server/:

• spec.md — especificación congelada con criterios de aceptación AC1…AC17;

• evidence.md / evidence.json — para cada criterio, veredicto y prueba concreta;

• verdict.json — resultado de la verificación independiente con una sesión nueva;

• problems.md — discrepancias encontradas por el verificador;

• raw/ — registros brutos de las ejecuciones: pruebas, sesión MCP en vivo, verificación de la limpieza de stdout.

No se verifica el código fuente, sino el comportamiento del servidor con un agente real: el harness raw/mcp_session_check.py levanta server.py por stdio con un cliente MCP real, llama a todas las herramientas, ejecuta las ocho tareas analíticas, recibe la negativa ante el borrado y comprueba que stdout contenga solo marcos JSON-RPC.

La propia habilidad de desarrollo está localmente en .claude/skills/ y no se commitea al repositorio — es código de terceros.

Decisiones tomadas sobre ambigüedades del pliego