| name | mcphub-explained |
| description | Explains mcphub architecture in plain Russian: how supervisor + daemon wrappers + MCP servers (serena, gopls-mcp, mcp-language-server) fit together; what hub-routing solves; key files; common operator-visible failures. Load when working on mcphub or onboarding a new contributor. |
mcphub на пальцах
Этот skill — учебник для оператора и быстрый брифинг для агента который только что попал в репозиторий mcp-local-hub. Содержит plain Russian объяснения архитектуры + glossary + file:line указатели на самые часто читаемые места кода.
Сохранение в docs/skills/ (а не в .claude/skills/) — преднамеренно: учебник версионируется вместе с кодом, чтобы при изменении архитектуры обновлялись оба синхронно. Loadable через файловый Read, не через runtime skill resolver.
Когда читать этот skill
- Только что попал в репозиторий, нужен высокоуровневый обзор за 10 минут
- Оператор спрашивает "что такое mcphub" / "как это работает" / "почему 200 процессов"
- Расследуется баг в supervisor lifecycle, респавне, или hub-routing — нужен ментальный мап перед погружением в код
- Просматриваешь план
docs/superpowers/plans/2026-05-20-serena-supervisor-unified.md и нужен глоссарий
1. Что такое MCP-сервер
Аналогия: AI-ассистент (claude / codex / cursor) умеет говорить, но не умеет читать файлы или запускать команды. MCP-сервер — это маленькая программа-переводчик. Помощник говорит "хочу увидеть файл X" — MCP-сервер идёт, читает файл, возвращает содержимое.
Каждый MCP-сервер — это отдельный процесс. Когда AI-помощник запускается, он спавнит нужные MCP-серверы и общается с ними через stdin/stdout или HTTP.
Известные MCP-серверы в этом репо: memory, time, wolfram, serena (умная работа с кодом), gopls-mcp (Go LSP), mcp-language-server (LSP-обёртка для других языков), gdb, lldb, godbolt, paper-search-mcp, perftools, sequential-thinking.
2. Зачем mcphub существует
Проблема без mcphub: 7 AI-ассистентов × ~14 MCP-серверов каждый = ~100 процессов. Каждый ест RAM/CPU/диск. На Windows: Task Manager показывает сотню node.exe, python.exe, mcphub.exe.
С mcphub: ассистенты вместо собственных копий MCP-серверов подключаются к ОДНОМУ экземпляру через mcphub. Hub держит одну memory, одну serena, одну mcp-language-server per язык — все 7 ассистентов с ними общаются.
Результат: ~18 процессов вместо ~100. Меньше памяти, меньше CPU, меньше хаоса.
Это и есть смысл mcphub: сокращение копий MCP-серверов через shared-hub архитектуру. Запись от 2026-04-17: memory/project_mcphub_process_tails_motivation.md.
3. Архитектура — три слоя
Слой 1: Supervisor (нянька)
- Один процесс
mcphub.exe supervise — долгоживущий
- Знает какие MCP-серверы должны быть запущены — читает
supervisor-intent.json и daemon-intent.json
- Спавнит их при старте
- При падении пытается перезапустить (через auto-respawn dispatcher — PR #230, см. §6)
- При выключении старается убить всех дочек через Windows Job Object с
KILL_ON_JOB_CLOSE
Канонический код: internal/cli/supervise.go:380-680 — runSupervise функция.
Слой 2: Daemon wrapper (обёртка)
- Для каждого MCP-сервера supervisor запускает обёртку
mcphub.exe daemon --server <name> --daemon <variant>
- Обёртка делает то, что сам MCP-сервер не умеет: открывает HTTP-порт, переводит сообщения, держит соединения
- Для
serena: обёртка слушает 9121 (claude) или 9122 (codex), а внутри неё uvx → python serena на внутреннем порту (external + 10000)
- Обёртка проксирует запросы. Похоже на reverse proxy.
Канонический код: internal/daemon/http_host.go (для native-http daemons), internal/daemon/host.go (для stdio bridge).
Слой 3: GUI + router
mcphub.exe gui — веб-интерфейс на 127.0.0.1:9125 (port настраиваемый)- Содержит router: client → request → router → нужный daemon
- Tray icon показывает aggregate state (StateOK / StatePartial / StateDown)
Канонический код: internal/gui/, tray под internal/cli/gui.go.
Картинка
твой AI-ассистент (codex / claude / cursor)
↓
mcphub.exe gui (порт 9125)
↓ роутинг
mcphub.exe supervise ← state files in %LOCALAPPDATA%\mcp-local-hub
↓ держит дочек через Job Object
mcphub.exe daemon --server serena --daemon claude (порт 9121)
↓ внутри спавнит
uvx → uv → python serena (порт 19121)
4. Serena — почему она особенная
serena — MCP-сервер для умной работы с кодом. Знает символы (find_symbol, rename_symbol), может искать ссылки. Написан на Python, запускается через uvx.
Особенность 1: _active_project — глобальное состояние процесса. В каждый момент работает с ОДНИМ проектом. Переключение через activate_project убивает LSP-дочек (clangd, tsserver) старого проекта и спавнит для нового. 200-400 мс + RAM-spike.
Особенность 2: контексты — claude-code и codex. В claude-code контексте activate_project НЕ экспонируется (single_project: true) и search_for_pattern тоже исключён. В codex контексте — оба доступны.
Текущий legacy setup (servers/serena/manifest.yaml на master): 2 daemon-а — claude на 9121 (context claude-code) + codex на 9122 (context codex). Это плохо для multi-project работы — все 6 claude-family агентов делят одну серену залоченную на один проект.
Целевой дизайн (план docs/superpowers/plans/2026-05-20-serena-supervisor-unified.md): N серен = N активных воркспейсов агентов (1:1 биекция, dynamic-pool). Каждый воркспейс получает свой долгоживущий serena-daemon забутстрапленный на --project <abs-path>.
5. Что mcphub УЖЕ решает / ЕЩЁ нет
| Проблема | Решение | Статус |
|---|
| 100 процессов вместо 18 | hub-routing через mcphub migrate | ✓ работает; codex stdio→HTTP миграция применена 2026-05-20 |
| Падающий daemon не перезапускается | PR #229 daemon-exited emit + PR #230 auto-respawn dispatcher | ✓ merged 2026-05-20, validated в production (kill→respawn за 1.1s) |
_active_project thrashing между проектами | dynamic-pool 1:1 biection | пишется в плане, 4 BLOCKERS открыты в v3 review |
| LSP-language MCP-серверы (clangd, typescript и т.д.) per-subagent | PR #222 workspace-scoped LSP-bridge на 9200-9299 | в работе на ветке feat/v0.5.x-servers-matrix-revamp |
| Per-subagent fan-out codex CLI | upstream codex feature request (out-of-scope для mcphub PR) | external-only |
| Аварийная очистка live-rooted процессов | Phase H в плане: mcphub cleanup --aggressive с typed-confirmation | дизайн готов, реализация в v4+ |
6. PR #229 + PR #230 (что сделано 2026-05-20)
PR #229 — supervisor daemon-exited event emit:
- В goroutine
cmd.Wait() (internal/cli/supervise.go:~1600) после exit пишется audit event daemon-exited с pid, exit_code, wait_err
- БЕЗ этого emit супервизор тихо переводил state в "idle" и оператор не знал ПОЧЕМУ daemon упал. 35 циклов silent crash подтверждены логом
- Закрывает diagnostic gap
PR #230 — auto-respawn dispatcher:
- Channel-based goroutine
runRespawnDispatcher (internal/cli/supervise_respawn_dispatcher.go)
- При
daemon-exited non-clean: запись в sliding window (30 мин) → если < 10 в окне → backoff 1s/2s/4s/8s/16s/32s/60s cap → respawn
- При >= 10 fails в окне →
MarkQuarantined + persist supervisor-state.json → авто-respawn останавливается; оператор снимает карантин без полного рестарта через mcphub daemon recover <task> (identity-gated reap порт-скваттера + force-respawn) или force-respawn (POST /api/daemon/respawn {force:true}); cold restart тоже чистит окно
- Operator-stop respect: проверяет
daemon-intent.json IsActiveStop → suppress respawn если оператор сам остановил
- Validated live 2026-05-20 16:12Z: kill серена → cycle exited→scheduled→fired→spawned за 1.1 секунды
7. Где смотреть код для типичных задач
8. Workflow PR — golden path
См. CLAUDE.md §"PR review + merge workflow (MANDATORY)" — это hard gate. Кратко:
go build ./... && go vet ./... && go test ./... локально (но ./internal/cli/... + ./internal/daemon/... чтобы не убить установленных daemon-ов)git push -u origin <branch> + gh pr create- Codex Cloud bot делает review — wait for PASS на CURRENT HEAD commit (не stale на старом)
- Все findings (P0/P1/P2/P3) фиксить ВСЕ перед merge. Не deferer на post-merge без явного разрешения оператора
- Deep-review per CLAUDE.md Step 5 — параллельный codex
-c model_reasoning_effort=xhigh deep-security
- CI
workflow_dispatch-only — НЕ автотриггерить
gh pr merge <N> --squash --delete-branch — НЕ --admin
9. Glossary
| Термин | Простыми словами |
|---|
| MCP | Model Context Protocol — стандарт общения AI с инструментами |
| MCP-сервер | Программа-переводчик между AI и инструментом |
| mcphub | "Телефонная станция" для MCP-серверов — одна копия вместо N |
| supervisor | Нянька внутри mcphub. Запускает, рестартит |
| daemon wrapper | mcphub.exe обёртка вокруг конкретного MCP-сервера |
| serena | MCP-сервер для умной работы с кодом |
| uvx | Python-пакет launcher (как pip install + run) |
| active project | Внутри serena — текущий проект на котором работает |
_active_project thrashing | Когда N AI пытаются переключить проект — серена дёргается |
| dynamic-pool | Архитектура: 1 серена на каждый проект, без перетягивания |
| handshake-port | Альтернатива fixed port: kernel-assigned + IPC publish |
| state machine | Формальная модель состояний (idle/running/exiting и т.д.) |
| orphan | Процесс чей родитель умер, но он сам выжил |
| Job Object | Windows: убить родителя → kernel убьёт детей |
| supervisor-intent.json | Канонический список daemon-ов которые должны крутиться |
| daemon-intent.json | Per-task override: stopped/disabled/quarantined |
| supervisor-state.json | Runtime snapshot: state, current_pid, pid_generation per task |
| supervisor-events.log | JSONL audit — daemon-spawned/exited/respawn-scheduled и т.д. |
| auto-respawn dispatcher | PR #230 goroutine — реагирует на crashCh события |
| sliding window | 30-min окно для failure counter (quarantine threshold = 10) |
| PR #222 | Servers-matrix LSP+env-overlay revamp (in flight) |
| PR #229 | daemon-exited emit (merged 2026-05-20) |
| PR #230 | Auto-respawn dispatcher (merged 2026-05-20) |
| Phase H | Operational hygiene tooling в плане (cleanup --aggressive) |
10. Где спросить операатора
Когда что-то не понятно — лучше спросить чем гадать (AGENTS.md AXIOM "never guess"). Operator preferences:
- Russian default: отвечай на русском по умолчанию (memory: feedback_russian_default)
- Никогда без tray: GUI launch без
--no-tray (memory: feedback_gui_always_tray)
- Subagents always opus + max (memory: feedback_subagent_opus_max_default)
- Codex always xhigh + file-based prompt only (memory: feedback_codex_xhigh_default, feedback_codex_file_prompt_only)
- Build → install order: commit first, then bash build.sh, then install (memory: feedback_build_then_install_order)
11. Term Recap для не-Russian читателя
- skill — учебник (literally "skill" / methodology document)
- учебник — textbook / primer
- демон / daemon — long-running process
- обёртка / wrapper — proxy process spawned around a third-party MCP server
- серены / serena — the serena MCP server (plural "серены" = "serena instances")
- багу / fix / починить — bug / fix / repair (used colloquially)
- merge / merge'нём / merge-ить — git merge, transliterated
