{"id":44190137,"url":"https://github.com/plagness/llm-mcp","last_synced_at":"2026-02-27T01:08:18.692Z","repository":{"id":337034415,"uuid":"1151780234","full_name":"plagness/LLM-MCP","owner":"plagness","description":"LLM routing core + workers + MCP bridge with persistent queue and Telegram telemetry.","archived":false,"fork":false,"pushed_at":"2026-02-07T11:53:17.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-07T20:23:08.996Z","etag":null,"topics":["grpc","llm","mcp","queue","telemetry"],"latest_commit_sha":null,"homepage":"https://github.com/plagness/LLM-MCP","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plagness.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T22:20:16.000Z","updated_at":"2026-02-07T11:58:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/plagness/LLM-MCP","commit_stats":null,"previous_names":["plagness/llm-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/plagness/LLM-MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plagness%2FLLM-MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plagness%2FLLM-MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plagness%2FLLM-MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plagness%2FLLM-MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plagness","download_url":"https://codeload.github.com/plagness/LLM-MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plagness%2FLLM-MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29273139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grpc","llm","mcp","queue","telemetry"],"created_at":"2026-02-09T17:00:42.536Z","updated_at":"2026-02-27T01:08:18.679Z","avatar_url":"https://github.com/plagness.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLM-MCP\n\n[![Version](https://img.shields.io/badge/version-2026.02.12-blue.svg)](VERSION)\n[![Runtime](https://img.shields.io/badge/runtime-go%20%2B%20python%20%2B%20node-green.svg)](compose.yml)\n[![Queue](https://img.shields.io/badge/queue-postgres-orange.svg)](db/init)\n[![Transport](https://img.shields.io/badge/transport-http%20%2B%20grpc-7a3cff.svg)](proto/llm.proto)\n\nЕдиный роутер LLM-запросов и MCP-набор инструментов с устойчивой очередью,\nавтодискавери устройств и телеметрией в Telegram.\n\n[![Quick Start](https://img.shields.io/badge/Quick%20Start-Open-1f6feb?style=for-the-badge)](#-быстрый-старт)\n[![Architecture](https://img.shields.io/badge/Architecture-Open-1f6feb?style=for-the-badge)](#-архитектура)\n[![Changelog](https://img.shields.io/badge/Changelog-Open-1f6feb?style=for-the-badge)](CHANGELOG.md)\n\n## ✨ Возможности\n\n### 🧠 Единый роутинг LLM\n- Локальные задачи через Ollama (`ollama.generate`, `ollama.embed`).\n- Облачные провайдеры: OpenAI, OpenRouter.\n- Единый job lifecycle: submit -\u003e claim -\u003e heartbeat -\u003e complete/fail.\n\n### 🔍 Multi-Ollama Discovery\n- Автодискавери устройств через Tailscale mesh.\n- Multi-port probe (`OLLAMA_PORTS`) — несколько Ollama инстансов на одном хосте.\n- Compose profiles: `ollama` (single), `ollama-multi` (3 инстанса).\n\n### 🗂️ Устойчивая очередь\n- Postgres-очередь с `FOR UPDATE SKIP LOCKED`.\n- Lease-механика: задачи возвращаются в очередь после таймаута воркера.\n- Состояние переживает перезапуск контейнеров.\n\n### 📡 MCP + телеметрия\n- `llmmcp` отдаёт MCP/HTTP bridge к core.\n- `llmtelemetry` публикует статус/прогресс в Telegram.\n- Поддержан route через `telegram-mcp` и direct fallback.\n\n### ☸️ Kubernetes\n- Полный набор K8s манифестов с Kustomize.\n- Ollama Deployment с nodeSelector для привязки к нодам.\n- Готов к развёртыванию на K3s кластере.\n\n## 🧱 Архитектура\n\n```text\n┌──────────────────────┐      ┌──────────────────────┐\n│ Clients / MCP Hosts  │─────▶│ llmmcp (Node.js)     │\n│                      │      │ :3333                │\n└──────────────────────┘      └──────────┬───────────┘\n                                          │ gRPC/HTTP\n                                  ┌───────▼───────────┐\n                                  │ llmcore (Go API)  │\n                                  │ :8080 / :9090     │\n                                  └───────┬───────────┘\n                                          │\n                     ┌────────────────────▼────────────────────┐\n                     │ llmdb (PostgreSQL)                      │\n                     │ jobs, devices, models, telemetry state  │\n                     └──────────────────────────────────────────┘\n                               ▲                   ▲\n                               │                   │\n                        ┌──────┴──────┐      ┌─────┴─────────┐\n                        │ llmworker   │      │ llmtelemetry  │\n                        │ execution   │      │ tg updates    │\n                        └─────────────┘      └───────────────┘\n```\n\n| Компонент | Порт | Назначение |\n|---|---|---|\n| `llmcore` | `8080` | HTTP API для job-операций |\n| `llmcore` | `9090` | внутренний gRPC transport |\n| `llmmcp` | `3333` | MCP/HTTP bridge |\n| `llmdb` | `5435` | очередь и состояние |\n\n## 🚀 Быстрый старт\n\n```bash\ncd llm-mcp\ncp .env.example .env\n\ndocker compose -f compose.yml --env-file .env up -d --build\n```\n\nПроверка:\n\n```bash\ncurl -fsS http://127.0.0.1:8080/health || true\ncurl -fsS http://127.0.0.1:3333/health || true\n```\n\n## 🔌 Минимальные API точки (MVP)\n\n- `POST /v1/jobs` — постановка задачи.\n- `GET /v1/jobs/{id}` — статус.\n- `GET /v1/jobs/{id}/stream` — SSE статус/прогресс.\n- `POST /v1/workers/register|claim|complete|fail|heartbeat` — протокол worker.\n- `POST /v1/discovery/run` — ручной запуск discovery.\n\n## 🔧 Ключевые переменные окружения\n\n- `PORT_DB_LLM=5435`, `PORT_HTTP_LLMCORE=8080`, `PORT_GRPC_LLMCORE=9090`, `PORT_MCP_LLM=3333`.\n- `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `OLLAMA_EMBED_MODEL`.\n- `OPENAI_API_KEY`, `OPENROUTER_API_KEY`.\n- `TELEGRAM_USE_MCP`, `TELEGRAM_MCP_BASE_URL`, `TELEGRAM_MCP_BOT_ID`, `TELEGRAM_MCP_CHAT_ID`.\n- `TELEGRAM_MCP_FALLBACK_DIRECT=1` для отказоустойчивого маршрута телеметрии.\n- Если `TELEGRAM_MCP_BASE_URL` не задан, используется `http://tgapi:8000`; на 1 релиз включён legacy retry к `http://telegram-api:8000`.\n\n## 📚 Документация\n\n- `doc/README.md` — полный справочник по core/worker/mcp/telemetry.\n- `doc/integration_channel_mcp.md` — интеграция с `channel-mcp`.\n- `proto/llm.proto` — внутренний gRPC контракт.\n\n## 📁 Структура\n\n```text\nllm-mcp/\n├── core/           # Go API/router/queue/discovery\n├── worker/         # Python execution adapters\n├── telemetry/      # Telegram telemetry sender\n├── mcp/            # MCP adapter (Node.js)\n├── planner/        # Фоновые процессы (sync, cleanup, benchmarks)\n├── db/init/        # SQL init + миграции\n├── k8s/            # Kubernetes манифесты\n├── proto/          # gRPC contracts\n├── scripts/        # Утилиты (sync моделей, probe)\n├── config/         # Курированные конфиги\n└── compose.yml\n```\n\n## 🧭 Public Git Standards\n\n- Версия хранится в `VERSION` в формате `YYYY.MM.x`.\n- Все изменения описываются в `CHANGELOG.md`.\n- Секреты и токены не попадают в git; используется только `.env.example`.\n- Перед merge обязательны `docker compose config` и минимальный smoke по health/API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplagness%2Fllm-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplagness%2Fllm-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplagness%2Fllm-mcp/lists"}