Анализатор кодовой базы MCP-сервера

Промышленный MCP-сервер (Model Context Protocol), который анализирует кодовые базы TypeScript, обнаруживает проблемы со здоровьем кода, получает системные инциденты и генерирует практические планы по устранению неполадок. Поддерживает двойной транспорт (STDIO для локальной разработки, SSE для облачного развертывания). Построен на базе ts-morph, Express и валидации Zod.

🚀 Функции

Три основных инструмента:

1. analyze_codebase_health — сканирует репозитории TypeScript на наличие:

   • Больших файлов (кандидаты на рефакторинг)

   • Отсутствующих явных типов функций (слабая типизация)

   • Циклических зависимостей (архитектурные проблемы)

   • Использует ts-morph для анализа на уровне AST

2. fetch_system_incidents — возвращает структурированные данные об инцидентах:

   • Имитационные данные об инцидентах (идеально для тестирования/демонстрации)

   • Настраиваемые задержки и режимы сбоев

   • JSON-ответы, удобные для LLM

3. generate_remediation_plan — создает практические планы исправлений:

   • Анализ первопричин на основе трассировок стека

   • Пошаговые инструкции по устранению

   • Рекомендации по коду и лучшие практики

   • Оценка уровня риска

Все инструменты возвращают структурированные конверты успеха/ошибки, предназначенные для обработки LLM.

Обзор архитектуры

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

Локальный запуск (STDIO)

1. Установите зависимости:

   • npm install

2. Запустите сервер:

   • npm run dev:stdio

3. Сервер запускается через stdin/stdout и готов к работе с локальными MCP-клиентами.

Запуск с SSE (Express)

1. Установите переменные окружения:

   • TRANSPORT=sse

   • опционально: AUTH_TOKEN=your-secret-token

2. Запустите сервер:

   • npm run dev:sse

3. Эндпоинты:

   • GET /events для потока SSE

   • POST /messages?sessionId=... для сообщений MCP JSON-RPC

Подключение из Cursor

Для локального использования зарегистрируйте Nexus-Core как stdio MCP-сервер:

• command: node

• args: dist/index.js (после сборки) или tsx src/index.ts (разработка)

• env: TRANSPORT=stdio

Для облачного использования настройте ваш MCP-клиент на использование SSE-эндпоинта:

• stream URL: https://<host>/events

• message URL: https://<host>/messages?sessionId=<session-id>

• добавьте Authorization: Bearer <AUTH_TOKEN>, если включена токеновая авторизация.

Примеры промптов

• "Analyze my repo"

• "Fetch incidents"

• "Fix this error"

Переменные окружения

См. .env.example для всех поддерживаемых настроек. Важные параметры:

• TRANSPORT: stdio или sse

• TOOL_TIMEOUT_MS: жесткий таймаут для каждого вызова инструмента

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: ограничители анализа

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: элементы управления внешними зависимостями

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: жизненный цикл сессии SSE

Промышленное развертывание

Docker

• Сборка образа: docker build -t nexus-core .

• Запуск контейнера:

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

Используйте deploy.sh:

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

Этот скрипт:

1. Собирает образ контейнера

2. Отправляет его в GCR

3. Развертывает в Cloud Run

Надежность и модель ошибок

• Все запросы к инструментам проверяются с помощью Zod.

• Ни один вызов инструмента не возвращает необработанные исключения.

• Ошибки используют стандартный конверт с:

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, время выполнения)