MCP OpenAPI Schema Explorer

OpenAPI (v3.0) ve Swagger (v2.0) spesifikasyonlarına token-verimli erişim sağlayan, MCP Resource Templates tabanlı bir MCP (Model Context Protocol) sunucusu.

Proje Hedefi

Bu projenin temel hedefi, MCP istemcilerine (Cline veya Claude Desktop gibi) tüm dosyayı LLM'nin context penceresine yüklemeden büyük OpenAPI spesifikasyonlarının yapısını ve ayrıntılarını keşfetmelerine olanak sağlamaktır. Bunu MCP Resource Templates aracılığıyla spesifikasyonun bölümlerini sunarak ve salt-okunur veri keşfi için parametreli erişim desenleri sağlayarak başarır.

Bu sunucu, spesifikasyonları hem yerel dosya yollarından hem de uzak HTTP/HTTPS URL'lerinden yüklemeyi destekler. Swagger v2.0 spesifikasyonları yükleme sırasında otomatik olarak OpenAPI v3.0'a dönüştürülür.

Not: Bu sunucu resource templates (önceden numaralandırılmış kaynaklar değil) sağlar. MCP istemcileri bu şablonlara resources/templates/list protokol yöntemi aracılığıyla erişir. Resource templates hakkında daha fazla bilgi için MCP Resource Templates belgelerine bakın.

Neden MCP Resource Templates?

Model Context Protocol hem Resources hem de Tools tanımlar.

• Resources: Veri kaynakları (dosyalar, API yanıtları gibi) temsil eder. MCP istemcileri tarafından salt-okunur erişim ve keşif için idealdirler.
  • Resource Templates: Parametreli URI'ler kullanan (örneğin, openapi://paths/{path}/{method}) özel bir kaynak türü. Tüm olası değerleri önceden numaralandırmadan dinamik erişime olanak tanır.
• Tools: Yürütülebilir eylemler veya işlevler temsil eder. LLM'ler tarafından görevleri gerçekleştirmek veya dış sistemlerle etkileşime girmek için sıklıkla kullanılır.

Tools aracılığıyla OpenAPI speclerine erişim sağlayan diğer MCP sunucuları varsa da, bu proje özellikle Resource Templates aracılığıyla erişim sağlamaya odaklanır. Bu yaklaşım, özellikle büyük API'ler için verimlidir çünkü:

• Binlerce olası path ve component'i önceden numaralandırmayı gerektirmez
• İstemciler, şablon desenleri kullanarak mevcut kaynakları dinamik olarak keşfedebilir
• Spesifikasyonun belirli bölümlerine yapılandırılmış, isteğe bağlı erişim sağlar

MCP istemcileri ve yetenekleri hakkında daha fazla ayrıntı için MCP İstemci Belgelerine bakın.

İstemciye Göre Hızlı Başlangıç Kılavuzları

• Claude Code - Anthropic'in Claude ile kodlama için CLI aracı
• Claude Desktop, Cline, Windsurf - Aşağıdaki kurulum talimatlarına bakın

Kurulum

Önerilen kullanım yöntemleri (npx ve Docker, aşağıda açıklanmıştır) için ayrı bir kurulum adımı gerekli değildir. MCP istemciniz sağladığınız konfigürasyona göre paketi otomatik olarak indirecek veya Docker görüntüsünü çekecektir.

Bununla birlikte, sunucuyu açıkça kurmayı tercih ederseniz veya gerekiyorsa, iki seçeneğiniz vardır:

1. Global Kurulum: Paketi npm kullanarak global olarak kurabilirsiniz:

   npm install -g mcp-openapi-schema-explorer
   

   MCP istemcinizi global olarak kurulmuş bir sunucu kullanacak şekilde yapılandırmak için aşağıdaki Yöntem 3'e bakın.

2. Yerel Geliştirme/Kurulum: Repository'yi klonlayabilir ve yerel olarak derleyebilirsiniz:

   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
   cd mcp-openapi-schema-explorer
   npm install
   npm run build
   

   Sunucuyu yerel derlemeden node kullanarak çalıştırmak için MCP istemcinizi yapılandırmak amacıyla aşağıdaki Yöntem 4'e bakın.

Sunucuyu MCP İstemcinize Ekleme

Bu sunucu MCP istemcileri tarafından çalıştırılmak için tasarlanmıştır (Claude Desktop, Windsurf, Cline vb.). Bunu kullanmak için, istemcinizin ayarlar dosyasına (genellikle bir JSON dosyası) bir konfigürasyon girdisi eklersiniz. Bu girdisi, istemciye sunucu işleminin nasıl yürütüleceğini söyler (örneğin, npx, docker veya node kullanarak). Sunucunun kendisi, istemci ayarları girişinde belirtilen command-line argümanlarının ötesinde ayrı bir konfigürasyon gerektirmez.

Aşağıda, istemci konfigürasyonunuza sunucu girişi eklemenin yaygın yöntemleri verilmiştir.

Yöntem 1: npx (Önerilen)

npx kullanmak önerilir çünkü global/yerel kurulumdan kaçınır ve istemcinin yayınlanan en son sürümü kullanmasını sağlar.

Örnek İstemci Konfigürasyon Girdisi (npx Yöntemi):

Aşağıdaki JSON nesnesini MCP istemcinizin konfigürasyon dosyasının mcpServers bölümüne ekleyin. Bu girdisi, istemciye sunucuyu npx kullanarak nasıl çalıştıracağını söyler:

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Konfigürasyon Notları:

• "My API Spec (npx)" yerine, bu sunucu örneği için istemcinizde benzersiz bir ad yazın.
• <path-or-url-to-spec> yerine, spesifikasyonunuzun mutlak yerel dosya yolunu veya tam uzak URL'sini yazın.
• --output-format isteğe bağlıdır (json, yaml, json-minified), varsayılan olarak json'dur.
• Birden fazla spesifikasyonu keşfetmek için mcpServers içine, her biri benzersiz bir adla ve farklı bir spec'i işaret eden ayrı girişler ekleyin.

Yöntem 2: Docker

MCP istemcinizi, resmi Docker görüntüsü kadykov/mcp-openapi-schema-explorer kullanarak sunucuyu çalıştırmaya yönelendirebilirsiniz.

Örnek İstemci Konfigürasyon Girdileri (Docker Yöntemi):

Aşağıdaki JSON nesnelerinden birini MCP istemcinizin konfigürasyon dosyasının mcpServers bölümüne ekleyin. Bu girişleri, istemciye sunucuyu docker run kullanarak nasıl çalıştıracağını söyler:

• Uzak URL: URL'yi doğrudan docker run'a geçirin.

• Uzak URL Kullanarak:

  {
    "mcpServers": {
      "My API Spec (Docker Remote)": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "kadykov/mcp-openapi-schema-explorer:latest",
          "<remote-url-to-spec>"
        ],
        "env": {}
      }
    }
  }
  

• Yerel Dosya Kullanarak: (Dosyayı konteynera bağlamayı gerektirir)

  {
    "mcpServers": {
      "My API Spec (Docker Local)": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-v",
          "/full/host/path/to/spec.yaml:/spec/api.yaml",
          "kadykov/mcp-openapi-schema-explorer:latest",
          "/spec/api.yaml",
          "--output-format",
          "yaml"
        ],
        "env": {}
      }
    }
  }
  

  Önemli: /full/host/path/to/spec.yaml yerine, ana makinenizde doğru mutlak yolu yazın. /spec/api.yaml yolu, konteyner içindeki karşılık gelen yoldur.

Yöntem 3: Global Kurulum (Daha Az Yaygın)

npm install -g kullanarak paketi global olarak kurduysanız, istemcinizi doğrudan çalıştırmak için yapılandırabilirsiniz.

# Bu komutu terminalinizde bir kez çalıştırın
npm install -g mcp-openapi-schema-explorer

Örnek İstemci Konfigürasyon Girdisi (Global Kurulum Yöntemi):

Aşağıdaki girdisi MCP istemcinizin konfigürasyon dosyasına ekleyin. Bu, mcp-openapi-schema-explorer komutunun istemcinin yürütme ortamı PATH'inde erişilebilir olduğunu varsayar.

{
  "mcpServers": {
    "My API Spec (Global)": {
      "command": "mcp-openapi-schema-explorer",
      "args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}

• command (mcp-openapi-schema-explorer) öğesinin, MCP istemciniz tarafından kullanılan PATH ortam değişkeninde erişilebilir olduğundan emin olun.

Yöntem 4: Yerel Geliştirme/Kurulum

Bu yöntem, repository'yi yerel olarak klonladıysanız veya değiştirilmiş bir sürümü çalıştırmak istiyorsanız yararlıdır.

Kurulum Adımları (Terminalinizde bir kez çalıştırın):

1. Repository'yi klonlayın: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Dizine gidin: cd mcp-openapi-schema-explorer
3. Bağımlılıkları yükleyin: npm install
4. Projeyi derleyin: npm run build (veya just build)

Örnek İstemci Konfigürasyon Girdisi (Yerel Geliştirme Yöntemi):

Aşağıdaki girdisi MCP istemcinizin konfigürasyon dosyasına ekleyin. Bu, istemciye yerel olarak derlenmiş sunucuyu node kullanarak çalıştırmasını söyler.

{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],

      "env": {}
    }
  }
}

Önemli: /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js yerine, klonlanan repository'nizdeki derlenmiş index.js dosyasının doğru mutlak yolunu yazın.

Özellikler

• MCP Resource Template Erişimi: Parametreli URI şablonları (openapi://info, openapi://paths/{path}/{method}, openapi://components/{type}/{name}) aracılığıyla OpenAPI speclerini keşfedin.
• OpenAPI v3.0 & Swagger v2.0 Desteği: Her iki formatı yükler, v2.0'ı otomatik olarak v3.0'a dönüştürür.
• Yerel & Uzak Dosyalar: Specları yerel dosya yollarından veya HTTP/HTTPS URL'lerinden yükleyin.
• Token-Verimli: LLM'ler için yapılandırılmış erişim sağlayarak token kullanımını minimize etmek için tasarlanmıştır.
• Çoklu Çıktı Formatları: JSON (varsayılan), YAML veya minified JSON (--output-format) içinde ayrıntılı görünümler alın.
• Dinamik Sunucu Adı: MCP istemcilerinde sunucu adı, yüklenen specin info.title'ını yansıtır.
• Reference Dönüşümü: İç $ref'ler (#/components/...) tıklanabilir MCP URI'lerine dönüştürülür.

Mevcut MCP Kaynakları

Bu sunucu, OpenAPI spesifikasyonunu keşfetmek için aşağıdaki MCP resource şablonlarını sunar.

Önemli: Bu sunucu resource şablonları sağlar, önceden numaralandırılmış kaynaklar değil. MCP istemcisini kullandığınızda:

• İstemci, mevcut şablon desenlerini keşfetmek için resources/templates/list öğesini çağırır
• Daha sonra, şablon parametrelerini doldurarak belirli URI'ler oluşturursunuz (örneğin, {path} yerine users%2F%7Bid%7D)
• İstemci, yapılandırılan URI'nizle resources/read kullanarak gerçek içeriği getirir

resources/list ("templates" olmadan) çağrırsanız, boş bir liste alırsınız—bu beklenen davranıştır.

Çoklu Değer Parametrelerini Anlama (*)

Bazı resource şablonları, {method*} veya {name*} gibi yıldız işaretiyle biten parametreler içerir. Bu, parametrenin virgülle ayrılmış birden fazla değeri kabul ettiğini gösterir. Örneğin, bir yolun hem GET hem de POST yöntemleri için ayrıntılar isteyecekseniz, openapi://paths/users/get,post gibi bir URI kullanırsınız. Bu, tek bir istekte birden fazla öğe için ayrıntıları getirmeye olanak tanır.

Resource Şablonları:

• openapi://{field}

  • Açıklama: OpenAPI belgesinin üst düzey alanlarına (info, servers, tags gibi) veya paths veya components içeriğini listeler. Belirli mevcut alanlar, yüklenen spesifikasyona bağlıdır.
  • Örnek: openapi://info
  • Çıktı: paths ve components için text/plain liste; diğer alanlar için yapılandırılmış format (JSON/YAML/minified JSON).
  • Tamamlamalar: Yüklenen spece bulunan gerçek üst düzey anahtarlara göre {field} için dinamik öneriler sağlar.

• openapi://paths/{path}

  • Açıklama: Belirli bir API yolu için mevcut HTTP yöntemlerini (işlemleri) listeler.
  • Parameter: {path} - API yol dizesi. URL kodlanmış olmalıdır (örneğin, /users/{id} users%2F%7Bid%7D olur).
  • Örnek: openapi://paths/users%2F%7Bid%7D
  • Çıktı: text/plain yöntem listesi.
  • Tamamlamalar: Yüklenen spece bulunan yollara göre {path} için dinamik öneriler sağlar (URL kodlanmış).

• openapi://paths/{path}/{method*}

  • Açıklama: Belirli bir API yolu üzerinde bir veya daha fazla işlemin (HTTP yöntemi) ayrıntılı spesifikasyonunu alır.
  • Parametreler:
    • {path} - API yol dizesi. URL kodlanmış olmalıdır.
    • {method*} - Bir veya daha fazla HTTP yöntemi (örneğin, get, post, get,post). Büyük/küçük harf duyarsız.
  • Örnek (Tek): openapi://paths/users%2F%7Bid%7D/get
  • Örnek (Çoklu): openapi://paths/users%2F%7Bid%7D/get,post
  • Çıktı: Yapılandırılmış format (JSON/YAML/minified JSON).
  • Tamamlamalar: {path} için dinamik öneriler sağlar. {method*} için statik öneriler sağlar (GET, POST, PUT, DELETE vb. gibi yaygın HTTP fiilleri).

• openapi://components/{type}

  • Açıklama: Belirli bir türün tüm tanımlı bileşenlerinin adlarını listeler (örneğin, schemas, responses, parameters). Belirli mevcut türler, yüklenen spesifikasyona bağlıdır. Ayrıca listelenen her tür için kısa bir açıklama sağlar.
  • Örnek: openapi://components/schemas
  • Çıktı: text/plain bileşen adları listesi açıklamalarla.
  • Tamamlamalar: Yüklenen spece bulunan bileşen türlerine göre {type} için dinamik öneriler sağlar.

• openapi://components/{type}/{name*}

  • Açıklama: Belirli bir türün bir veya daha fazla adlandırılmış bileşeninin ayrıntılı spesifikasyonunu alır.
  • Parametreler:
    • {type} - Bileşen türü.
    • {name*} - Bir veya daha fazla bileşen adı (örneğin, User, Order, User,Order). Büyük/küçük harf duyarlı.
  • Örnek (Tek): openapi://components/schemas/User
  • Örnek (Çoklu): openapi://components/schemas/User,Order
  • Çıktı: Yapılandırılmış format (JSON/YAML/minified JSON).
  • Tamamlamalar: {type} için dinamik öneriler sağlar. Yüklenen spec toplamda tam olarak bir bileşen türü içeriyorsa sadece {name*} için dinamik öneriler sağlar (örneğin, sadece schemas). MCP SDK şu anda seçilen {type}'a yönelik tamamlamalar sağlamayı desteklemediğinden bu sınırlama vardır; tüm türler arasında tüm adları sağlamak yanıltıcı olabilir.

Katkıda Bulunma

Katkılar hoş karşılanır! Geliştirme ortamını kurma, testleri çalıştırma ve değişiklikler gönderme hakkındaki talimatlar için CONTRIBUTING.md dosyasına bakın.

Yayınlar

Bu proje, Conventional Commits tabanlı otomatik sürüm yönetimi ve paket yayınlama için semantic-release kullanır.

Gelecek Planları

(Gelecek planları henüz belirlenmemiştir)