Corpus

Corpus агрегирует документацию всех репозиториев вашей организации, строит живую карту системы на основе сущностей каталога Spotify Backstage и предоставляет всё это через мощный сервер Model Context Protocol (MCP).

Дайте вашим ИИ-агентам (Claude, Copilot и др.) целостный контекст, необходимый для понимания вашей архитектуры, владельцев сервисов, документации и кода — всё в одном месте!

✨ Возможности

• 🗺️ Автоматически генерируемый граф сущностей: Полностью разбирает сущности Backstage catalog-info.yaml (Components, APIs, Systems, Users) и генерирует двунаправленный граф связей с использованием общеизвестных отношений (например, ownerOf/ownedBy, providesApi/apiProvidedBy).

• 📖 Централизованный поиск по документации: Быстрый лексический поиск по README.md, docs/**/*.md, adr/**/*.md и ИИ-навыкам во всей вашей организации.

• 🔍 Глобальный поиск по коду: Поиск по ключевым словам во всех репозиториях организации через GitHub Code Search API.

• 💬 Контекст задач и PR: Проксирует запросы к поисковому API GitHub для поиска обсуждений, PR и задач по всей организации (search_issues_and_prs).

• 📄 Чтение файлов: Прямой доступ к точному содержимому файлов из любой ветки или коммита репозитория.

• ⚙️ Агрегация схем API: Автоматически индексирует файлы openapi и swagger, чтобы агенты могли мгновенно получать контракты конечных точек (list_api_schemas).

• 🚀 Запуск без настройки: Автоматически запускает недостающие сборки при старте. Если у вас есть учётные данные, просто выполните npm start — и сервер загрузит и проиндексирует всё.

• 🐞 Отчётность о пробелах: Опциональная возможность создания задачи GitHub, когда документация не может ответить на вопрос агента.

Related MCP server: repovine

🛠️ Быстрый старт

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

• Node.js v22+

• GitHub PAT (Personal Access Token):

  • Classic Token: Требуются права repo (для чтения приватных репозиториев) и read:org (если вы запрашиваете данные организации).

  • Fine-Grained Token: Требуются права Contents: Read-only и Metadata: Read-only для всех репозиториев. Если вы включите ENABLE_GAP_REPORTING, вам также понадобятся права Issues: Read & Write на целевом репозитории.

2. Настройка окружения

Создайте файл .env в корневом каталоге:

GIT_ORG=your-github-org-or-username
GIT_PAT=your-github-personal-access-token

# Optional
ENABLE_GAP_REPORTING=false
GITHUB_PROJECT=your-github-org/doc-gaps-repo

3. Сборка и запуск

Локальный запуск:

npm install
npm run build
npm start

Примечание: npm start автоматически запускает скрипты генерации корпуса и карты системы, если они ещё не были выполнены.

Запуск через Docker:

docker build -t corpus-mcp .
docker run -i -e GIT_ORG=your-github-org -e GIT_PAT=your-github-pat corpus-mcp

🤖 Регистрация в ИИ-клиентах

Antigravity

Antigravity нативно поддерживает MCP. Настройте сервер глобально, добавив его в ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "DOTENV_CONFIG_PATH": "/absolute/path/to/code-context-mcp/.env",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Desktop

Добавьте это в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "GIT_PAT": "your-github-pat",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Code

Выполните следующую команду в корне проекта:

claude mcp add corpus "node $(pwd)/dist/src/index.js"

🏗️ Архитектура и команды

• npm run build:corpus: Сканирует организацию GitHub и загружает документацию и данные каталога в corpus/manifest.json.

• npm run build:map: Преобразует манифест в активный граф зависимостей, сохраняемый в corpus/system-map.yaml.

• npm run build: Выполняет полный конвейер и компилирует TypeScript.

• npm run test: Запускает модульные тесты с использованием встроенного тестового раннера Node.js.

🧩 Карта системы и catalog-info.yaml

Corpus автоматически генерирует глобальный граф зависимостей сервисов вашей организации. Чтобы участвовать в карте системы, каждый репозиторий должен содержать файл catalog-info.yaml в своём корне, соответствующий формату описания Backstage.

Поскольку Corpus действует как процессор каталога Backstage, он извлекает сущности любого типа (Component, API, System, Group) и автоматически устанавливает двунаправленные связи. Если ваш Component определяет owner: group:auth-team и providesApis: [api:auth-api], Corpus автоматически генерирует рёбра ownedBy/ownerOf и providesApi/apiProvidedBy, чтобы ИИ-агенты могли нативно перемещаться по всему графу сервисов вашей организации.

Пример catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-auth-service
  description: Handles user authentication and token generation
spec:
  type: service
  lifecycle: production
  owner: group:auth-team
  providesApis:
    - api:auth-api
  dependsOn:
    - component:user-database
    - component:email-service

💡 Рекомендации и философия

Чтобы получить максимальную отдачу от Corpus и ваших ИИ-агентов, мы рекомендуем следующие практики экосистемы:

1. Держите документацию рядом с кодом: Документация должна находиться в репозитории рядом с кодом. Лучшее место для описания работы системы — непосредственно рядом с самой системой. Corpus автоматически подхватывает docs/**/*.md и adr/**/*.md во всех ваших репозиториях.

2. Центральный вики-репозиторий: Если у вас есть общеорганизационные архитектурные решения, RFC или стандарты качества кода, охватывающие несколько систем, храните их в центральном «вики»-репозитории в виде markdown-файлов. Corpus отлично их агрегирует.

3. Синергия со Spotify Backstage: Если вы используете Backstage, Corpus — идеальный компаньон.

   • Backstage — это внутренний портал разработчика (IDP), созданный для людей, предоставляющий богатый веб-интерфейс.

   • Corpus — это IDP, созданный для ИИ-агентов, предоставляющий тот же самый контекст через MCP. Поскольку Corpus нативно разбирает стандартные файлы catalog-info.yaml, дублирование работы исключено. Если ваши команды уже определяют теги dependsOn, lifecycle и owner для Backstage, Corpus автоматически подхватывает их и преобразует в активный граф, по которому могут перемещаться ИИ-агенты.

4. Частые автоматические обновления: Корпус задуман как живой, дышащий снимок вашей организации. Запуск скриптов сборки (npm run build) повторно загружает и перестраивает корпус локально. Поскольку это простой скрипт, обращающийся к API, для сборки он потребляет ноль токенов LLM. В идеале Corpus должен развёртываться централизованно внутри вашей компании с использованием cron-задачи (например, GitHub Action) для пересборки manifest.json каждую ночь и распространения его среди разработчиков.

🤝 Вклад в проект

Мы приветствуем ваш вклад! Пожалуйста, ознакомьтесь с нашими Рекомендациями по вкладу, чтобы узнать, как начать, настроить среду разработки и отправлять Pull Request.

Этот проект требует соблюдения Conventional Commits. Pre-commit хук автоматически форматирует ваш код с помощью Prettier и проверяет его с помощью ESLint.

Подробнее см. в Руководстве по навыку настройки.

📄 Лицензия

Corpus можно использовать бесплатно. Вся интеллектуальная собственность принадлежит Sayam Hussain.

Этот проект лицензирован в соответствии с лицензией MIT.