mcp-vkusvill: Instructions file for Codex

mcp-vkusvill

Guidance for AI agents working in this repository.

What This Is

An MCP (Model Context Protocol) server built on the fa-mcp-sdk framework. It proxies the official VkusVill MCP API (https://mcp001.vkusvill.ru/mcp) and reformats its raw JSON responses into readable Markdown. Exposed over STDIO or HTTP/SSE transports.

The upstream is itself an MCP server (JSON-RPC 2.0 over Streamable HTTP, anonymous — no auth). This server performs the MCP handshake with it, forwards tools/call, and formats the result.

Tools

All 7 upstream tools are proxied (our tool → upstream tool):

Our tool	Upstream tool	Purpose
search_products	vkusvill_products_search	Text search (price, rating, weight, id, xml_id, url)
get_product_details	vkusvill_product_details	Composition, КБЖУ, allergens, shelf life, manufacturer
get_product_analogs	vkusvill_product_analogs	Similar / replacement products
get_discounts	vkusvill_products_discount	Promo items with old→new price
find_shops	vkusvill_shops	Shops + filter reference (region/city/metro ids)
search_recipes	vkusvill_recipes	Recipes (ingredients, steps, nutrition) + filter reference
create_cart_link	vkusvill_cart_link_create	Build a shareable cart link from {xml_id, quantity}

Tool-level upstream errors arrive as {ok:false, error}; they are surfaced to the LLM via asTextError (not thrown as JSON-RPC errors).

Architecture

src/
├── start.ts                  # Entry point — assembles McpServerData, calls initMcpServer()
├── _types_/
│   ├── common.d.ts           # IToolModule interface
│   └── custom-config.ts      # Custom AppConfig extensions
├── lib/
│   ├── vkusvill-client.ts    # MCP client to the upstream (handshake, retry, SSE/JSON parse, errors)
│   └── format.ts             # Markdown formatters for every payload type (the core value)
├── tools/
│   ├── tools.ts              # Registry + central dispatcher (handleToolCall)
│   ├── search-products.ts    # One file per tool: definition + handler + optional prompt (IToolModule)
│   ├── get-product-details.ts
│   ├── get-product-analogs.ts
│   ├── get-discounts.ts
│   ├── find-shops.ts
│   ├── search-recipes.ts
│   └── create-cart-link.ts
├── prompts/
│   ├── agent-brief.ts        # Short agent description
│   ├── agent-prompt.ts       # Full system prompt
│   └── tool-prompts.ts       # Aggregates per-tool prompts for the tool_prompt MCP prompt
└── api/router.ts             # REST endpoints (tsoa decorators) — health only

config/
├── default.yaml              # Base config (incl. accessPoints.vkusvillMcp — the upstream host)
├── development.yaml / production.yaml   # Env overrides
├── local.yaml                # Local secrets / dev overrides (gitignored)
└── custom-environment-variables.yaml    # Env var → config mapping

tests/mcp/                    # MCP tool tests (STDIO, HTTP, SSE) — test-cases.js is shared