🏛️ ArchMCP: центральный удалённый MCP-сервер для микросервисов

[]

Дайте вашему ИИ-ассистенту для кодирования организационный мозг.
ArchMCP — это лёгкий удалённый сервер Model Context Protocol (MCP), который подключает ваших ИИ-ассистентов (Google Antigravity, Claude Desktop, Cursor, VS Code) ко всей вашей микросервисной архитектуре в реальном времени.

📚 Ознакомьтесь с пошаговым руководством пользователя и инструкцией по настройке

📖 История создания ArchMCP

Повседневная проблема

Представьте, что вы пишете фичу в order-service вместе со своим ИИ-ассистентом для кодирования. Вы спрашиваете ИИ:

«Реализуй оформление заказа и спиши с покупателя деньги».

И тут же ИИ упирается в стену:

• У него нет никакого понятия, какие заголовки payment-service требует для идемпотентности.

• Он не знает, какие колонки существуют в базе данных inventory-service, чтобы зарезервировать остатки.

• Он понятия не имеет, какие вышестоящие сервисы сломаются, если вы измените эндпоинт.

Чтобы решить эту проблему, разработчики обычно пробуют один из двух плохих вариантов:

1. Дамп всех репозиториев в промпт: это легко сжигает 100 000+ токенов за один вопрос, стоит больших денег, замедляет работу ИИ и вызывает галлюцинации из-за шума в промпте.

2. Клонирование 20+ репозиториев локально: каждый разработчик в команде должен хранить 20 репозиториев в актуальном состоянии на своём ноутбуке, чтобы локальный ИИ имел контекст.

Решение: общий удалённый мозг

ArchMCP решает эту задачу, выступая в роли централизованного «мозга» с миллисекундным доступом.

Вместо того чтобы работать как приватная локальная команда на одном ноутбуке, ArchMCP работает как общий удалённый сервис. Любой инженер команды подключает своего ИИ-ассистента к URL-адресу сервера ArchMCP с токеном аутентификации.

Когда вашему ИИ-ассистенту нужно узнать:

• «Какой сервис отвечает за возвраты?» $\rightarrow$ вызывает search_microservices.

• «Какие таблицы владеют данные в payment-service» $\rightarrow$ вызывает get_database_schema.

• «Если я изменю /api/v1/orders, кто сломается?» $\rightarrow$ вызывает analyze_blast_radius.

┌────────────────────────────────────────────────────────┐
│                   AI Assistant Client                  │
│       (Google Antigravity, Claude Desktop, Cursor)     │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │  HTTP / Server-Sent Events (SSE)
                           │  Authorization: Bearer <token>
                           │
┌──────────────────────────▼────────────────────────────────────────────────────────┐
│                                   ArchMCP Server                                   │
│                                                                                    │
│   ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐   │
│   │      MCP Tools      │  │    MCP Resources    │  │       MCP Prompts        │   │
│   │ • search_services   │  │ • arch/overview     │  │ • cross_service_planner  │   │
│   │ • blast_radius      │  │ • services/catalog  │  │ • incident_triage        │   │
│   │ • sequence_diagram  │  │ • guidelines/docs   │  │ • contract_refactor      │   │
│   │ • get_db_schema     │  │ • service docs      │  │                          │   │
│   └──────────┬──────────┘  └──────────┬──────────┘  └────────────┬─────────────┘   │
│              │                        │                          │                 │
│   ┌──────────▼────────────────────────▼──────────────────────────▼─────────────┐   │
│   │                       Microservice Intelligence Engine                     │   │
│   │ • Transitive Graph Traversal & Blast Radius Analyzer (BFS)                 │   │
│   │ • In-Memory Index & Token Search (< 2ms response time)                     │   │
│   │ • Dynamic OpenAPI / Swagger 3.0 Importer                                   │   │
│   └───────────────────────────────────┬────────────────────────────────────────┘   │
│                                       │                                            │
│   ┌───────────────────────────────────▼────────────────────────────────────────┐   │
│   │              Embedded Web Visualizer & Live Sandbox (/dashboard)           │   │
│   │ • Interactive Service Topology Explorer & Token Economics Calculator       │   │
│   └────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────┘

💡 Как я это спроектировал и почему

При проектировании ArchMCP я ставил цель сделать сервер быстрым, чистым и практичным без лишней сложности:

1. Почему удалённый HTTP/SSE, а не локальный CLI-процесс?

Стандартные MCP-серверы запускаются как локальный дочерний процесс через stdio. Хотя это работает для однопользовательских десктопных сценариев, компания с 50 инженерами и 30 микросервисами нуждается в едином централизованном источнике правды. Если запустить ArchMCP по HTTP/SSE, архитектурные обновления и новые API-схемы мгновенно станут доступны всем, без локального клонирования репозиториев.

2. Почему графовый индекс в памяти, а не тяжёлая векторная база данных?

Многие ИИ-инструменты сразу переходят на тяжёлые векторные базы данных (например, Pinecone или Milvus). Для структурированных архитектурных метаданных (маршруты API, таблицы баз данных, зависимости сервисов) обход графа и быстрое лексическое сопоставление токенов дают:

• Детерминизм: точные совпадения для таких маршрутов, как /api/v1/auth/login, или таблицы users.

• Нулевые накладные расходы: работа с ~38 МБ RAM, без внешних API-ключей и требований к GPU.

• Высокую скорость: время ответа менее 2 мс.

3. Рассмотренные компромиссы

📊 Бенчмарки производительности и экономичность по токенам

Мы измерили разницу между анализом микросервисной задачи через загрузку всех исходников в контекст и через запрос ArchMCP:

💡 Проверка в реальном времени: вы можете в любой момент вживую протестировать и измерить эти показатели на встроенном интерактивном дашборде‑песочнице, который рассчитывает считатые задержки и экономию токенов на каждом запросе.

🔍 Сюрпризы и открытия по ходу дела

Создание удалённого MCP-сервера на Python вскрыло несколько любопытных технических деталей:

1. Типовые аннотации становятся схемами AI: официальный Python SDK для MCP автоматически превращает Python-аннотации типов и docstring в определённые JSON-Schema, затем LLM использует схемы для выбора инструментов. Хорошие docstring делают ИИ буквально умнее.

2. Защита от DNS Rebinding: протокол MCP 2.0 автоматически проверяет входящие заголовки Host, чтобы защитить внутренние сети разработчиков от DNS-rebinding-атак через браузер.

3. Двухфазный SSE‑handshake: когда клиент ИИ подключается к GET /sse, сервер открывает Event Stream и возвращает уникальный callback-URL сессии (/messages/?session_id=...). Все последующие JSON-RPC-вызовы инструментов уходят именно на него.

🖥️ Живой браузерный визуализатор и песочница

ArchMCP включает встроенный отзывчивый веб‑дашборд по адресу http://localhost:8000/dashboard (или /):

• Интерактивная топология: Нажмите на любую карточку сервиса (auth-service, order-service, payment-service), чтобы увидеть его API, таблицы баз данных и карту связей.

• Живая песочница инструментов: Проверьте любой MCP-инструмент в реальном времени и наблюдайте запрос/ответ JSON-RPC, экономию токенов и задержку.

⌨️ CLI для разработчика

В состав ArchMCP входит удобный инструмент командной строки:

# 1. Start the Remote Server
archmcp run

# 2. Explore the Catalog in your Terminal
archmcp explore

# 3. Calculate Change Blast Radius
archmcp blast-radius auth-service

# 4. Import a live OpenAPI / Swagger Specification
archmcp import-openapi https://petstore.swagger.io/v2/swagger.json --owner "Commerce Team"

🔌 Подключение вашего ИИ‑ассистента

Как только ArchMCP запущен (например, на http://127.0.0.1:8000/sse), настройте ваш ИИ‑инструмент за секунды:

Google Antigravity IDE

Добавьте в .agents/mcp_config.json:

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse?token=dev-token-secret-123"
    }
  }
}

🚀 Быстрый старт из 3 шагов

# 1. Clone & Install
git clone https://github.com/ShubhamScript/archmcp.git
cd archmcp
pip install -e .[dev]

# 2. Run Tests
pytest -v

# 3. Start Server
archmcp run

Откройте в браузере http://localhost:8000/dashboard, чтобы интерактивно исследовать вашу архитектуру.

🔮 Что дальше в планах развития

Если вы расширяете ArchMCP до 500+ микросервисов в крупном предприятии:

1. Семантический поиск понятий: добавление pgvector или sqlite-vec с локальными эмбеддингами, чтобы разработчики могли искать по смыслу («Где живёт рекуррентный биллинг?»).

2. Интеграция с Backstage: автоматическая синхронизация с catalog-info.yaml от Spotify.

3. Шина Redis Event Bus: синхронизация активных SSE-сессий между масштабируемыми репликами контейнеров.

4. Git Webhooks: автоматическое обновление схем при каждом мерже PR.

📂 Структура проекта

archmcp/
├── README.md                      # Project guide & architecture story
├── pyproject.toml                 # Dependencies, CLI scripts, and build config
├── Dockerfile                     # Container build instructions
├── docker-compose.yml             # Container orchestration
├── data/
│   └── repositories.yaml          # Sample microservices catalog
├── src/
│   └── archmcp/
│       ├── main.py                # Server bootstrap
│       ├── cli.py                 # Developer CLI (run, explore, blast-radius, import-openapi)
│       ├── config/settings.py     # Environment settings
│       ├── auth/                  # Bearer token verification & ASGI middleware
│       ├── mcp/                   # Tools, Resources, Prompts, and SSE route handlers
│       ├── services/              # Blast radius, graph traversal, and search logic
│       ├── ingestion/             # OpenAPI importer, markdown parser, dependency scanner
│       ├── storage/               # In-memory database & token search index
│       ├── web/                   # Embedded visualizer and live testing playground
│       └── models/                # Pydantic schemas (Architecture, BlastRadius, Services)
└── tests/                         # 18 unit & integration tests

📄 Лицензия

Лицензия MIT. Бесплатно для Open Source и коммерческого использования.