Multi-Repo Architecture Hub (oss-mcp)

Расширяемый маршрутизатор мультирепозиторной архитектуры и сервер Model Context Protocol (MCP), написанный на Node.js (ESM). Предназначен для обнаружения зависимостей между репозиториями, топологической маршрутизации и пакетной интеграции AST-индексации с codebase-memory-mcp.

⚡ Быстрый старт (настройка за 3 минуты)

1. Предварительные требования

Убедитесь, что у вас установлены Node.js (>= 18) и codebase-memory-mcp глобально:

# Install codebase-memory-mcp globally
npm install -g codebase-memory-mcp@latest

2. Клонирование и установка зависимостей

git clone https://github.com/Abbilville/oss-mcp oss-mcp
cd oss-mcp
npm install

3. Инициализация любого мультирепозиторного рабочего пространства

Укажите oss-mcp путь к каталогу ваших микросервисов. Он просканирует репозитории, сгенерирует registry.yaml и автоматически выполнит пакетную индексацию кода в графы знаний AST:

npx oss-mcp setup /path/to/your/microservices-workspace

Related MCP server: Codebase Contextifier 9000

🚀 Ключевые возможности

1. Динамическое обнаружение нескольких проектов: Разрешает манифесты репозиториев (registry.yaml) динамически из параметров CLI, центральных каталогов (data/projects.yaml), переменных окружения или иерархии рабочего пространства.

2. Автоматический сканер структуры и зависимостей: Рекурсивно проверяет деревья каталогов в различных технологических стеках (Node.js, Express, React, Python, FastAPI, Java, Go), обнаруживая точки входа, порты и межсервисные HTTP/событийные связи.

3. Автоматическая пакетная AST-индексация: Оркестрирует индексацию графов AST через codebase-memory-mcp для всех сервисов в манифесте проекта одной командой.

4. Структурированный MCP-интерфейс: Предоставляет стандартизированные инструменты для AI-агентов, позволяющие запрашивать межсервисные архитектуры, прослеживать сквозные жизненные циклы запросов и перемещаться по границам нескольких сервисов.

📁 Работа с каталогом data/

Каталог data/ обеспечивает централизованное управление проектами для сред, в которых размещено несколько различных проектов микросервисов или систем.

data/
├── projects.yaml         # Central multi-project catalog (routes project IDs to manifests)
├── registry.yaml         # Default / sample repository manifest and service relationships
├── projects.yaml.example # Reference template for projects catalog
└── registry.yaml.example # Reference template for repository manifests

1. Центральный каталог проектов (data/projects.yaml)

Если вы управляете несколькими проектами на своей машине, зарегистрируйте их в data/projects.yaml (или ~/.config/oss-mcp/projects.yaml). Это позволит вам обращаться к любому проекту по идентификатору (например, npx oss-mcp index --project ecommerce):

# data/projects.yaml
projects:
  ecommerce:
    name: "E-Commerce Microservices"
    description: "Frontend SPA, API Gateway, Auth Service, and Order Service"
    registry_path: "./data/ecommerce_registry.yaml"
    root_path: "/path/to/ecommerce/workspace"

  analytics:
    name: "Analytics Platform"
    description: "Event streaming and reporting backend"
    registry_path: "/path/to/analytics/registry.yaml"
    root_path: "/path/to/analytics/workspace"

2. Манифест репозитория (registry.yaml)

Каждый проект имеет registry.yaml, определяющий его отдельные сервисы, метаданные, точки входа, порты и связи.

# registry.yaml
repos:
  - name: backend-service
    owner: backend-team
    local_path: ./services/backend-service
    description: "REST API server handling auth, database persistence, and business logic"
    tech_stack:
      - Node.js
      - Express
      - PostgreSQL
      - Redis
      - JWT
    entry_point: src/server.js
    port: 4000

  - name: web-frontend
    owner: frontend-team
    local_path: ./services/web-frontend
    description: "Customer SPA built with React and TypeScript"
    tech_stack:
      - React
      - TypeScript
      - Axios
    entry_point: src/index.tsx
    port: 3000

relationships:
  - source: web-frontend
    target: backend-service
    type: api_call
    description: "Frontend makes REST API calls to backend endpoints for data and authentication."

  - source: web-frontend
    target: backend-service
    type: depends_on
    description: "Frontend depends on backend JWT session management and RBAC permissions."

Поддерживаемые типы связей

• api_call: HTTP / REST / GraphQL-вызов от источника к цели.

• depends_on: Архитектурная зависимость или зависимость жизненного цикла (например, общая сессия, контрактная зависимость).

• event_stream: Асинхронный обмен сообщениями (Kafka, RabbitMQ, Redis Pub/Sub, AWS EventBridge).

• shared_resource: Общая схема базы данных, экземпляр кэша или хранилище.

• submodule: Ссылка на Git-подмодуль или пакет в монорепозитории.

🎯 Иерархия разрешения манифеста

При выполнении инструментов или команд CLI oss-mcp определяет, какой реестр загрузить, используя резервный механизм из 4 уровней:

1. Explicit Flag / Parameter   (--project "ecommerce" or --registry "/path/to/registry.yaml")
   └── 2. Central Projects Catalog (data/projects.yaml or ~/.config/oss-mcp/projects.yaml)
       └── 3. Environment Variable   (export MCP_REGISTRY_PATH="/path/to/registry.yaml")
           └── 4. Workspace Traversal (searching current directory & parent folders for registry.yaml)

💻 Справочник CLI

🤖 Интеграция с AI-ассистентами и IDE

oss-mcp предоставляет архитектурный мост, работающий в связке с codebase-memory-mcp.

┌─────────────────────────────────────────────────────────────┐
│                       AI Agent Layer                        │
│   (Antigravity / Claude Code / Cursor / Codex / Roo Code)   │
└──────────────────────────────┬──────────────────────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
 ┌───────────────────────────┐   ┌───────────────────────────┐
 │          oss-mcp          │   │    codebase-memory-mcp    │
 │                           │   │                           │
 │ • Multi-repo discovery    │   │ • Deep AST function index │
 │ • Service topology & port │   │ • Class & symbol search   │
 │ • Cross-repo relationships│   │ • Call graph path tracing │
 │ • Batch index management  │   │ • Source code snippets    │
 └───────────────────────────┘   └───────────────────────────┘

1. 🪐 Google Antigravity (AGY)

A. Настройка MCP-сервера

Добавьте oss-mcp в файл .agents/mcp_config.json вашего проекта или глобально в ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Установка навыков и правил рабочего пространства

1. Скопируйте или создайте символическую ссылку на каталог .agents/skills/ в каталог .agents/skills/ вашего активного проекта (или глобальный ~/.gemini/config/skills/).

2. Включите правило маршрутизации мультирепозиторных запросов в .agents/AGENTS.md:

   # Multi-Repo Routing
   For any question spanning multiple services or repositories, use the `oss-mcp` MCP server to discover topology with `get_architecture_overview()`, then query `codebase-memory-mcp` scoped to relevant repositories.

C. Слэш-команды Antigravity и использование

Вводите эти команды непосредственно в чате Antigravity:

• /oss setup /path/to/microservices — Автоматическое сканирование рабочего пространства, определение стеков и портов, генерация registry.yaml и пакетная индексация в графы AST.

• /oss status — Просмотр таблицы зарегистрированных сервисов, портов и количества узлов/ребер графа.

• /oss trace checkout flow from UI to backend — Прослеживание сквозных межсервисных жизненных циклов с диаграммами последовательности.

• /oss remove <project_id> — Безопасное удаление проекта и очистка графов знаний.

2. ⚡ Claude Code (CLI) и Claude Desktop

A. Настройка Claude Code CLI

Добавьте MCP-сервер напрямую с помощью команды claude mcp add:

# Add oss-mcp MCP server
claude mcp add oss-mcp node /absolute/path/to/oss-mcp/src/server.js

Или добавьте в файл .claude.json / settings.json вашего проекта:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Настройка Claude Desktop

Откройте файл конфигурации Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Добавьте определение сервера:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["C:/Telkom/oss-mcp/src/server.js"]
    }
  }
}

C. Инструкция по рабочему процессу Claude (CLAUDE.md)

Добавьте эту рекомендацию в файл CLAUDE.md вашего проекта, чтобы научить Claude маршрутизировать мультирепозиторные запросы:

## Multi-Repo Architecture Navigation
When answering questions about cross-service interactions, microservices, or APIs:
1. Call `oss-mcp` tool `get_architecture_overview()` to locate caller/callee services and port contracts.
2. Query `codebase-memory-mcp` (`search_graph`, `trace_path`, `get_code_snippet`) scoped by repository name.
3. Synthesize the end-to-end flow with a Mermaid sequence diagram.

D. Примеры чат-запросов в Claude

• "Отсканируй папку ../services и инициализируй мультирепозиторный реестр."

• "Покажи все зарегистрированные микросервисы и проверь, индексированы ли их графы AST."

• "Проследи поток аутентификации JWT от входа на фронтенде до проверки токена на бэкенде."

3. 🎯 Cursor IDE

A. Добавление MCP-сервера в Cursor

1. Перейдите в Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP.

2. Нажмите + Add New MCP Server.

3. Заполните:

   • Name: oss-mcp

   • Type: command

   • Command: node /absolute/path/to/oss-mcp/src/server.js

4. Нажмите Save и проверьте зеленую точку статуса.

B. Правила Cursor (.cursorrules или .cursor/rules/multi-repo.mdc)

Создайте файл правил в вашем рабочем пространстве:

---
description: Multi-repository architecture navigation rules
globs: *
---
You have access to the `oss-mcp` MCP server.
When the user asks about multi-service architecture or cross-repo communication:
1. Call `get_architecture_overview` to understand service topologies and ports.
2. Trace API calls and dependencies between services.
3. Provide Mermaid sequence diagrams for all cross-service workflows.

C. Примеры чат-запросов в Cursor

• @oss-mcp Какие сервисы взаимодействуют с платежным бэкендом?

• @oss-mcp Отсканируй это мультирепозиторное рабочее пространство и сгенерируй registry.yaml

• Как фронтенд-клиент получает товары из API каталога? Проследи маршрут и обработчик.

4. 🧩 Roo Code / Cline / Codex (расширения VS Code)

A. Настройка параметров MCP

Откройте cline_mcp_settings.json (или roo_cline_mcp_settings.json):

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"],
      "disabled": false,
      "autoApprove": [
        "get_architecture_overview",
        "get_repo_details",
        "get_related_repos",
        "list_projects"
      ]
    }
  }
}

B. Пользовательские инструкции

Добавьте в Custom Instructions в настройках Cline / Roo Code:

When working across multiple repositories, use the `oss-mcp` MCP tools to inspect service dependencies and ports before making code modifications or answering architectural questions.

🛠️ Подробный разбор навыков рабочего пространства

Навыки в .agents/skills/ инкапсулируют полные сквозные мультирепозиторные рабочие процессы:

🔌 Справочник MCP-инструментов

Лицензия

Распространяется под лицензией MIT.