apifable

사양을 읽고, API를 이해하고, 자신 있게 통합하세요.

English | 繁體中文

개요

apifable은 AI가 TypeScript 프론트엔드 프로젝트에 API를 더 원활하게 통합할 수 있도록 돕는 MCP 서버입니다. API 구조를 쉽게 탐색하고, 엔드포인트를 검색하며, TypeScript 타입을 생성하여 AI 에이전트가 정확한 통합 코드를 작성하는 데 필요한 컨텍스트를 제공합니다.

Related MCP server: openapi-mcp-proxy

✨ 주요 기능

• 📦 AI용 API 컨텍스트 — AI가 API를 이해하고 작업하는 데 필요한 구조를 제공합니다.

• 📘 OpenAPI 3.0 / 3.1 지원 — 신뢰할 수 있는 정보원으로서 표준 사양과 함께 작동합니다.

• 🤖 AI 에이전트를 위한 MCP 서버 — Claude, Cursor, Windsurf에 연결하세요.

• 🔍 API 탐색 도구 — 엔드포인트를 탐색하고, 키워드로 검색하며, 전체 요청/응답 세부 정보를 검사합니다.

• 🏷️ TypeScript 타입 생성 — 프론트엔드 코드에서 바로 사용할 수 있는 TypeScript 타입 정의를 생성합니다.

시작하기

설치

apifable init을 실행하여 프로젝트 구성을 설정하세요:

npx apifable@latest init

이 명령은 프로젝트 루트에 apifable.config.json을 생성합니다. 사양 경로를 팀과 공유할 수 있도록 이 구성 파일을 버전 관리 시스템에 커밋해야 합니다.

명령이 시작된 후, **수동 파일(Manual file)**과 원격 URL(Remote URL) 중에서 선택할 수 있습니다.

1. 수동 파일

OpenAPI 사양이 이미 프로젝트 내에 있거나 사양 업데이트를 직접 관리하려는 경우 이 모드를 사용하세요.

init은 openapi.yaml과 같은 로컬 파일 경로를 묻습니다.

그런 다음 해당 경로에 OpenAPI 사양 파일을 수동으로 배치해야 합니다. 백엔드 API가 변경되면 해당 파일도 수동으로 업데이트해야 합니다.

2. 원격 URL

OpenAPI 사양을 백엔드 API 문서에서 제공하는 OpenAPI 사양 엔드포인트와 같은 안정적인 원격 URL에서 가져올 수 있는 경우 이 모드를 사용하세요.

init은 먼저 https://api.example.com/openapi.yaml과 같은 원격 URL을 묻고, 그 다음 ./openapi.yaml과 같은 로컬 출력 경로를 묻습니다.

[!NOTE] 이 모드에서 init은 다운로드된 로컬 사양 경로를 .gitignore에 자동으로 추가합니다. 이 파일은 원격 소스에서 새로 고쳐지도록 설계되었기 때문입니다.

그런 다음 다음 명령을 실행하여 원격 URL에서 로컬 경로로 OpenAPI 사양을 다운로드할 수 있습니다 (spec.url → spec.path). 사양이 변경될 때마다 다시 실행하여 새로 고치세요:

npx apifable@latest fetch

헤더

팀과 공유할 수 있는 민감하지 않은 헤더의 경우, apifable.config.json에 spec.headers를 추가하세요:

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

인증 헤더 (비밀 토큰)

원격 OpenAPI 사양을 다운로드하는 데 인증(비공개 API)이 필요한 경우, 비밀 헤더를 .apifable/auth.json에 저장하세요. 이 파일은 버전 관리 시스템에 커밋해서는 안 됩니다:

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

apifable.config.json과 .apifable/auth.json 모두 헤더 값에서 ${ENV_VAR} 구문을 지원합니다.

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

헤더 우선순위 (높은 순에서 낮은 순)

1. .apifable/auth.json 헤더 (동일한 이름의 키를 덮어씀)

2. apifable.config.json spec.headers

Claude Code

.mcp.json에 다음을 추가하세요:

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

Cursor나 Windsurf와 같은 다른 AI 에이전트의 경우, 동일한 방식으로 apifable을 MCP 서버로 구성할 수 있습니다.

사용법

API를 탐색하고 기능을 구축하는 데 사용할 수 있는 몇 가지 예시 프롬프트입니다.

API 탐색

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

기능 구축

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] 기능을 구축하기 위한 프롬프트를 작성할 때는 페이지 경로, 컴포넌트 위치, 관련 API, 따라야 할 패턴이나 예시 등 관련 컨텍스트를 포함하세요.

AI 에이전트 가이드

AI 에이전트가 apifable을 더 효과적으로 사용할 수 있도록 프로젝트의 AGENTS.md에 다음을 추가하세요:

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

위 내용은 권장되는 시작점입니다. 엔드포인트 목록 열과 타입 폴더 경로를 프로젝트에 맞게 자유롭게 조정하세요.

MCP 도구 참조

get_spec_info

API 제목, 버전, 설명, 서버, 그리고 엔드포인트 개수가 포함된 모든 태그를 반환합니다. 익숙하지 않은 사양의 형태를 파악하려면 여기서 시작하세요.

list_endpoints_by_tag

입력:

• tag (string): 필터링할 태그 이름

• limit (number, 선택 사항): 반환할 최대 엔드포인트 수

• offset (number, 선택 사항): 건너뛸 엔드포인트 수 (기본값: 0)

지정된 태그에 속하는 모든 엔드포인트를 반환합니다. 응답에는 페이지네이션을 위한 total, offset, hasMore 필드가 포함됩니다. 결과가 30개를 초과하고 limit이 지정되지 않은 경우 경고가 포함됩니다.

search_endpoints

입력:

• query (string): 검색할 키워드

• tag (string, 선택 사항): 특정 태그로 검색 제한

• limit (number, 선택 사항): 반환할 최대 결과 수 (기본값: 10)

operationId, 경로, 요약 및 설명을 대상으로 키워드 검색을 수행합니다. 결과는 관련성 순으로 정렬됩니다. 정확히 일치하는 항목이 없으면 자동으로 퍼지 검색으로 전환됩니다. 응답에는 matchType 필드("exact" 또는 "fuzzy")가 포함되며, 퍼지 결과에는 결과별 score 필드도 포함됩니다.

get_endpoint

입력 (하나 선택):

• method (string) + path (string): HTTP 메서드 및 엔드포인트 경로 (예: get + /users/{id})

• operationId (string): 작업 ID (예: listUsers)

매개변수, requestBody, 응답을 포함한 전체 엔드포인트 객체를 반환하며, 지원되는 내부 컴포넌트 $ref는 인라인으로 해결됩니다.

search_schemas

입력:

• query (string): 검색할 키워드

• limit (number, 선택 사항): 반환할 최대 결과 수 (기본값: 10)

스키마 이름 및 설명을 대상으로 키워드 검색을 수행합니다. 결과는 관련성 순으로 정렬됩니다. 정확히 일치하는 항목이 없으면 자동으로 퍼지 검색으로 전환됩니다. 응답에는 matchType 필드("exact" 또는 "fuzzy")가 포함되며, 퍼지 결과에는 결과별 score 필드도 포함됩니다. 결과가 비어 있는 경우 다음 단계를 위한 안내가 포함된 message 필드가 포함될 수 있습니다.

get_schema

입력:

• name (string): components/schemas의 스키마 이름

지원되는 내부 컴포넌트 $ref가 해결된 전체 스키마를 반환합니다.

get_types

입력 (모드 하나 선택):

• schemas (string[]): components/schemas의 스키마 이름 배열

• method (string) + path (string): HTTP 메서드 및 엔드포인트 경로

• operationId (string): 작업 ID (예: listUsers)

코드 텍스트로 독립적인 TypeScript 선언을 생성합니다. 엔드포인트 모드에서는 스키마 종속성을 수집하기 전에 지원되는 내부 컴포넌트 $ref를 따릅니다. 자동으로 전이적 종속성을 포함하며 import 문은 포함하지 않습니다.

모드 규칙:

• 호출당 정확히 하나의 모드만 사용: schemas, method + path, 또는 operationId

• 동일한 호출에서 모드를 혼합하지 마세요.

제한 사항

• 외부 $ref(예: 다른 파일이나 URL에 대한 참조)는 지원되지 않습니다.

• OpenAPI 2.0(Swagger)은 지원되지 않습니다. OpenAPI 3.0 및 3.1 사양만 지원됩니다.

후원

이 패키지가 도움이 되었다고 생각하신다면, 제 작업을 지원하기 위해 후원자가 되는 것을 고려해 주세요~ 후원해 주시면 제 주요 프로젝트에 귀하의 아바타가 표시됩니다.

크레딧

• @reapi/mcp-openapi — 초기 영감을 주었습니다.

라이선스

MIT LICENSE

Star History