VKUSVILL

MCP server for VkusVill. It proxies the official VkusVill MCP API and reformats its raw JSON into readable Markdown, letting AI agents search products, look up composition and nutrition, find shops, browse recipes, and build shareable cart links.

License Node.js TypeScript MCP fa-mcp-sdk

Quick Links

• Tools
• Quick Start
• MCP Client Integration
• Key Features
• Configuration
• Build & Run
• Authentication
• Admin Panel
• Agent Tester
• Claude Code Skills

Overview

This server sits between an AI agent and the official VkusVill MCP API (https://mcp001.vkusvill.ru/mcp). The upstream is itself an MCP server (JSON-RPC 2.0 over Streamable HTTP, anonymous — no credentials). This proxy performs the MCP handshake with it, forwards tools/call requests, and converts the raw JSON responses into Markdown that is easy for an LLM to read and present. It exposes 7 tools over HTTP/SSE or STDIO. Use it when you want VkusVill grocery data inside an MCP-capable assistant.

Tools (7)

All tools wrap one upstream VkusVill tool each and return formatted Markdown. Tool-level upstream failures are surfaced to the LLM in-conversation (not thrown as protocol errors).

Products

Tool	Description
search_products	Text search for products (price, rating, weight, id, xml_id, url).
get_product_details	Composition, КБЖУ (nutrition), allergens, shelf life, manufacturer.
get_product_analogs	Similar / replacement products for a given product id.
get_discounts	Promo items with old → new price.

Shops

Tool	Description
find_shops	Shops (address, hours, phone, features) plus region/city/metro filter reference.

Recipes

Tool	Description
search_recipes	Recipes (ingredients, steps, nutrition) plus filter reference.

Cart

Tool	Description
create_cart_link	Build a shareable cart link from {xml_id, quantity} items.

Project-specific details on the proxy and formatting: Upstream Proxy.

Quick Start

npm install
npm run build
npm start                       # HTTP mode, port 9048

For STDIO mode (Claude Desktop direct spawn):

node dist/src/start.js stdio

Verify the HTTP server is up:

curl http://localhost:9048/health

No configuration is required to talk to the upstream — it is anonymous. A config/local.yaml (gitignored) is only needed when you enable MCP-server authentication or the Agent Tester LLM.

MCP Client Integration

By default the MCP server's own authentication is off (webServer.auth.enabled: false), so no auth header is needed. If you enable it, pass a JWT via the standard Authorization: Bearer header (generate one with the /gen-jwt skill or node scripts/generate-jwt.js).

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "mcp-vkusvill": {
      "type": "http",
      "url": "http[s]://<host[:port]>/mcp"
    }
  }
}

When server auth is enabled, add a header:

"headers": {
  "Authorization": "Bearer <jwt-token>"
}

Claude Desktop

Add to claude_desktop_config.json.

Option 1 — STDIO (local build, direct spawn):

{
  "mcpServers": {
    "mcp-vkusvill": {
      "command": "node",
      "args": ["<path>/mcp-vkusvill/dist/src/start.js", "stdio"],
      "env": {}
    }
  }
}

Option 2 — HTTP (remote server via mcp-remote):

{
  "mcpServers": {
    "mcp-vkusvill": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http[s]://<host[:port]>/mcp",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}

Qwen Code

Add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "mcp-vkusvill": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http[s]://<host[:port]>/mcp",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.mcp-vkusvill]
url = "http[s]://<host[:port]>/mcp"

When server auth is enabled and you connect via mcp-remote, add --header "Authorization:Bearer <jwt-token>" to the args — with no space after the :.

Key Features

• VkusVill MCP proxy — performs the upstream MCP handshake, forwards tools/call, retries once on transient failures with session reset.
• Markdown formatting — every payload (products, nutrition, shops, recipes, cart) is rendered as readable Markdown in src/lib/format.ts.
• Graceful tool errors — upstream business errors reach the LLM as in-conversation text, not as protocol crashes.
• Dual transport — HTTP/SSE for web integrations, STDIO for direct Claude Desktop spawn.
• Admin Panel (/admin) — JWT / permanent-token generation and inspection UI.
• Agent Tester (/agent-tester) — built-in chat UI and headless API to drive the tools via an LLM.
• MCP prompts & resources — agent_brief, agent_prompt, and tool_prompt ship with the server.

Transports

• HTTP — web integrations. Endpoints:
  • /mcp — MCP protocol (JSON-RPC 2.0)
  • /health — health check
  • /docs — Swagger UI (REST, tsoa-generated)
  • /admin — token generator UI
  • /agent-tester — Agent Tester web UI
  • / — home page with server status
• STDIO — for Claude Desktop direct spawn (no network).

Port is set in config/default.yaml → webServer.port (default 9048).

Configuration Basics

Priority: environment variables > config/local.yaml > config/{NODE_ENV}.yaml > config/default.yaml.

Key	Description	Default
accessPoints.vkusvillMcp.host	Upstream VkusVill MCP URL	https://mcp001.vkusvill.ru/mcp
webServer.port	HTTP server port	9048
webServer.host	Bind address	127.0.0.1
webServer.auth.enabled	MCP server authorization on/off	false
mcp.transportType	Transport (http / stdio)	http
mcp.tools.answerAs	Response format (text / structuredContent)	text
adminPanel.enabled	Admin panel UI on/off	true
agentTester.enabled	Agent Tester UI on/off	true

Full reference: Configuration.

Build & Run

npm run build        # tsc
npm start            # HTTP server
node dist/src/start.js stdio   # STDIO mode

Quality and tests:

npm run lint:fix       # oxlint --fix
npm run format:fix     # oxfmt
npm run typecheck      # tsc --noEmit
npm run test:mcp       # STDIO transport tests
npm run test:mcp-http  # HTTP transport tests
npm run test:mcp-sse   # SSE transport tests

Environment variables:

• NODE_ENV — picks the config/{NODE_ENV}.yaml overlay.

Authentication

The upstream VkusVill API is anonymous, so the proxy needs no credentials to fetch data. The server's own authentication (who may call this MCP server) is configured under webServer.auth and is disabled by default. When enabled it supports permanent server tokens, JWT (Bearer), and Basic. Tokens are minted via the Admin Panel, the /gen-jwt skill, or node scripts/generate-jwt.js.

Methods, JWT modes, and the admin-panel JWT claim requirement: Authentication.

Admin Panel

A web UI at /admin generates and inspects tokens. It is enabled by default with authType: [permanentServerTokens, jwtToken]. When JWT auth is used, the panel only accepts a JWT whose payload contains allow: 'gen-token'. Setup and usage: Admin Panel.

Agent Tester

A built-in chat UI at /agent-tester and a headless API at /agent-tester/api/chat/test drive the tools through an LLM. Requires an OpenAI-compatible key in agentTester.openAi; run npm run check-llm to validate the key first. Full guide: Testing.

Claude Code Skills

The project ships with custom skills in .claude/skills/:

Command	Description
/gen-jwt	Generate JWT tokens for MCP server authentication.
/upgrade-sdk	Upgrade the fa-mcp-sdk dependency end-to-end (analyze, plan, apply).
/change-log	Generate a Keep a Changelog entry between versions.
/feature-prompt-generator	Turn a feature description into a self-sufficient prompt for an AI CLI.
/readme-generator	Generate structured README.md + satellite readme-docs/*.md.
/mcp-app-create	Scaffold a new MCP App (interactive UI: tool + HTML resource).
/mcp-app-add-to-server	Enrich existing MCP server tools with interactive UIs.
/create-mcp-wizard	End-to-end MCP server implementation from brief to live repo.

Details, launch modes, and examples: SKILLS.

The skills can also be shared with OpenAI Codex via .agents/skills/. Run npm run agents:link once to create the link (npm run agents:link:status / npm run agents:link:remove to inspect or undo it).

Stack

• Framework: fa-mcp-sdk
• Transport: MCP (STDIO, HTTP, SSE)
• Language: TypeScript (ESM, Node ≥ 20)
• MCP SDK: @modelcontextprotocol/sdk
• Tooling: oxlint, oxfmt, jest

License

MIT © Viacheslav Makarov. See LICENSE.