YApi MCP Bridge

Model Context Protocol（MCP） 기반의 YApi Server로, MCP를 지원하는 AI 클라이언트가 YApi 인터페이스를 조회, 검색, 생성 및 업데이트할 수 있게 해줍니다.

기능

현재 제공되는 도구는 다음과 같습니다:

Server는 삭제 도구를 제공하지 않아 AI 클라이언트가 되돌릴 수 없는 작업을 실수로 실행하는 것을 방지합니다.

Related MCP server: YApi MCP Server

npm으로 설치

저장소를 클론할 필요 없이 바로 실행할 수 있습니다:

npx -y yapi-mcp-bridge

전역 설치도 가능합니다:

npm install -g yapi-mcp-bridge
yapi-mcp-bridge

전역 설치 후 다음 명령어로 도구 호출 통계를 확인할 수 있습니다:

yapi-mcp-stats

소스 코드에서 설치

환경 요구 사항

• Node.js 18 이상

• 정상적으로 접근 가능한 YApi 인스턴스

• 해당 프로젝트에 접근 권한이 있는 YApi Cookie

소스 코드에서 실행하려면 pnpm 10 이상도 필요합니다. macOS에서는 Homebrew로 Node.js와 pnpm을 설치할 수 있습니다:

brew install node pnpm

의존성 설치

프로젝트 디렉터리로 이동한 후 실행:

pnpm install

YApi 구성

환경 변수 예시 복사:

cp .env.example .env

.env 편집:

YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;

매개변수 설명:

• YAPI_HOST: YApi 서비스 주소, 프로토콜과 도메인만 입력하고 /api는 포함하지 마세요.

• YAPI_COOKIE: YApi 접근 시 사용하는 전체 Cookie 문자열.

• YAPI_LOG_FILE: 선택적 로그 파일 경로, 기본값은 ~/.yapi-mcp/logs/yapi-mcp.log.

YApi에 로그인한 후 브라우저 개발자 도구의 Network 패널에서 아무 YApi 요청을 선택하고 Request Headers에서 Cookie를 복사할 수 있습니다. Cookie는 로그인 자격 증명과 동일하므로 Git에 커밋하거나 다른 사람과 공유하지 마세요. 이 프로젝트는 기본적으로 .env를 무시하도록 설정되어 있습니다.

Server 시작

프로젝트 루트 디렉터리에서 실행:

pnpm start

이것은 stdio MCP Server입니다. 직접 시작하면 일반적인 HTTP 페이지가 없고 대화형 프롬프트도 출력되지 않습니다. MCP 클라이언트가 표준 입력/출력을 통해 통신하기를 기다립니다.

시작에 성공하면 Server는 stderr로 유사한 정보를 출력하며, MCP 통신에 사용되는 stdout을 오염시키지 않습니다:

[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log

테스트 실행:

pnpm test

MCP 클라이언트 연동

npm 패키지를 사용할 때, stdio MCP Server를 지원하는 클라이언트에 다음 구성을 추가하세요:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-bridge"
      ],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}

소스 코드로 시작하는 경우 Node.js 절대 경로 구성을 계속 사용할 수 있습니다:

{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}

구성을 수정한 후 MCP 클라이언트를 재시작하거나 다시 로드하세요. 클라이언트는 yapi_로 시작하는 9개의 도구를 발견할 수 있어야 합니다.

사용법

연동 후 자연어로 AI 클라이언트에게 YApi 작업을 지시할 수 있습니다.

프로젝트 및 인터페이스 조회

获取 YApi 项目 1922 的详情。

列出 YApi 项目 1922 的所有接口分类。

在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。

yapi_get_interface는 기본적으로 다음 일반 정보만 반환합니다:

• 인터페이스 ID, 제목, HTTP 메서드 및 경로

• 인터페이스 설명

• Path, Query, Header 및 Body 입력 매개변수

• 응답 유형 및 응답 내용

YApi 메타데이터를 확인하거나 원본 응답을 가져와야 할 때는 full: true를 명시적으로 요청할 수 있습니다:

获取 YApi 接口 5001 的原始全量数据。

인터페이스 분류 생성

在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。

인터페이스 생성

在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。

인터페이스 생성 시 필수 매개변수:

requestBody와 responseBody는 문자열로 전달해야 합니다. 내용이 JSON 또는 JSON Schema인 경우에도 먼저 문자열로 직렬화해야 합니다.

인터페이스 업데이트

把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。

인터페이스 업데이트는 인터페이스 ID와 수정할 필드만 제공하면 되며, 제공되지 않은 필드는 YApi로 전송되지 않습니다.

로그 및 호출 통계

Server는 기본적으로 로그를 다음 위치에 기록합니다:

~/.yapi-mcp/logs/yapi-mcp.log

로그는 JSON Lines 형식으로, 각 줄이 하나의 이벤트입니다. 예:

{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}

도구 로그는 도구 이름, 호출 상태 및 소요 시간만 기록하며 호출 매개변수, 인터페이스 내용, Cookie 또는 기타 자격 증명은 기록하지 않습니다.

로그가 1000개를 초과하면 Server는 자동으로 가장 오래된 300개를 삭제하여 로그 파일이 계속 커지는 것을 방지합니다.

도구 호출 빈도, 성공 수, 실패 수 및 평균 소요 시간 확인:

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

YAPI_LOG_FILE로 로그 위치를 변경할 수 있습니다. 상대 경로를 사용하면 Server의 시작 디렉터리를 기준으로 해석됩니다. MCP 클라이언트에서는 절대 경로를 구성하는 것이 좋습니다.

자주 묻는 질문

"로그인 필요" 또는 권한 없음 반환

다음 항목을 확인하세요:

• YAPI_COOKIE가 완전한지, 이미 만료되었는지.

• 현재 Cookie에 해당하는 사용자에게 프로젝트 접근 또는 편집 권한이 있는지.

• Cookie를 수정한 후 MCP Server를 재시작했는지.

클라이언트가 Server를 찾지 못함

• MCP 구성의 src/index.js가 절대 경로를 사용하는지 확인.

• command가 실행 가능한 Node.js를 가리키는지 확인.

• 프로젝트 디렉터리에서 pnpm test를 실행하여 의존성과 실행 환경이 정상인지 확인.

.env 수정 후 적용되지 않음

.env는 기본적으로 Server의 현재 작업 디렉터리에서 로드됩니다. 터미널에서 시작할 때는 프로젝트 루트에서 pnpm start를 실행하세요. MCP 클라이언트에서 시작할 때는 구성의 env를 통해 YAPI_HOST와 YAPI_COOKIE를 명시적으로 전달하는 것이 좋습니다.

프로젝트 구조

src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试

보안 주의사항

• .env 또는 YApi Cookie를 커밋하지 마세요.

• 쓰기 도구는 YApi 데이터를 실제로 수정하므로 실행 전에 프로젝트 ID, 분류 ID 및 인터페이스 ID를 확인하세요.

• 권한 범위가 최소인 YApi 계정을 사용하는 것이 좋습니다.

• 기본 로그는 사용자 디렉터리의 .yapi-mcp/logs/에 저장되며 npm 설치 디렉터리에는 기록되지 않습니다.