MCP VKUSVILL

MCP server for integration with VkusVill

Install & Run

Quick Start

# Install
npm install

# Configure (copy config/local.yaml from config/_local.yaml)
# Add database credentials

# Build
npm run build

# Run (STDIO mode for Claude Desktop)
npm start

Test Run

# Unit tests
npm test

# MCP protocol tests
npm run test:mcp        # STDIO mode
npm run test:mcp-http   # HTTP mode
npm run test:mcp-simple # Simple test

Dual Transport System

STDIO Mode (default for Claude Desktop):

• Direct stdin/stdout communication

• Optimal for Claude Desktop integration

• No network ports required

HTTP Mode (web integration):

• HTTP server with Server-Sent Events (SSE)

• Home page with server status at http://localhost:9048/

• Health check endpoint at /health

• Direct JSON-RPC 2.0 endpoint at /mcp

Related MCP server: vk-ads-mcp

Features

MCP Tools

MCP Prompts

agent_brief

Brief description of agent capabilities for agent selection.

agent_prompt

Complete prompt with instructions.

MCP Resources

staff://agent/brief

Same as agent_brief prompt. MIME: text/plain

staff://agent/prompt

Same as agent_prompt prompt. MIME: text/plain

2. Configuration

Option A: Configuration File

Option B: Environment Variables

Usage with AI CLIs

The server exposes an HTTP MCP endpoint at http[s]://<host[:port]>/mcp. Authentication (when enabled in config/default.yaml → webServer.auth) is passed via the standard Authorization header — most commonly a JWT Bearer token generated by the /gen-jwt skill or by node scripts/generate-jwt.js.

With Claude Code

Add to ~\.claude.json:

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

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

With Qwen Code

Add to ~\.qwen\settings.json:

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

For STDIO transport (local Claude Desktop integration without an HTTP server), run node <path-to-project>/dist/src/start.js stdio — see CLAUDE.md for details.

HTTP Mode Endpoints

• / - Home page

• /health - Health check

• /sse - Server-Sent Events

• /mcp - JSON-RPC 2.0

Claude Code Skills

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

Details, launch modes, and examples: SKILLS

Sharing Skills with OpenAI Codex

The skills in .claude/skills/ can also be used from OpenAI Codex — Codex officially reads project Skills from .agents/skills/ and supports symlinked skill folders. Run the bundled helper once to create the link (junction on Windows, relative symlink on macOS/Linux):

npm run agents:link          # create .agents/skills -> .claude/skills
npm run agents:link:status   # inspect current link state
npm run agents:link:remove   # remove the link

Only skills are linked. Other Claude Code entities (.claude/agents/, .claude/commands/, hooks, MCP config) use formats incompatible with Codex (TOML agents in .codex/agents/, MCP servers in .codex/config.toml) and must be configured separately. For project guidance, this template already keeps a single AGENTS.md and imports it from CLAUDE.md via @AGENTS.md, so the same instructions feed both tools.

Security

Admin panel JWT requirement

When adminPanel.authType includes jwtToken, the admin panel (/admin) accepts a JWT only if its payload contains allow: 'gen-token'. JWTs without this claim are rejected with 401 — this blocks short-lived tokens issued for other purposes (for example, the 5-minute JWT auto-generated by the Agent Tester page and written into its Authorization header) from being replayed to mint arbitrary long-lived tokens.

permanentServerTokens and basic admin auth are unaffected by this check.

Generate an admin-capable JWT:

node scripts/generate-jwt.js -u admin -ttl 30d -p "allow=gen-token"

Public Contract

The runtime contract surfaced by this server (transports, HTTP endpoints, JWT claims, tool / prompt / resource shape, error mapping, headers, semver and deprecation policy) is documented in FA-MCP-SDK-DOC/11-public-contract.md.

Tools, prompts and resources exposed by this project are listed in the table below — update this section whenever you add, rename, or remove an entry.

Tools

Prompts

Resources

Versioning policy

This project follows the semver contract documented in FA-MCP-SDK-DOC/11-public-contract.md. Mark every MAJOR change with [BREAKING] in CHANGELOG.md.