MCP 서버: 확장 가능한 OpenAPI 엔드포인트 검색 및 API 요청 도구

할 일

도커 이미지는 미리 다운로드된 모델 없이 2GB입니다. 미리 다운로드된 모델을 포함하면 3.76GB입니다!! 너무 큽니다. 누가 좀 줄여주세요.

구성

환경 변수를 통해 사용자 정의하세요. GLOBAL_TOOL_PROMPT가 중요합니다 !

OPENAPI_JSON_DOCS_URL : OpenAPI 사양 JSON에 대한 URL(기본값은 https://api.staging.readymojo.com/openapi.json )
MCP_API_PREFIX : 사용자 정의 가능한 도구 네임스페이스(기본값 "any_openapi"):지엑스피1
GLOBAL_TOOL_PROMPT : 모든 도구 설명 앞에 추가할 선택적 텍스트입니다. Claude가 도구를 정확하게 선택하도록 하는 데 필수적입니다.
# Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ...

요약

이 항목을 만든 이유 : 수백 KB 크기의 swagger openapi 문서가 포함된 개인 API를 제공하고 싶습니다.

Claude MCP는 이 크기의 파일을 처리하는 데 단순히 오류가 있습니다.
결과를 YAML로 변환하려고 했는데, 크기가 너무 작고 오류가 많습니다. 실패했습니다.
API 카테고리를 제공한 후 MCP 클라이언트(Claude Desktop)에 그룹별로 API 문서를 가져오도록 요청하려고 했습니다. 여전히 너무 커서 실패했습니다.

결국 저는 다음과 같은 해결책을 찾았습니다.

자연어(예: 제품 목록)를 사용하여 관련 API 엔드포인트를 찾기 위해 메모리 내 의미 검색을 사용합니다.
(한 엔드포인트를 하나의 청크로 저장하도록 설계했기 때문에) 완전한 엔드포인트 문서를 백만초(메모리에 있는 것처럼) 안에 반환합니다.

붐 , 이제 클로드는 모든 매개변수를 사용해 어떤 API를 호출해야 할지 알게 됐어요!

잠깐만요, 이 서버에서 실제 RESTful 요청을 하기 위해 다른 도구를 만들어야 합니다. "fetch" 서버는 작동하지 않고, 그 이유를 디버깅하고 싶지 않습니다.

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

기술적 주요 내용:

query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop)
MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

특징

🧠 원격 OpenAPI JSON 파일을 소스로 사용, 로컬 파일 시스템 접근 없음, API 변경에 대한 업데이트 필요 없음
🔍 최적화된 MiniLM-L3 모델을 사용한 의미 검색(43MB 대 원래 90MB)
🚀 비동기 지원이 가능한 FastAPI 기반 서버
🧠 엔드포인트 기반 청킹 OpenAPI 사양(100KB 이상 문서 처리), 엔드포인트 컨텍스트 손실 없음
⚡ 즉각적인 엔드포인트 검색을 위한 메모리 내 FAISS 벡터 검색

제한 사항

linux/arm/v7을 지원하지 않음(Transformer 라이브러리에서 빌드 실패)
🐢 Docker 이미지를 사용하지 않으면 콜드 스타트 페널티(모델 로딩 시 약 15초)가 발생합니다.
[사용 안 함] 현재 Docker 이미지가 모델 다운로드를 비활성화했습니다. huggingface에 대한 종속성이 있습니다. Claude Desktop을 로드할 때 모델을 다운로드하는 데 시간이 걸립니다. huggingface가 다운되면 서버가 시작되지 않습니다.
최신 도커 이미지에는 미리 다운로드된 모델이 포함되어 있습니다. 문제가 있으면 이전 버전으로 되돌리는 것이 좋습니다.

다중 인스턴스 구성 예

다중 인스턴스 구성 예시는 다음과 같습니다. 여러 API 세트에 더욱 유연하게 사용할 수 있도록 설계했습니다.

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    },
    "healthcare_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=healthcare",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for Healthcare API services efg.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

이 예에서는:

서버는 OpenAPI 문서에서 기본 URL을 자동으로 추출합니다.
- 금융 API를 위한 https://api.finance.com
- 헬스케어 API를 위한 https://api.healthcare.com
선택적으로 API_REQUEST_BASE_URL 환경 변수를 사용하여 기본 URL을 재정의할 수 있습니다.

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "API_REQUEST_BASE_URL=https://api.finance.staging.com",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude Desktop 사용 예

클로드 데스크톱 프로젝트 프롬프트:

You should get the api spec details from tools financial_api_request_schema

You task is use financial_make_request tool to make the requests to get response. You should follow the api spec to add authorization header:
Authorization: Bearer <xxxxxxxxx>

Note: The base URL will be returned in the api_request_schema response, you don't need to specify it manually.

채팅에서는 다음과 같은 작업을 할 수 있습니다.

Get prices for all stocks

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Scalable OpenAPI Endpoint Discovery and API Request Tool을 자동으로 설치하려면:

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

pip 사용하기

pip install mcp-server-any-openapi

사용 가능한 도구

서버는 다음 도구를 제공합니다(여기서 {prefix} MCP_API_PREFIX 에 의해 결정됨).

{접두사}_api_요청_스키마

의도와 일치하는 API 엔드포인트 스키마를 가져옵니다. 경로, 메서드, 매개변수, 응답 형식을 포함한 엔드포인트 세부 정보를 반환합니다.

입력 스키마:

{
    "query": {
        "type": "string",
        "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')"
    }
}

{접두사}_요청_하기

복잡한 API를 안정적으로 실행하고, 단순화된 구현으로는 실패하는 경우에 필수적입니다 . 다음을 제공합니다.

입력 스키마:

{
    "method": {
        "type": "string",
        "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
    },
    "url": {
        "type": "string",
        "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)"
    },
    "headers": {
        "type": "object",
        "description": "Request headers (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "query_params": {
        "type": "object",
        "description": "Query parameters (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "body": {
        "type": "object",
        "description": "Request body for POST, PUT, PATCH (optional)"
    }
}

응답 형식:

{
    "status_code": 200,
    "headers": {
        "content-type": "application/json",
        ...
    },
    "body": {
        // Response data
    }
}

도커 지원

다중 아키텍처 빌드

공식 이미지는 3가지 플랫폼을 지원합니다.

# Build and push using buildx
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

유연한 도구 명명

MCP_API_PREFIX 통해 도구 이름을 제어합니다.

# Produces tools with "finance_api" prefix:
docker run -e MCP_API_PREFIX=finance_ ...

지원 플랫폼

리눅스/amd64
리눅스/arm64

옵션 1: 미리 빌드된 이미지 사용(Docker Hub)

docker pull buryhuang/mcp-server-any-openapi:latest

옵션 2: 지역 개발 빌드

docker build -t mcp-server-any-openapi .

컨테이너 실행

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

주요 구성 요소

EndpointSearcher : 다음을 처리하는 핵심 클래스:
- OpenAPI 사양 구문 분석
- 의미 검색 인덱스 생성
- 엔드포인트 문서 형식
- 자연어 쿼리 처리
서버 구현 :
- 비동기 FastAPI 서버
- MCP 프로토콜 지원
- 도구 등록 및 호출 처리

소스에서 실행

python -m mcp_server_any_openapi

Claude Desktop과 통합

Claude Desktop 설정에서 MCP 서버를 구성하세요.

{
  "mcpServers": {
    "any_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

기여하다

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시( git push origin feature/amazing-feature )
풀 리퀘스트 열기

특허

이 프로젝트는 LICENSE 파일에 포함된 조건에 따라 라이센스가 부여되었습니다.

구현 노트

엔드포인트 중심 처리 : 대규모 사양을 처리하는 데 어려움을 겪는 문서 수준 분석과 달리 다음을 통해 개별 엔드포인트를 인덱싱합니다.
- 고유 식별자로서의 경로 + 방법
- 매개변수 인식 임베딩
- 응답 스키마 컨텍스트
최적화된 사양 처리 : 다음을 통해 최대 10MB(약 5,000개 엔드포인트)의 OpenAPI 사양을 처리합니다.
- 스키마 구성 요소의 지연 로딩
- 경로 항목의 병렬 구문 분석
- 선택적 임베딩 생성(중복된 설명 생략)

MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

Integrations