lekss361/gendesign

Fork 0

infra: развернуть стек MCP-серверов (GlitchTip + Redis ACL + .claude/mcp.json) #204

New issue

Closed

opened 2026-05-16 10:28:47 +00:00 by lekss361 · 0 comments

lekss361 commented

2026-05-16 10:28:47 +00:00

Owner

Контекст

Расширяем набор MCP-серверов в Claude Code, чтобы закрыть текущие болевые точки:

нет WebSearch → Brave Search MCP + Fetch MCP
нет наблюдаемости ошибок → self-hosted GlitchTip + Sentry-MCP
нет тулинга для очередей/контейнеров → Redis + Docker MCP
нет инструментов для I3 #44 (engineering_networks) → Overpass MCP
нет геокодинга для Site Finder → MapTiler MCP
нет valid-time schema introspection → OpenAPI MCP по gendsgn.ru/openapi.json
Obsidian MCP режет файлы >64k → Filesystem MCP с whitelist на mirror

Полный список и обоснование: см. обсуждение в чате-сессии 2026-05-16 (вынесу в vault runbooks/MCP_Stack_2026-05.md отдельным PR).

Acceptance

claude mcp list на dev-машине показывает 14 серверов, все зелёные
GlitchTip отдаёт UI на https://errors.gendsgn.ru, проект backend + frontend создан
FastAPI и Next.js отправляют test-event в GlitchTip (виден в UI)
Redis на VPS закрыт паролем (requirepass), MCP подключается через SSH-tunnel
Дев-документ в vault: runbooks/MCP_Stack_2026-05.md с конфигом + env-keys
CLAUDE.md обновлён: список доступных MCP в секции «Where to look»

Шаги развёртки (Beget VPS)

Шаг 1. GlitchTip (errors.gendsgn.ru)

1.1. Создать БД и пользователя

ssh gendesign
sudo -u postgres psql <<'SQL'
CREATE USER glitchtip WITH PASSWORD '<gen>';
CREATE DATABASE glitchtip OWNER glitchtip;
SQL

1.2. Дополнить `docker-compose.yml`

  glitchtip-web:
    image: glitchtip/glitchtip:latest
    container_name: glitchtip-web
    depends_on: [postgres, redis]
    environment:
      DATABASE_URL: postgres://glitchtip:${GLITCHTIP_DB_PASS}@postgres:5432/glitchtip
      SECRET_KEY: ${GLITCHTIP_SECRET}
      PORT: 8080
      EMAIL_URL: dummy://
      GLITCHTIP_DOMAIN: https://errors.gendsgn.ru
      DEFAULT_FROM_EMAIL: errors@gendsgn.ru
      CELERY_WORKER_AUTOSCALE: "1,3"
      ENABLE_USER_REGISTRATION: "false"
    restart: always
    mem_limit: 256m

  glitchtip-worker:
    image: glitchtip/glitchtip:latest
    container_name: glitchtip-worker
    depends_on: [postgres, redis]
    command: ./bin/run-celery-with-beat.sh
    environment:
      DATABASE_URL: postgres://glitchtip:${GLITCHTIP_DB_PASS}@postgres:5432/glitchtip
      SECRET_KEY: ${GLITCHTIP_SECRET}
    restart: always
    mem_limit: 256m

В .env.runtime (на VPS):

GLITCHTIP_DB_PASS=<gen>
GLITCHTIP_SECRET=<openssl rand -hex 32>

1.3. Caddy

errors.gendsgn.ru {
    reverse_proxy glitchtip-web:8080
}

docker compose up -d glitchtip-web glitchtip-worker && systemctl reload caddy (или caddy reload).

1.4. Создать первого админа

docker compose exec glitchtip-web ./manage.py createsuperuser

→ создать организацию gendesign, проекты backend, frontend, celery, забрать DSN-ы.

Шаг 2. Sentry SDK в коде

2.1. Backend (`backend/app/main.py`)

import sentry_sdk
from sentry_sdk.integrations.celery import CeleryIntegration
from sentry_sdk.integrations.fastapi import FastApiIntegration
from sentry_sdk.integrations.sqlalchemy import SqlalchemyIntegration

if settings.GLITCHTIP_DSN:
    sentry_sdk.init(
        dsn=settings.GLITCHTIP_DSN,
        environment=settings.ENVIRONMENT,
        release=settings.GIT_SHA,
        traces_sample_rate=0.05,
        integrations=[FastApiIntegration(), CeleryIntegration(), SqlalchemyIntegration()],
    )

2.2. Frontend (`frontend/sentry.{client,server,edge}.config.ts`)

Стандартный @sentry/nextjs init, DSN из NEXT_PUBLIC_GLITCHTIP_DSN.

2.3. Smoke-test

docker compose exec backend python -c "import sentry_sdk; sentry_sdk.capture_message('glitchtip ok')"

→ event прилетает в UI за 5–10 сек.

Шаг 3. Redis ACL + удалённый доступ

Сейчас redis открыт только внутри docker-сети. Чтобы MCP с локальной машины мог подключаться:

# В redis-контейнере
redis-cli ACL SETUSER mcp_ro on '><gen>' allkeys +@read +@connection +ping

Прокинуть SSH-tunnel на dev-машине (как уже сделано для postgres):

ssh -N -L 6379:localhost:6379 gendesign

В mcp.json: REDIS_URL=redis://mcp_ro:<pass>@localhost:6379/0.

Альтернатива (если не хочется тоннеля): пробросить TLS-Redis через Caddy stream. Но для read-only диагностики тоннель проще.

Шаг 4. API-ключи

Ключ	Где взять	Назначение
`BRAVE_API_KEY`	https://api.search.brave.com → Free plan	Web search 2k/мес
`MAPTILER_API_KEY`	https://cloud.maptiler.com → Free	Геокодинг 100k/мес
`GLITCHTIP_TOKEN`	https://errors.gendsgn.ru/profile/auth-tokens	Sentry-MCP read access

Положить в env-переменные dev-машины (User-scope, не в репо).

Шаг 5. `.claude/mcp.json`

Положить файл из соседнего сообщения в ~/.claude/mcp.json. После — claude mcp list.

Полный финальный список (14 серверов):

forgejo — уже есть
obsidian — уже есть
postgres-gendesign — уже есть
chrome-devtools — уже есть
playwright — уже есть
knowledge-graph — уже есть
fetch — новый
brave-search — новый
openapi — новый
maptiler — новый
overpass — новый
docker — новый
redis — новый
sentry (→ GlitchTip) — новый
filesystem-vault — новый
sequential-thinking — новый

(итого 16; считай 14 если объединить filesystem-vault и obsidian как «один источник vault»)

Шаг 6. Документация

Vault runbooks/MCP_Stack_2026-05.md — этот же чеклист + troubleshooting
CLAUDE.md → секция «Where to look» добавить ссылку на runbook
.env.example в репо — добавить плейсхолдеры GLITCHTIP_DSN, NEXT_PUBLIC_GLITCHTIP_DSN

Caveats и риски

Имена npm-пакетов: MCP-экосистема молодая, имена пакетов меняются. Перед каждым npx -y <name> проверять npm view <name> — если 404, искать актуальный форк (overpass-mcp особенно).
Resource budget VPS: GlitchTip web+worker ≈ 400 MB RAM. Проверить docker stats перед merge.
Redis ACL: при существующих Celery worker'ах добавление requirepass сломает соединение — выкатывать ACL-only, без requirepass (Celery подключается под default без пароля, MCP — под mcp_ro).
GlitchTip SECRET_KEY ротация: после смены протухают сессии. Зафиксировать в KeePass.
Tier limits: Brave 2k/мес запросов хватит, но если будем гонять research-сессии каждый день — мониторить.

Engineering networks issue (#TBD после #200)
Vault: meta/Project_GenDesign.md changelog 2026-05-16
Discussion: чат-сессия 2026-05-16 (claude opus 4.7)

## Контекст Расширяем набор MCP-серверов в Claude Code, чтобы закрыть текущие болевые точки: - нет WebSearch → Brave Search MCP + Fetch MCP - нет наблюдаемости ошибок → self-hosted **GlitchTip** + Sentry-MCP - нет тулинга для очередей/контейнеров → Redis + Docker MCP - нет инструментов для I3 #44 (`engineering_networks`) → Overpass MCP - нет геокодинга для Site Finder → MapTiler MCP - нет valid-time schema introspection → OpenAPI MCP по `gendsgn.ru/openapi.json` - Obsidian MCP режет файлы >64k → Filesystem MCP с whitelist на mirror Полный список и обоснование: см. обсуждение в чате-сессии 2026-05-16 (вынесу в vault `runbooks/MCP_Stack_2026-05.md` отдельным PR). ## Acceptance - [ ] `claude mcp list` на dev-машине показывает **14 серверов**, все зелёные - [ ] GlitchTip отдаёт UI на https://errors.gendsgn.ru, проект `backend` + `frontend` создан - [ ] FastAPI и Next.js отправляют test-event в GlitchTip (виден в UI) - [ ] Redis на VPS закрыт паролем (`requirepass`), MCP подключается через SSH-tunnel - [ ] Дев-документ в vault: `runbooks/MCP_Stack_2026-05.md` с конфигом + env-keys - [ ] CLAUDE.md обновлён: список доступных MCP в секции «Where to look» --- ## Шаги развёртки (Beget VPS) ### Шаг 1. GlitchTip (errors.gendsgn.ru) #### 1.1. Создать БД и пользователя ```bash ssh gendesign sudo -u postgres psql <<'SQL' CREATE USER glitchtip WITH PASSWORD '<gen>'; CREATE DATABASE glitchtip OWNER glitchtip; SQL ``` #### 1.2. Дополнить `docker-compose.yml` ```yaml glitchtip-web: image: glitchtip/glitchtip:latest container_name: glitchtip-web depends_on: [postgres, redis] environment: DATABASE_URL: postgres://glitchtip:${GLITCHTIP_DB_PASS}@postgres:5432/glitchtip SECRET_KEY: ${GLITCHTIP_SECRET} PORT: 8080 EMAIL_URL: dummy:// GLITCHTIP_DOMAIN: https://errors.gendsgn.ru DEFAULT_FROM_EMAIL: errors@gendsgn.ru CELERY_WORKER_AUTOSCALE: "1,3" ENABLE_USER_REGISTRATION: "false" restart: always mem_limit: 256m glitchtip-worker: image: glitchtip/glitchtip:latest container_name: glitchtip-worker depends_on: [postgres, redis] command: ./bin/run-celery-with-beat.sh environment: DATABASE_URL: postgres://glitchtip:${GLITCHTIP_DB_PASS}@postgres:5432/glitchtip SECRET_KEY: ${GLITCHTIP_SECRET} restart: always mem_limit: 256m ``` В `.env.runtime` (на VPS): ``` GLITCHTIP_DB_PASS=<gen> GLITCHTIP_SECRET=<openssl rand -hex 32> ``` #### 1.3. Caddy ```caddyfile errors.gendsgn.ru { reverse_proxy glitchtip-web:8080 } ``` `docker compose up -d glitchtip-web glitchtip-worker && systemctl reload caddy` (или `caddy reload`). #### 1.4. Создать первого админа ```bash docker compose exec glitchtip-web ./manage.py createsuperuser ``` → создать организацию `gendesign`, проекты `backend`, `frontend`, `celery`, забрать DSN-ы. --- ### Шаг 2. Sentry SDK в коде #### 2.1. Backend (`backend/app/main.py`) ```python import sentry_sdk from sentry_sdk.integrations.celery import CeleryIntegration from sentry_sdk.integrations.fastapi import FastApiIntegration from sentry_sdk.integrations.sqlalchemy import SqlalchemyIntegration if settings.GLITCHTIP_DSN: sentry_sdk.init( dsn=settings.GLITCHTIP_DSN, environment=settings.ENVIRONMENT, release=settings.GIT_SHA, traces_sample_rate=0.05, integrations=[FastApiIntegration(), CeleryIntegration(), SqlalchemyIntegration()], ) ``` #### 2.2. Frontend (`frontend/sentry.{client,server,edge}.config.ts`) Стандартный `@sentry/nextjs` init, DSN из `NEXT_PUBLIC_GLITCHTIP_DSN`. #### 2.3. Smoke-test ```bash docker compose exec backend python -c "import sentry_sdk; sentry_sdk.capture_message('glitchtip ok')" ``` → event прилетает в UI за 5–10 сек. --- ### Шаг 3. Redis ACL + удалённый доступ Сейчас redis открыт только внутри docker-сети. Чтобы MCP с локальной машины мог подключаться: ```bash # В redis-контейнере redis-cli ACL SETUSER mcp_ro on '><gen>' allkeys +@read +@connection +ping ``` Прокинуть SSH-tunnel на dev-машине (как уже сделано для postgres): ``` ssh -N -L 6379:localhost:6379 gendesign ``` В `mcp.json`: `REDIS_URL=redis://mcp_ro:<pass>@localhost:6379/0`. **Альтернатива** (если не хочется тоннеля): пробросить TLS-Redis через Caddy stream. Но для read-only диагностики тоннель проще. --- ### Шаг 4. API-ключи | Ключ | Где взять | Назначение | |---|---|---| | `BRAVE_API_KEY` | https://api.search.brave.com → Free plan | Web search 2k/мес | | `MAPTILER_API_KEY` | https://cloud.maptiler.com → Free | Геокодинг 100k/мес | | `GLITCHTIP_TOKEN` | https://errors.gendsgn.ru/profile/auth-tokens | Sentry-MCP read access | Положить в env-переменные **dev-машины** (User-scope, не в репо). --- ### Шаг 5. `.claude/mcp.json` Положить файл из соседнего сообщения в `~/.claude/mcp.json`. После — `claude mcp list`. Полный финальный список (14 серверов): 1. forgejo — уже есть 2. obsidian — уже есть 3. postgres-gendesign — уже есть 4. chrome-devtools — уже есть 5. playwright — уже есть 6. knowledge-graph — уже есть 7. **fetch** — новый 8. **brave-search** — новый 9. **openapi** — новый 10. **maptiler** — новый 11. **overpass** — новый 12. **docker** — новый 13. **redis** — новый 14. **sentry (→ GlitchTip)** — новый 15. **filesystem-vault** — новый 16. **sequential-thinking** — новый (итого 16; считай 14 если объединить filesystem-vault и obsidian как «один источник vault») --- ### Шаг 6. Документация - [ ] Vault `runbooks/MCP_Stack_2026-05.md` — этот же чеклист + troubleshooting - [ ] CLAUDE.md → секция «Where to look» добавить ссылку на runbook - [ ] `.env.example` в репо — добавить плейсхолдеры `GLITCHTIP_DSN`, `NEXT_PUBLIC_GLITCHTIP_DSN` --- ## Caveats и риски - **Имена npm-пакетов**: MCP-экосистема молодая, имена пакетов меняются. Перед каждым `npx -y <name>` проверять `npm view <name>` — если 404, искать актуальный форк (`overpass-mcp` особенно). - **Resource budget VPS**: GlitchTip web+worker ≈ 400 MB RAM. Проверить `docker stats` перед merge. - **Redis ACL**: при существующих Celery worker'ах добавление `requirepass` сломает соединение — выкатывать ACL-only, без `requirepass` (Celery подключается под `default` без пароля, MCP — под `mcp_ro`). - **GlitchTip SECRET_KEY ротация**: после смены протухают сессии. Зафиксировать в KeePass. - **Tier limits**: Brave 2k/мес запросов хватит, но если будем гонять research-сессии каждый день — мониторить. ## Related - Engineering networks issue (#TBD после `#200`) - Vault: `meta/Project_GenDesign.md` changelog 2026-05-16 - Discussion: чат-сессия 2026-05-16 (claude opus 4.7)