모델 컨텍스트 프로토콜(MCP) 서버로, OpenAPI 엔드포인트를 MCP 도구로 노출하며, MCP 프롬프트 및 자원에 대한 선택적 지원도 제공합니다. 이 서버는 대형 언어 모델이 MCP 프로토콜을 통해 OpenAPI 명세에 정의된 REST API를 발견하고 상호작용할 수 있도록 합니다.

📖 문서

• 사용자 가이드 - Claude 데스크톱, 커서 또는 기타 MCP 클라이언트와 함께 이 MCP 서버를 사용하려는 사용자를 위한 안내
• 라이브러리 사용 - 이 패키지를 라이브러리로 사용하는 커스텀 MCP 서버를 만드는 개발자를 위한
• 개발자 가이드 - 코드베이스 기여자 및 개발자를 위한 안내
• AuthProvider 가이드 - 상세한 인증 패턴 및 예시

---

사용자 가이드

이 섹션에서는 Claude Desktop, 커서 또는 기타 MCP 호환 도구를 통해 최종 사용자로서 MCP 서버를 사용하는 방법을 다룹니다.

개요

이 MCP 서버는 두 가지 방식으로 사용할 수 있습니다:

1. CLI 도구: 빠른 설정을 위해 명령줄 인수와 npx @ivotoby/openapi-mcp-server를 직접 사용하세요
2. 라이브러리: OpenAPIServer 클래스를 자신의 Node.js 애플리케이션에서 가져오기 및 사용자 지정 구현을 위해 사용하기

서버는 두 가지 전송 방식을 지원합니다:

OpenAPI MCP Server

A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP tools, along with optional support for MCP prompts and resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.

📖 Documentation

• User Guide - For users wanting to use this MCP server with Claude Desktop, Cursor, or other MCP clients
• Library Usage - For developers creating custom MCP servers using this package as a library
• Developer Guide - For contributors and developers working on the codebase
• AuthProvider Guide - Detailed authentication patterns and examples

---

User Guide

This section covers how to use the MCP server as an end user with Claude Desktop, Cursor, or other MCP-compatible tools.

Overview

This MCP server can be used in two ways:

1. CLI Tool: Use npx @ivotoby/openapi-mcp-server directly with command-line arguments for quick setup
2. Library: Import and use the OpenAPIServer class in your own Node.js applications for custom implementations

The server supports two transport methods:

1. Stdio Transport (default): For direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output.
2. Streamable HTTP Transport: For connecting to the server over HTTP, allowing web clients and other HTTP-capable systems to use the MCP protocol.

Quick Start for Users

Option 1: Using with Claude Desktop (Stdio Transport)

No need to clone this repository. Simply configure Claude Desktop to use this MCP server:

1. Locate or create your Claude Desktop configuration file:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the following configuration:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

3. Replace the environment variables with your actual API configuration:
   • API_BASE_URL: The base URL of your API
   • OPENAPI_SPEC_PATH: URL or path to your OpenAPI specification
   • API_HEADERS: Comma-separated key:value pairs for API authentication headers

Option 2: Using with HTTP Clients (HTTP Transport)

To use the server with HTTP clients:

1. No installation required! Use npx to run the package directly:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \