SpecBridge MCP

SpecBridge MCP는 OpenAPI/Huma 계약 인텔리전스를 AI 에이전트에 노출하기 위한 클론 앤 오운(clone-and-own) MCP 스타터입니다. 이 도구는 OpenAPI/Huma 사양을 에이전트가 프론트엔드나 클라이언트 코드를 변경하기 전에 사용할 수 있는 결정론적 엔드포인트 메타데이터, 스키마, 유효성 검사 팩트, 참조된 DTO 및 TypeScript 선언으로 변환합니다.

이 프로젝트는 npm에 게시하는 대신 리포지토리 우선 방식을 취합니다. 프로젝트를 복제하고, 백엔드 레지스트리를 비공개 또는 공개 사양에 맞게 조정하며, 로컬 MCP 서버를 에이전트 호스트에 등록하여 사용하십시오. 구현 방식은 다운스트림 파일 변경을 피하고, 중립적인 공개 데모 백엔드를 사용하며, 여러 주입된 백엔드를 지원하고, 추론된 헬퍼를 보장보다는 최선의 노력으로 취급함으로써 핵심을 중립적으로 유지합니다.

상태: 실험적. 이 도구 인터페이스는 로컬 자동화에 유용하지만, 리포지토리는 각 팀이 소유하고 조정하는 것을 목적으로 합니다.

간략한 역사

SpecBridge MCP는 백엔드 API 계약을 둘러싼 개발 주기를 개선하기 위해 SesameLab에서 개인 내부 도구로 시작되었습니다. 실제로 MCP를 통해 AI 에이전트에게 구조화된 OpenAPI/Huma 계약 데이터를 제공함으로써, API 문서 페이지를 직접 읽도록 요청하는 것보다 환각(hallucination) 현상이 줄어들었습니다.

제공 기능

• 하나 이상의 OpenAPI/Huma 호환 사양을 위한 구성 가능한 백엔드 레지스트리

• 실제 공개 OpenAPI URL을 사용하는 제로 구성 데모 백엔드

• JSON/YAML을 지원하는 사양 로드 및 새로 고침

• 엔드포인트 나열 및 필터링

• 다음과 같은 결정론적 팩트를 포함하는 엔드포인트 계약 번들:

  • 작업 메타데이터

  • 매개변수

  • 요청 및 응답 스키마

  • 참조된 구성 요소 스키마

  • 엔드포인트 범위의 TypeScript DTO 선언

  • required, nullable, enum, format, 배열, 맵 및 구성과 같은 유효성 검사 팩트

• 구성 요소 스키마에서 TypeScript DTO 선언 생성

• 결정론적 사양 팩트보다 부차적인 최선의 제안 헬퍼

비목표

• v1을 위해 이 프로젝트를 npm에 게시하는 것

• 일반적인 설치 가능한 CLI 추상화 제공

• 다운스트림 프론트엔드/클라이언트 리포지토리 변경

• 프레임워크별 클라이언트 또는 SDK 생성기가 되는 것

• 사양 호스팅 또는 팀 API 데이터를 원격으로 저장하는 것

요구 사항

• Node.js 18+

• pnpm 10+

설치

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

백엔드 구성

SpecBridge는 도구가 즉시 작동하도록 공개 데모 API를 가리키는 openapi.backends.json과 함께 제공됩니다.

자체 API를 사용하려면 openapi.backends.json을 편집하거나 OPENAPI_BACKENDS_FILE이 다른 JSON 파일을 가리키도록 설정하십시오.

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

구성 우선순위

도구 호출의 경우, 해당 호출에 대해 명시적인 specUrl 재정의가 먼저 시도됩니다.

백엔드 레지스트리 소스는 다음 순서로 병합되며, 나중에 오는 소스가 id를 기준으로 이전 소스를 재정의합니다:

1. 내장 공개 데모 백엔드

2. 리포지토리 로컬 openapi.backends.json (존재하는 경우)

3. OPENAPI_BACKENDS_FILE (설정된 경우)

4. OPENAPI_BACKENDS (설정된 경우)

DEFAULT_BACKEND_ID는 기본 백엔드를 선택합니다. 설정되지 않은 경우, SpecBridge는 swagger-petstore를 사용합니다.

환경 변수

• MCP_TRANSPORT: stdio 또는 http

• MCP_HTTP_HOST: HTTP 바인드 호스트

• MCP_HTTP_PORT: HTTP 포트

• MCP_HTTP_PATH: /mcp와 같은 MCP 엔드포인트 경로

• MCP_HTTP_STATELESS: 상태 비저장 HTTP 모드의 경우 true로 설정

• DEFAULT_BACKEND_ID: 기본 백엔드 ID

• OPENAPI_BACKENDS: 백엔드 구성의 JSON 배열

• OPENAPI_BACKENDS_FILE: 백엔드 구성 JSON 파일의 경로

• OPENAPI_FETCH_TIMEOUT_MS: 사양 로드를 위한 가져오기 시간 제한

• OPENAPI_CACHE_TTL_MS: 메모리 내 사양 캐시 TTL

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: 정적 Swagger UI 스크립트에서 엄격한 JSON 객체 추출을 선택합니다. 가져온 JavaScript는 절대 실행되지 않습니다.

실행

stdio 모드

pnpm mcp
# or
./mcp-server.sh

HTTP 모드

pnpm mcp:http

상태 비저장 HTTP 모드:

pnpm mcp:http:stateless

MCP 호스트 설정

명령 기반 stdio 구성

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Codex config.toml 예시

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP URL

서버 시작:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

그런 다음 호스트를 다음에 연결하십시오:

• http://127.0.0.1:3000/mcp

호스트에 세션 상태 문제가 있는 경우 --stateless 옵션으로 다시 시도하십시오.

도구

권장 흐름:

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

구성된 백엔드 대상, 기본 백엔드 ID 및 선택적 도메인 힌트를 나열합니다.

load_openapi_spec

백엔드에 대한 OpenAPI/Huma 호환 사양을 로드하거나 새로 고칩니다. 직접적인 specUrl 재정의를 지원합니다.

list_api_endpoints

선택적 태그, 메서드, 경로 부분 문자열 및 제한 필터를 사용하여 로드된 사양의 엔드에서 엔드포인트를 나열합니다.

get_endpoint_contract

결정론적 엔드포인트 계약 번들을 반환합니다: 작업 메타데이터, 매개변수, 요청 본문, 응답, 참조된 스키마, 엔드포인트 범위의 TypeScript DTO 선언, 유효성 검사 팩트 및 최선의 힌트.

generate_typescript_dto

구성 요소 스키마 이름에서 TypeScript DTO 선언을 생성하고 참조된 중첩 DTO 유형을 포함합니다.

propose_new_endpoint

현재 사양에서 발견된 패턴에 맞춰 최선의 엔드포인트 및 DTO 제안을 반환합니다. 이를 결정론적 보장이 아닌 에이전트 보조 도구로 취급하십시오.

개발

pnpm install
pnpm check
pnpm build
pnpm test

유용한 스크립트:

• pnpm check: Biome 확인

• pnpm format: Biome 형식 적용

• pnpm lint: Biome 린트 전용

• pnpm build: 깨끗한 TypeScript 빌드

• pnpm test: 모든 테스트 빌드 및 실행

• pnpm test:e2e: MCP 스모크 테스트 빌드 및 실행

클론 앤 오운(Clone-and-own) 지침

SpecBridge는 의도적으로 리포지토리 우선 방식을 취합니다. 핵심을 작게 유지하고, 백엔드 구성을 로컬에서 조정하며, 다운스트림 에이전트가 클라이언트 코드를 편집하는 방법을 결정하도록 하십시오. 팀에 사용자 지정 인증, 내부 명명 규칙 또는 추가 계약 팩트가 필요한 경우, 전역 패키지 추상화와 씨름하는 대신 복제본에 추가하십시오.