# API Skill MCP

[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

## 로컬 Codex 설정

API Skill은 stdio MCP 서버로 실행됩니다.

```bash
node /Users/dobby/dev/apiskill/scripts/mcp-server.mjs
```

다음 설정을 `/Users/dobby/.codex/config.toml`에 추가합니다. Codex 클라이언트가 프로젝트 설정을 읽는다면 프로젝트 수준 `.codex/config.toml`을 유지할 수도 있습니다.

```toml
[mcp_servers.apiskill]
command = "node"
args = ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"]
cwd = "/Users/dobby/dev/apiskill"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
```

캐시 환경 변수를 설정하지 않으면 MCP, Web, CLI는 모두 같은 `~/.apiskill/cache`를 사용합니다. 프로젝트별로 분리할 때는 세 프로세스에 동일한 절대 경로의 `APISKILL_CACHE_DIR`를 설정하세요.

Codex를 재시작하고 `/mcp`를 실행합니다. `apiskill`과 아래 도구들이 보여야 합니다.

## 읽기 도구

- `apiskill_check`: 사용 가능한 캐시된 OpenAPI 문서가 있는지 확인하고, 없으면 가져오기 예시를 반환합니다.
- `apiskill_help`: MCP 도움말, 사용 가능한 도구, 가져오기 예시를 표시합니다.
- `apiskill_list_versions`: 캐시된 버전을 나열합니다.
- `apiskill_search_endpoints`: 엔드포인트 요약을 검색합니다.
- `apiskill_query_api`: CLI와 같은 query입니다. 단일 매치는 JSON, raw endpoint data, CLI config를 반환할 수 있습니다.
- `apiskill_get_endpoint`: 하나의 엔드포인트에 대해 파라미터, 요청 본문, 응답, 수동 설정, 선택적 raw operation을 가져옵니다.
- `apiskill_get_ai_context`: AI가 사용하기 좋은 Markdown을 가져옵니다.
- `apiskill_get_schema`: 이름 있는 schema를 펼칩니다.

## 쓰기 도구

아래 도구는 `cache/latest-import.json`과 `cache/versions/`를 수정합니다.

- `apiskill_import_url`: 직접 OpenAPI JSON/YAML URL을 가져옵니다.
- `apiskill_crawl_openapi`: Swagger UI / Knife4j / Redoc을 크롤링하고 발견한 문서를 가져옵니다.
- `apiskill_import_file`: 로컬 JSON/YAML 파일을 가져옵니다.
- `apiskill_import_curl`: curl 명령을 실행하고 그 OpenAPI 응답을 가져옵니다.
- `apiskill_create_document`: 처음부터 API 문서를 작성하기 위한 빈 OpenAPI 문서 버전을 생성합니다.
- `apiskill_create_api`: 수동 API 작업을 생성합니다.
- `apiskill_edit_api`: 수동 API 작업을 편집/교체합니다.
- `apiskill_delete_api`: API 작업을 삭제합니다.

## 처음부터 작성하기

프로젝트에 아직 상위 문서가 없다면 agent에게 먼저 `apiskill_create_document`를 호출하게 합니다.

```json
{
  "title": "My API",
  "version": "1.0.0",
  "description": "Internal service contract"
}
```

그 다음 `apiskill_create_api`로 엔드포인트를 추가하고, `apiskill_edit_api`로 수정하며, `apiskill_get_endpoint` 또는 `apiskill_query_api`로 확인합니다. 이렇게 하면 제3자 OpenAPI 소스가 없어도 AI 도구가 로컬 API 계약을 생성하고 지속적으로 관리할 수 있습니다.

## 검증

```bash
npm run mcp
```

프로토콜 수준 검증은 서버를 initialize한 뒤 `tools/list`, `apiskill_check`, `apiskill_list_versions`를 차례로 호출하면 됩니다. 서버는 `serverInfo.name = apiskill-mcp`를 반환하고 `apiskill_*` 도구를 나열해야 합니다.

## 향후 서버 배포

현재 구성은 로컬 stdio입니다. 서버 배포에서는 SSH/원격 실행기를 통해 같은 stdio 서버를 시작하고 서버 측 `APISKILL_ROOT`와 `APISKILL_CACHE_DIR`를 설정하거나, 같은 shared core 모듈을 호출하는 Streamable HTTP MCP wrapper를 추가할 수 있습니다. 도구 이름과 payload 의미는 안정적으로 유지하세요.