Pyrus AI 생태계 — MCP 인프라

이 저장소는 Pyrus MCP 인프라 서비스와 이를 지원하는 AI 엔지니어링 팀의 구현 및 거버넌스 본거지입니다. 또한 향후 Knowledge MCP에 대한 아키텍처 명세와 로드맵을 포함하며, 이는 별도의 데이터 저장소와 라이프사이클을 가진 독립적인 서비스입니다.

제품 경계

AI clients / employees
        |
        +---------------------+
        |                     |
        v                     v
   Pyrus MCP             Knowledge MCP
   Pyrus actions         canonical knowledge
        |                     |
        v                     v
     Pyrus API          PostgreSQL/pgvector
        ^                     ^
        |                     |
        +------- PyrusBot ----+
             orchestration

Pyrus MCP

권한이 있는 직원/AI 호스트가 MCP를 통해 Pyrus 작업을 수행할 수 있도록 하는 프로덕션 등급의 외부 서비스입니다. 독립적으로 배포 가능하며 개발자 워크스테이션에 의존해서는 안 됩니다.

Knowledge MCP

정식 버전 관리 문서, 증거/계보, 의미론적 임베딩, 하이브리드 검색 및 Pyrus MCP를 통한 Pyrus 지식 베이스로의 통제된 게시를 위한 별도의 MCP 서비스입니다.

PyrusBot

두 MCP를 모두 소비하는 미래의 오케스트레이션/애플리케이션 계층입니다. 인프라 계약을 변경하지 않고 나중에 채팅 봇, CLI, 웹 유틸리티 또는 IDE 어댑터가 될 수 있습니다.

Related MCP server: MCP Gateway

현재 우선순위

Pyrus MCP 프로덕션 준비가 최우선입니다. Knowledge MCP는 병렬로 명세되지만 계약이 승인된 후에 구현됩니다. PyrusBot 통합은 안정적인 인프라 계약 이후에 진행됩니다.

규범 문서

• IMPLEMENTATION_PLAN.md — 규범적 구현 진입점.

• docs/architecture/system-architecture-v2.md — 전체 시스템 아키텍처.

• docs/architecture/contracts-v2.md — MCP, Pyrus API, 보안, 웹훅 및 Knowledge 계약.

• docs/planning/production-roadmap-v2.md — 단계별 로드맵 및 병렬화 규칙.

• tasks/registry.yaml — 소유자, 검토자, 게이트 및 종속성이 있는 실행 가능한 작업 그래프.

• contracts/pyrus-tool-catalog.yaml — 복구 가능한 레거시 호환성 카탈로그; 현재 레거시 증거가 복구될 때까지 차단됨.

• docs/qa/gates.md — 병합/릴리스/프로덕션 승인 게이트.

• docs/ai-team/agent-registry.yaml — 엔지니어링 역할 및 권한.

현재 주요 차단 항목

1. 이전 계획은 pyrus_mcp_tools_spec.json 및 inventory.json을 참조했지만, 해당 아티팩트는 현재 저장소에 존재하지 않습니다. 1:1 패리티를 선언하기 전에 정확한 레거시 계약을 복구해야 합니다.

2. 보이는 계획에는 "61개 도구"라고 명시되어 있지만, 현재 보이는 그룹화된 목록은 해당 숫자와 독립적으로 일치하지 않습니다. 따라서 정확한 레거시 개수와 이름은 P0 계약 복구 작업입니다.

3. 단일 SERVER_AUTH_TOKEN은 적절한 다중 사용자 프로덕션 권한 부여 모델이 아닙니다. 목표는 MCP/OAuth 호환 베어러 인증, 대상 검증, 범위, 테넌트 바인딩, 취소 및 감사입니다.

4. SQLite는 로컬 개발 옵션이며, 내구성 있는 프로덕션 시스템 기록이 아닙니다.

엔지니어링 스택

Pyrus MCP

Python 3.11+ 정책; uv; FastMCP; Streamable HTTP; 로컬 테스트용 stdio; Pydantic; httpx; pytest; Ruff; 정적 타이핑; PostgreSQL; 선택적 Redis; Docker; GitHub Actions; 외부 비밀 관리.

Knowledge MCP

Python + FastMCP; PostgreSQL + pgvector; 대형/원시 아티팩트를 위한 객체 스토리지; 모델/버전 레코드가 있는 임베딩 제공자 어댑터; 백그라운드 인덱싱/임베딩 작업; 선택적 Redis; 동일한 프로덕션 보안 및 관찰 가능성 규율.

개발 모델

모든 구현 항목에는 하나의 기본 실행자, 독립적인 검토자 및 명시적인 게이트 소유자가 있습니다. 작업은 독립적으로 테스트 가능한 결과를 두 개 이상 포함할 때마다 분할됩니다. 새로운 발견 사항은 범위를 조용히 확장하는 대신 연결된 작업을 생성합니다.

프로덕션 릴리스는 아키텍처, 계약, 보안, QA, 지속성, 관찰 가능성, 스테이징 및 릴리스 검사에 의해 게이트됩니다.

유용한 명령어

node scripts/dashboard-server.mjs
# Open http://localhost:4748/

대시보드는 작업 레지스트리에 대한 인터페이스입니다. 레지스트리와 위 문서가 진실의 원천으로 남습니다.