OpenAPI-MCP: AI aracınızın mevcut API belgelerine sahip herhangi bir API'ye erişmesini sağlayan Dockerize MCP Sunucusu

MCP araç tanımlarını doğrudan bir Swagger/OpenAPI belirtim dosyasından oluşturun.

OpenAPI-MCP, bir swagger.json veya openapi.yaml dosyasını okuyan ve karşılık gelen Model Context Protocol (MCP) araç setini oluşturan bir dockerize MCP sunucusudur. Bu, Cursor gibi MCP ile uyumlu istemcilerin standart OpenAPI belirtimleriyle tanımlanan API'lerle etkileşime girmesini sağlar. Artık AI aracınızı, sadece OpenAPI/Swagger belirtimini sağlayarak herhangi bir API'ye erişebilir hale getirebilirsiniz - ek kodlama gerekmez.

İçindekiler

• Neden OpenAPI-MCP?
• Özellikler
• Kurulum
  • Önceden Derlenmiş Docker Hub İmajını Kullanma (Önerilen)
  • Yerel Olarak Derleme (İsteğe Bağlı)
• Weatherbit Örneğini Çalıştırma (Adım Adım)
• Komut Satırı Seçenekleri
  • Ortam Değişkenleri

Demo

Demoyu kendiniz çalıştırın: Weatherbit Örneğini Çalıştırma (Adım Adım)

Neden OpenAPI-MCP?

• Standart Uyumluluğu: Mevcut OpenAPI/Swagger belgelerinizi kullanın.
• Otomatik Araç Oluşturma: Her endpoint için manuel yapılandırma olmadan MCP araçları oluşturun.
• Esnek API Anahtarı Yönetimi: Proxy API'si için API anahtarı doğrulamasını güvenli bir şekilde yönetin ve anahtarları MCP istemcisine sunmayın.
• Yerel ve Uzak Belgeler: Yerel belirtim dosyaları veya uzak URL'ler ile çalışır.
• Dockerize Araç: Docker ile konteynerize hizmet olarak kolayca dağıtın ve çalıştırın.

Özellikler

• OpenAPI v2 (Swagger) & v3 Desteği: Standart belirtim biçimlerini ayrıştırır.
• Şema Oluşturma: OpenAPI işlem parametrelerinden ve request/response tanımlarından MCP araç şemaları oluşturur.
• Güvenli API Anahtarı Yönetimi:
  • API anahtarlarını komut satırı yapılandırmasına dayalı olarak isteklere enjekte eder (header, query, path, cookie).
    • API anahtarlarını doğrudan bayraklardan (--api-key), ortam değişkenlerinden (--api-key-env) veya yerel belgelerle birlikte bulunan .env dosyalarından yükler.
    • API anahtarlarını son MCP istemcisinden (ör. AI asistanı) gizli tutar.
• Sunucu URL'si Algılaması: Belirtimden sunucu URL'lerini araç etkileşimleri için temel olarak kullanır (geçersiz kılınabilir).
• Filtreleme: Belirli işlemleri veya etiketleri dahil etme/dışlama seçenekleri (--include-tag, --exclude-tag, --include-op, --exclude-op).
• Request Header Enjeksiyonu: REQUEST_HEADERS ortam değişkeni aracılığıyla özel başlıklar geçirin (ek kimlik doğrulama, izleme vb. için).

Kurulum

Docker

Bu aracı çalıştırmanın önerilen yolu Docker aracılığıyladır.

Önceden Derlenmiş Docker Hub İmajını Kullanma (Önerilen)

Alternatif olarak, Docker Hub üzerinde mevcut olan önceden derlenmiş imajı kullanabilirsiniz.

1. İmajı Çekin:

   docker pull ckanthony/openapi-mcp:latest
   

2. Konteyneri Çalıştırın: Yukarıdaki docker run örneklerini izleyin, ancak openapi-mcp:latest yerine ckanthony/openapi-mcp:latest kullanın.

Yerel Olarak Derleme (İsteğe Bağlı)

1. Docker İmajını Yerel Olarak Derleyin:

   # Depo kökü klasörüne gidin
   cd openapi-mcp
   # Docker imajını derleyin (istediğiniz şekilde etiketleyin, ör. openapi-mcp:latest)
   docker build -t openapi-mcp:latest .
   

2. Konteyneri Çalıştırın: Konteyneri çalıştırırken OpenAPI belirtimini ve gerekli API anahtarı yapılandırmasını sağlamanız gerekir.

   • Örnek 1: Yerel belirtim dosyası ve .env dosyası kullanma:

     • OpenAPI belirtim dosyanızı içeren bir dizin oluşturun (ör. ./my-api, openapi.json veya swagger.yaml içerir).
     • API bir anahtar gerektiriyorsa, aynı dizinde bir .env dosyası oluşturun (ör. ./my-api/.env) ve API_KEY=your_actual_key yazın (--api-key-env bayrağı farklıysa API_KEY değiştirin).

     docker run -p 8080:8080 --rm \\
         -v $(pwd)/my-api:/app/spec \\
         --env-file $(pwd)/my-api/.env \\
         openapi-mcp:latest \\
         --spec /app/spec/openapi.json \\
         --api-key-env API_KEY \\
         --api-key-name X-API-Key \\
         --api-key-loc header
     

     (İhtiyaç doğrultusunda --spec, --api-key-env, --api-key-name, --api-key-loc ve -p ayarlayın.)

   • Örnek 2: Uzak belirtim URL'si ve doğrudan ortam değişkeni kullanma:

     docker run -p 8080:8080 --rm \\
         -e SOME_API_KEY="your_actual_key" \\
         openapi-mcp:latest \\
         --spec https://petstore.swagger.io/v2/swagger.json \\
         --api-key-env SOME_API_KEY \\
         --api-key-name api_key \\
         --api-key-loc header
     

   • Anahtar Docker Run Seçenekleri:

     • -p <host_port>:8080: Host üzerindeki bir portu konteynerın varsayılan 8080 portuna eşleyin.
     • --rm: Çıkışında konteyneri otomatik olarak kaldırın.
     • -v <host_path>:<container_path>: Belirtim içeren yerel bir dizini konteynere monte edin. Mutlak yollar veya $(pwd)/... kullanın. Yaygın konteyner yolu: /app/spec.
     • --env-file <path_to_host_env_file>: Yerel dosyadan ortam değişkenlerini yükleyin (API anahtarları vb.). Yol host üzerindedir.
     • -e <VAR_NAME>="<value>": Tek bir ortam değişkenini doğrudan geçirin.
     • openapi-mcp:latest: Yerel olarak derlediğiniz imajın adı.
     • --spec ...: Gerekli. Belirtim dosyasının yolu konteyner içinde (ör. /app/spec/openapi.json) veya genel bir URL.
     • --port 8080: (İsteğe Bağlı) Sunucunun dinlediği dahili portu değiştirin (-p içindeki konteyner portuyla eşleşmelidir).
     • --api-key-env, --api-key-name, --api-key-loc: Hedef API'nin API anahtarı gerektirmesi durumunda gereklidir.
     • (Tüm komut satırı seçenekleri için --help bayrağını kullanarak bkz: docker run --rm openapi-mcp:latest --help)

Weatherbit Örneğini Çalıştırma (Adım Adım)

Bu depo, Weatherbit API kullanılan bir örnek içermektedir. İşte genel Docker imajını kullanarak nasıl çalıştırılacağı:

1. OpenAPI Belgelerini Bulma (İsteğe Bağlı Bilgi): Birçok genel API'nin OpenAPI/Swagger belirtimi çevrimiçi olarak mevcuttur. Bunları keşfetmek için harika bir kaynak APIs.guru'dur. Bu örnekte kullanılan Weatherbit belirtimi (weatherbitio-swagger.json) oradan alınmıştır.

2. Weatherbit API Anahtarı Alın:

   • Weatherbit.io adresine gidin ve bir hesap oluşturun (ücretsiz seviye sunmaktadırlar).
   • Weatherbit hesabı panonuzdan API anahtarınızı bulun.

3. Bu Depoyu Klonlayın: Bu depodan örnek dosyalara ihtiyacınız vardır.

   git clone https://github.com/ckanthony/openapi-mcp.git
   cd openapi-mcp
   

4. Ortam Dosyasını Hazırlayın:

   • Örnek dizinine gidin: cd example/weather
   • Örnek ortam dosyasını kopyalayın: cp .env.example .env
   • Yeni .env dosyasını düzenleyin ve YOUR_WEATHERBIT_API_KEY_HERE yerine Weatherbit'ten aldığınız gerçek API anahtarını koyun.

5. Docker Konteynerini Çalıştırın: openapi-mcp kök dizininden (örnek klasörünü içeren), aşağıdaki komutu çalıştırın:

   docker run -p 8080:8080 --rm \\
       -v $(pwd)/example/weather:/app/spec \\
       --env-file $(pwd)/example/weather/.env \\
       ckanthony/openapi-mcp:latest \\
       --spec /app/spec/weatherbitio-swagger.json \\
       --api-key-env API_KEY \\
       --api-key-name key \\
       --api-key-loc query
   

   • -v $(pwd)/example/weather:/app/spec: Yerel example/weather dizinini (belirtim ve .env dosyasını içeren) konteynerdeki /app/spec'e monte eder.
   • --env-file $(pwd)/example/weather/.env: Docker'ı .env dosyanızdan ortam değişkenlerini (API_KEY özellikle) yüklemesi için belirtir.
   • ckanthony/openapi-mcp:latest: Genel Docker imajını kullanır.
   • --spec /app/spec/weatherbitio-swagger.json: Konteynerdeki belirtim dosyasını gösterir.
   • --api-key-* bayrakları, aracın API anahtarını nasıl enjekte etmesi gerektiğini yapılandırır (API_KEY env değişkeninden okunur, adı key, sorgu dizinine yerleştirilir).

6. MCP Sunucusuna Erişin: MCP sunucusu artık uyumlu istemciler için http://localhost:8080 adresinde çalışıyor ve erişilebilir olmalıdır.

Docker Compose Kullanma (Örnek):

example/ dizininde sağlanan bir docker-compose.yml dosyası, yerel olarak derlenmiş imaj kullanarak Weatherbit API örneğini çalıştırmayı göstermektedir.

1. Ortam Dosyasını Hazırlayın: example/weather/.env.example öğesini example/weather/.env öğesine kopyalayın ve gerçek Weatherbit API anahtarınızı ekleyin:

   # example/weather/.env
   API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
   

2. Docker Compose ile Çalıştırın: example dizinine gidin ve şu komutu çalıştırın:

   cd example
   # Bu, proje kökündeki Dockerfile'dan imajı yerel olarak derler
   # Docker Hub'ın genel imajını KULLANMAZ
   docker-compose up --build
   

   • --build: Docker Compose'u, hizmeti başlatmadan önce proje kökündeki Dockerfile'ı kullanarak imajı derlemesi için zorlar.
   • Compose, example/docker-compose.yml dosyasını okuyacak, imajı derleyecek, ./weather'ı monte edecek, ./weather/.env'i okuyacak ve belirtilen komut satırı argümanları ile openapi-mcp konteynerini başlatacaktır.
   • MCP sunucusu http://localhost:8080 adresinde mevcut olacaktır.

3. Hizmeti Durdur: Compose'un çalıştığı terminalde Ctrl+C basın veya başka bir terminalden example dizininden docker-compose down komutunu çalıştırın.

Komut Satırı Seçenekleri

openapi-mcp komutu aşağıdaki bayrakları kabul eder:

Bayrak	Açıklama	Tür	Varsayılan
--spec	Gerekli. OpenAPI belirtim dosyasının yolu veya URL'si.	string	(yok)
--port	MCP sunucusunu çalıştıracak port.	int	8080
--api-key	Doğrudan API anahtarı değeri (güvenlik için --api-key-env veya .env dosyasını kullanın).	string	(yok)
--api-key-env	API anahtarını içeren ortam değişken adı. Belirtim yerel ise, belirtimin dizinindeki .env dosyasını da kontrol eder.	string	(yok)
--api-key-name	Anahtar kullanılıyorsa gerekli. API anahtarı parametresinin adı (header, query, path veya cookie adı).	string	(yok)
--api-key-loc	Anahtar kullanılıyorsa gerekli. API anahtarının konumu: header, query, path veya cookie.	string	(yok)
--include-tag	Dahil edilecek etiket (tekrarlanabilir). Dahil etme bayrakları kullanılıyorsa yalnızca dahil edilen öğeler açığa çıkar.	string slice	(yok)
--exclude-tag	Dışlanacak etiket (tekrarlanabilir). Dışlamalar dahil etmelerden sonra uygulanır.	string slice	(yok)
--include-op	Dahil edilecek Operation ID (tekrarlanabilir).	string slice	(yok)
--exclude-op	Dışlanacak Operation ID (tekrarlanabilir).	string slice	(yok)
--base-url	Belirtimden algılanan hedef API sunucusu taban URL'sini el ile geçersiz kılın.	string	(yok)
--name	Oluşturulan MCP araç setinin varsayılan adı (belirtimde başlık yoksa kullanılır).	string	"OpenAPI-MCP Tools"
--desc	Oluşturulan MCP araç setinin varsayılan açıklaması (belirtimde açıklama yoksa kullanılır).	string	"Tools generated from OpenAPI spec"

Not: Bu listeyi --help bayrağı ile çalıştırarak alabilirsiniz (ör. docker run --rm ckanthony/openapi-mcp:latest --help).

Ortam Değişkenleri

• REQUEST_HEADERS: Hedef API'ye yapılan tüm giden isteklere özel başlıklar eklemek için bu ortam değişkenini bir JSON dizesine ayarlayın (ör. '{"X-Custom": "Value"}').