@vglu/tele-gpu-pilot-mcp

MCP server exposing self-hosted tele-gpu-pilot pod inference (chat / image / status) to Claude Code, Cursor, и любому MCP-compatible клиенту через stdio.

Single-tenant: тебе нужен access token к чьему-то pod'у. Если у тебя нет — этот package бесполезен. Это не публичный inference SaaS, это transport-mechanism к pod'у Виталия.

Tools

| Tool | Что делает | Когда вызывать | |---|---|---| | pod_image_generate | POST /v1/images/generations → Flux schnell. Optional save_path пишет PNG на disk; без него — inline base64 content (для Zed/Desktop/web где рендер работает). | «нарисуй / сгенерируй картинку» | | pod_chat | POST /v1/chat/completions → text. Models: gemma-4-26b / gemma-4-e4b / qwen-2.5-32b-coder / qwen3-4b | Tech-writer drafts, rephrase, classification — где cloud overkill | | pod_status | GET /v1/models — pod alive? какие модели в whitelist'е токена | Debug / discovery |

Install + setup

1. Получи token

Создаёт владелец pod'а — на pod'е через LiteLLM admin API:

ssh <pod-admin>@vps "MASTER=\$(grep LITELLM_MASTER_KEY pod-runtime/.env | cut -d= -f2)
curl -X POST http://127.0.0.1:8000/key/generate \
  -H \"Authorization: Bearer \$MASTER\" \
  -H 'Content-Type: application/json' \
  -d '{\"key_alias\":\"<your-name>\",\"models\":[\"gemma-4-26b\",\"flux-schnell\"],\"rpm_limit\":60,\"max_budget\":5}'"

Token приходит в response поле key (sk-...).

2. Положи token куда-нибудь

Server ищет TELE_GPU_PILOT_TOKEN в порядке приоритета:

1. process.env — задано в shell или в env: {} блоке .mcp.json
2. .env в repo — local dev (cwd-based + relative к dist/)
3. ~/.tele-gpu-pilot.env — global home-dir fallback (рекомендуется для npx-installed)
4. ~/.config/tele-gpu-pilot/.env — XDG-style alternative

Простейший способ — global config (работает из любого проекта):

# Linux/Mac
cat > ~/.tele-gpu-pilot.env << EOF
TELE_GPU_PILOT_TOKEN=sk-yourtoken
TELE_GPU_PILOT_URL=https://tele-gpu-pilot.sims-service.com/v1
EOF
chmod 600 ~/.tele-gpu-pilot.env

# Windows PowerShell
@'
TELE_GPU_PILOT_TOKEN=sk-yourtoken
TELE_GPU_PILOT_URL=https://tele-gpu-pilot.sims-service.com/v1
'@ | Set-Content -Path $HOME\.tele-gpu-pilot.env

3. Register в Claude Code

.mcp.json в repo root (любого проекта, где хочешь использовать pod):

{
  "mcpServers": {
    "tele-gpu-pilot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vglu/tele-gpu-pilot-mcp"]
    }
  }
}

npx -y скачает и закеширует package при первом запуске (~10s), потом fast.

После рестарта Claude Code:

• /mcp → должен показать tele-gpu-pilot · connected · 3 tools
• В чате: «сгенерируй картинку: ... и сохрани как cat.png»

4. Register в Cursor

Cursor → Settings → MCP → Add server:

Type:    stdio
Command: npx
Args:    -y @vglu/tele-gpu-pilot-mcp

Или Cursor подхватит .mcp.json если в Settings включено project MCP discovery.

Tool examples

pod_image_generate

{
  "prompt": "a tabby cat coding on a laptop, warm sunset",
  "size": "1024x1024",
  "n": 1,
  "model": "flux-schnell",
  "save_path": "out.png"
}

• С save_path → PNG записывается на disk, tool возвращает абсолютный путь в structuredContent.saved_paths. Использовать в terminal Claude Code (host не рендерит inline images).
• Без save_path → inline base64 content (для Zed Agent Panel / Claude Desktop / claude.ai).
• N>1 + save_path → суффиксы _0, _1, … перед .ext.

pod_chat

{
  "prompt": "Rephrase more concisely: ...",
  "system": "You are a technical writer. Output only the rephrased text.",
  "model": "gemma-4-26b",
  "max_tokens": 500,
  "temperature": 0.3
}

pod_status

{} → alive flag + список моделей per current token whitelist.

Error semantics

Tool returns isError: true + текстовое сообщение (не throw'ит) при:

• auth_error 401/403 — token неверный / model не в whitelist'е
• rate_limit 429 — RPM или daily budget exceeded
• pod_offline 5xx / network — pod sleeping. Owner делает /wake в Telegram бота.
• client_error 4xx — invalid params

Это даёт MCP-host'у возможность cascade'нуться на cloud-модель.

Timeouts

• Image-gen: 240s (cold-start gemma + flux load до 60s, потом ~6s/image)
• Chat: 120s
• Status: 10s

Logs

В stderr (stdout зарезервирован для MCP JSON-RPC frames). Debug:

npx -y @vglu/tele-gpu-pilot-mcp 2>/tmp/mcp.log
# Открой /tmp/mcp.log в parallel

Что внутри

• @modelcontextprotocol/sdk — официальный TS SDK
• zod — input/output schemas
• 4 tools (image, chat, status) + 1 client helper + entry
• ~530 LoC, без runtime deps кроме SDK + zod

Source

github.com/vglu/tele-gpu-pilot/tree/master/tools/mcp. MCP server — часть проекта tele-gpu-pilot (Telegram bot + RunPod scheduler + pod-runtime stack). Сам package distributable отдельно.

License — MIT.