MCP 모듈 코드 표준

코드 표준이 중요한 이유

우리가 출시하는 모든 커넥터는 동일하게 보입니다. 그것은 우연이 아니라 규율입니다. 두 번째 통합이 도착할 때, 각 MCP 모듈이 동일한 구조, 명명, 오류 계약을 따르기 때문에 에이전트의 역량을 테스트, 감사, 교체하기 쉽습니다.

이 문서는 IdeaBosque 오케스트레이션 백본 내의 모든 MCP 모듈에 대한 표준을 정의합니다. 디렉토리 레이아웃, 도구 등록, 입출력 스키마, 오류 처리, 속도 제한, 감사 로깅, PII 경계 처리를 다룹니다.

디렉토리 구조

각 MCP 모듈은 일관된 레이아웃으로 app/mcp_modules/ 아래 자체 디렉토리에 있습니다:

app/mcp_modules/<slug>/
  __init__.py
  module.py          # 도구 등록 + 핸들러
  schemas.py         # 입출력 Pydantic 모델
  tests/
    test_module.py
  README.md

도구 등록

각 모듈은 표준 인터페이스를 통해 도구를 등록합니다. 오케스트레이션 백본은 register_tools() 진입점을 스캔하여 도구를 발견합니다 — 수동 와이어링이 필요 없습니다.

def register_tools(registrar):
    """이 모듈이 제공하는 모든 도구를 등록합니다."""
    registrar.tool(
        name="search_catalog",
        description="SKU 또는 이름으로 공급업체 카탈로그 검색",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # 분당 호출 수
    )

오류 처리

모듈은 날 문자열이 아닌 타입화된 예외를 발생시켜야 합니다. 백본은 MCPToolError 서브클래스를 잡아 에이전트가 추론할 수 있는 구조화된 응답으로 변환합니다:

• MCPAuthError — 자격 증명 누락 또는 만료
• MCPRateLimitError — 업스트림 속도 제한 도달
• MCPTimeoutError — 업스트림 호출이 구성된 타임아웃을 초과
• MCPValidationError — 입력이 스키마 검증을 통과하지 못함
• MCPUpstreamError — 업스트림이 오류 상태를 반환

속도 제한

각 도구는 등록 호출에서 자체 속도 제한을 선언합니다. 백본은 에이전트별, 도구별, 윈도우별로 이를 적용합니다. 제한에 도달하면 에이전트는 Retry-After 헤더가 있는 429 응답을 받습니다 — 충돌하거나 맹목적으로 재시도하지 않습니다.

감사 로깅

각 도구 호출은 다음과 함께 로깅됩니다: 타임스탬프, 에이전트 ID, 도구 이름, 입력 해시(원시 입력이 아닌 — PII 경계), 출력 상태, 지속 시간, 업스트림 시스템. 로그는 구조화된 JSON로 작성되고 관측 가능성 파이프라인으로 전송됩니다.

"모든 도구 호출이 로깅되고 감사 가능"은 나중에 추가하는 기능이 아닙니다. 표준이 가장 먼저 요구하는 것입니다.

PII 경계 처리

모듈은 어떤 입력 필드에 PII가 포함되는지 선언해야 합니다. 백본은 로깅 전에 이 필드들을 해시하고, 원시 PII를 감사 파이프라인에 보내지 않습니다. PII 필드는 스키마에서 표시됩니다:

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

pii=True가 설정되면, 감사 로거는 값을 SHA-256 해시로 대체합니다. 도구 핸들러는 여전히 원시 값을 받습니다 — PII 처리는 로깅 경계에서 강제되며, 비즈니스 로직 내부가 아닙니다.