Corpus

Corpus는 조직의 모든 저장소에 걸친 문서를 집계하고, Spotify Backstage 카탈로그 엔터티를 사용하여 실시간 시스템 맵을 구축하며, 이를 강력한 Model Context Protocol (MCP) 서버 뒤에 제공합니다.

AI 에이전트(Claude, Copilot 등)에게 아키텍처, 서비스 소유권, 문서, 코드를 이해하는 데 필요한 총체적인 맥락을 한곳에서 제공하세요!

✨ 기능

• 🗺️ 자동 생성 엔터티 그래프: Backstage catalog-info.yaml 엔터티(Components, APIs, Systems, Users)를 완전히 파싱하고 잘 알려진 관계(예: ownerOf/ownedBy, providesApi/apiProvidedBy)를 사용하여 양방향 관계 그래프를 생성합니다.

• 📖 중앙 집중식 문서 검색: 조직 전체의 README.md, docs/**/*.md, adr/**/*.md 및 AI 스킬을 빠르게 어휘 검색합니다.

• 🔍 전역 코드 검색: GitHub Code Search API를 통해 모든 조직 저장소에서 키워드를 검색합니다.

• 💬 이슈 및 PR 컨텍스트: GitHub 검색 API를 프록시하여 조직 전체의 토론, 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):

  • 클래식 토큰: 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

🤖 AI 클라이언트에 등록

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는 조직 서비스의 전역 의존성 그래프를 자동으로 생성합니다. 시스템 맵에 참여하려면 각 저장소의 루트에 Backstage Descriptor Format을 따르는 catalog-info.yaml 파일이 있어야 합니다.

Corpus는 Backstage 카탈로그 프로세서처럼 작동하므로 모든 엔터티 유형(Component, API, System, Group)을 추출하고 양방향 관계를 자동으로 연결합니다. Component가 owner: group:auth-team 및 providesApis: [api:auth-api]를 정의하는 경우, Corpus는 ownedBy/ownerOf 및 providesApi/apiProvidedBy 엣지를 자동으로 생성하여 AI 에이전트가 조직의 전체 서비스 그래프를 기본적으로 탐색할 수 있게 합니다.

예제 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와 AI 에이전트를 최대한 활용하려면 다음 생태계 관행을 권장합니다:

1. 문서를 코드와 가까이 유지하세요: 문서는 코드 옆의 저장소에 있어야 합니다. 시스템이 어떻게 작동하는지 문서화하는 가장 좋은 위치는 시스템 바로 옆입니다. Corpus는 모든 저장소에서 docs/**/*.md 및 adr/**/*.md를 자동으로 수집합니다.

2. 중앙 Wiki 저장소: 여러 시스템에 걸친 회사 차원의 아키텍처 결정, RFC 또는 코드 품질 표준이 있다면 중앙 "Wiki" 저장소에 마크다운 파일로 보관하세요. Corpus가 완벽하게 집계합니다.

3. Spotify Backstage와의 시너지: Backstage를 사용한다면 Corpus는 완벽한 동반자입니다.

   • Backstage는 사람을 위해 구축된 내부 개발자 포털(IDP)로, 풍부한 웹 UI를 제공합니다.

   • Corpus는 AI 에이전트를 위해 구축된 IDP로, MCP를 통해 동일한 맥락을 그대로 노출합니다. Corpus가 표준 catalog-info.yaml 파일을 기본적으로 파싱하므로 중복 작업이 전혀 없습니다. 팀에서 이미 Backstage를 위해 dependsOn, lifecycle, owner 태그를 정의하고 있다면, Corpus가 자동으로 이를 수집하여 AI 에이전트가 탐색할 수 있는 활성 그래프로 변환합니다.

4. 빈번한 자동 업데이트: Corpus는 조직의 살아 숨 쉬는 스냅샷을 의미합니다. 빌드 스크립트(npm run build)를 실행하면 로컬에서 코퍼스를 다시 가져와 재구축합니다. 단순한 API 스크래핑 스크립트이므로 빌드에 LLM 토큰을 전혀 사용하지 않습니다. 이상적으로 Corpus는 cron 작업(예: GitHub Action)을 사용하여 매일 밤 manifest.json을 재구축하고 개발자에게 배포하는 방식으로 회사 내 중앙에 배포되어야 합니다.

🤝 기여

기여를 환영합니다! 시작하는 방법, 개발 환경 설정, Pull Request 제출에 대한 자세한 내용은 기여 가이드라인을 참조하세요.

이 프로젝트는 Conventional Commits를 준수합니다. pre-commit 훅이 Prettier로 코드 형식을 자동 지정하고 ESLint로 검사합니다.

자세한 내용은 셋업 스킬 가이드를 참조하세요.

📄 라이선스

Corpus는 무료로 사용할 수 있습니다. 모든 지적 재산권은 Sayam Hussain 소유입니다.

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.