MCP 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.

Quick Links

• Tools

• Quick Start

• MCP Client Integration

• Key Features

• Configuration

• Build & Run

• Authentication

• Admin Panel

• Agent Tester

• Claude Code Skills

Related MCP server: 1c-buddy-mcp

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

Shops

Recipes

Cart

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.

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/:

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.