orbit-mcp

Orbit proje yönetim aracı için MCP sunucusu. Projeler, sayfalar, iş kalemleri, durumlar ve projeye özel alanlar üzerinde okuma ve yazma yapar.

Windows, macOS ve Linux'ta aynı şekilde çalışır: saf HTTP, yerel bağımlılık yok.

Sunucu hiçbir kuruma, çalışma alanına veya projeye ait bilgi içermez. Adres giriş sırasında girilir; çalışma alanı ve projeler giriş yapan kullanıcının kendi yetkisinden okunur.

Kurulum

npx -y orbit-mcp login

Komut tarayıcıda küçük bir giriş formu açar ve Orbit adresi, e-posta, parola ister. Form tercih edilmesinin sebebi pratik: terminalde klavye düzeni yüzünden @ yazılamayabiliyor, formda ise parola yöneticisi de otomatik doldurabiliyor.

Form yalnızca 127.0.0.1 üzerinde, rastgele bir yol belirteciyle çalışır ve giriş bitince kapanır. Terminalden giriş için login --terminal kullanılabilir.

Girişten sonra hesabın erişebildiği çalışma alanları API'den listelenir; tek alan varsa otomatik seçilir, birden fazlaysa seçim istenir. Kısa ad (slug) elle yazılmaz.

Oturum çerezi ~/.orbit-mcp/session.json dosyasına yazılır (POSIX'te 0600, Windows'ta ayrıca DPAPI ile şifrelenir). Parola hiçbir yerde saklanmaz.

Windows'ta DPAPI şifrelemesi başarısız olursa çerez kaydedilmez ve sebebi gösterilir. Düz metin kaydı bilerek kabul ediliyorsa ORBIT_PLAINTEXT_SESSION=1 ile tekrar denenir.

npx orbit-mcp whoami    # kayıtlı oturumu ve geçerliliğini gösterir
npx orbit-mcp logout    # oturumu siler

MCP istemcisine ekleme

macOS / Linux

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "orbit-mcp"],
      "env": { "ORBIT_ALLOW_WRITE": "1" }
    }
  }
}

Windows

{
  "mcpServers": {
    "orbit": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "orbit-mcp"],
      "env": { "ORBIT_ALLOW_WRITE": "1" }
    }
  }
}

ORBIT_ALLOW_WRITE verilmezse yazma araçları hiç yüklenmez — sunucu salt okunur çalışır.

Araçlar

Okuma — her zaman açık

| Araç | İş | |---|---| | orbit_projeler | Kullanıcının erişebildiği projeleri listeler | | orbit_proje_meta | Durumlar, etiketler, modüller, iş kalemi tipleri ve özel alan şeması — tek çağrıda | | orbit_sayfa_agaci | Sayfa ağacını girintili gösterir, ada göre süzer | | orbit_sayfa_oku | Sayfa içeriğini Markdown veya ham HTML olarak verir | | orbit_is_kalemi_oku | Anahtarıyla iş kalemi; özel alanlar görünen adlarıyla | | orbit_is_kalemi_listele | Sunucu tarafı süzgeçlerle liste (aşağıya bakın), imleçli sayfalama | | orbit_yorumlar | İş kalemi yorumları | | orbit_gecmis | Alan değişikliği geçmişi (kim, ne zaman, neyi) | | orbit_bildirimler | Kullanıcının Orbit bildirimleri |

Tüm araçlar metnin yanında structuredContent da döndürür ve outputSchema bildirir; istemci sonucu ayrıştırmak zorunda kalmaz.

orbit_is_kalemi_listele süzgeçleri

Hepsi Orbit sunucusunda uygulanır; bu yüzden eski işler de bulunur ve büyük projelerde yalnızca eşleşen kayıtlar iner.

| Girdi | Örnek | |---|---| | metin | "hugin" — başlıkta geçen metin, büyük/küçük harf duyarsız | | durum, tip, etiket, modul | Ad veya ad dizisi: ["N_Done", "In Progress"] | | durum_grubu | ["backlog", "unstarted", "started"] — açık işler | | atanan | Ad, e-posta, kullanıcı kimliği veya "ben" | | oncelik | ["urgent", "high"] | | guncellenme_sonrasi / _oncesi | "2026-09-01" | | hedef_tarih_sonrasi / _oncesi | "2026-09-30" | | siralama | guncellenme-yeni (varsayılan), olusturma-yeni, hedef-tarih, oncelik, numara … | | adet | Sayfa başına kayıt, en fazla 1000 (varsayılan 50) | | imlec | Önceki sonucun sonraki_imlec değeri; süzgeçler aynı kalmalı |

Bilinmeyen bir durum, tip, etiket, modül veya kişi adı artık sessizce yok sayılmaz; geçerli değerleri listeleyen bir hata döner.

Yazma — ORBIT_ALLOW_WRITE=1 gerekir

| Araç | İş | |---|---| | orbit_sayfa_olustur | Yeni sayfa; içerik Markdown olarak verilebilir | | orbit_sayfa_guncelle | Sayfa adı ve/veya içeriği | | orbit_sayfa_tasi | Sayfayı başka bir üst sayfanın altına taşır | | orbit_is_kalemi_olustur | Yeni iş kalemi; durum, tip, etiket, özel alanlar | | orbit_is_kalemi_guncelle | Durum, başlık, etiket, açıklama, özel alanlar | | orbit_sayfa_arsivle | Sayfayı arşivler, geri alır veya kalıcı siler | | orbit_is_kalemi_arsivle | İş kalemini arşivler veya geri alır | | orbit_yorum_ekle | İş kalemine yorum |

Tasarımdaki kararlar

Hiçbir şey koda gömülü değil. Adres, çalışma alanı, projeler, durumlar, etiketler, iş kalemi tipleri ve özel alan şemaları — hepsi çalışma anında API'den okunur. Kullanıcı hangi projelere yetkiliyse onları görür, hangisinde çalışacağına kendi karar verir.

Özel alanlar şemaya karşı doğrulanır. single_select alanına listede olmayan bir değer, number alanına metin, date alanına yanlış biçim yazılamaz — istek API'ye hiç gitmez, bunun yerine o projede geçerli olan seçenekler listelenir. Alan anahtarları ve seçenekleri orbit_proje_meta ile öğrenilir.

Markdown → Orbit HTML dönüştürücü. Orbit editörü başlık etiketi kullanmaz; başlıklar kalın paragraftır, tablolarda etiket sütunu #D9E1F2, koyu başlık satırı #1F3864 arka planlıdır. Markdown yazarsınız, dönüştürücü Orbit'in kendi biçimini üretir. Markdown tablosunun başlık satırı boş bırakılırsa etiket tablosu üretilir:

|  |  |
| --- | --- |
| Alan | Değer |
| Sorumlu | Ad Soyad |

Yaz-sonra-doğrula. Her yazma işleminden sonra kayıt geri okunur. Sebebi somut: Orbit'te sayfa oluştururken üst sayfa alanının adı parent, parent_id değil — yanlış alan gönderildiğinde API 201 döndürüp alanı sessizce yok sayıyor. Bu sınıf hatalar sessizce geçmesin diye doğrulama yapılır, gerekirse düzeltilir, olmazsa uyarı verilir.

Kimlik esnekliği. Proje UUID, ad veya kısa kod ile; iş kalemi PROJEKODU-NUMARA biçiminde belirtilir. UUID ezberlemek gerekmez. Ad karşılaştırması dile duyarsızdır: in progress, In Progress ve IN PROGRESS aynı durumu bulur.

Büyük çalışma alanlarına uygun. İstekler süreç genelinde sınırlı eşzamanlılıkla (varsayılan 4) ve zaman aşımıyla gönderilir. Proje listesi, durumlar, tipler ve özel alan şemaları 5 dakika bellekte tutulur. Çalışma alanı üye listesi (binlerce kayıt, 10 MB'ı aşabilir) yalnızca ad çözmek gerektiğinde indirilir ve kimlik/ad/e-posta olarak ~/.orbit-mcp/cache/ altında 24 saat saklanır; sonraki süreçler yeniden indirmez.

Hata türleri ayrılır. 401 veya giriş sayfasına yönlendirme "yeniden giriş yapın" der; 403 ise oturumun geçerli olduğunu, sorunun proje yetkisinde olduğunu söyler.

Sorun bildirme

Hata ve öneriler için: [email protected]

Sürüm notları

0.2.0

• Windows'ta login takılması giderildi. DPAPI için PowerShell spawn ile çağrılıyor, stdin kapatılıyor ve 20 sn zaman aşımı var. DPAPI başarısız olursa çerez artık sessizce düz metin yazılmıyor.
• orbit_is_kalemi_listele: tüm süzgeçler sunucu tarafında; metin araması eski işleri de buluyor; durum_grubu, atanan, oncelik, hedef tarih ve guncellenme_oncesi eklendi; sayfa başına 1000 kayıt ve imleçli sayfalama; çıktıda atanan, öncelik ve tarihler. Tip süzgeci önceden sunucuda yok sayılıyordu, düzeltildi.
• İsteklerde zaman aşımı ve eşzamanlılık sınırı; meta veri önbelleği; üye listesi disk önbelleği.
• 403 artık "login olun" demiyor.
• Tüm araçlarda structuredContent + outputSchema.
• package.json: exports, types, bugs.
• Ad eşleştirmesi dile duyarsız ("In Progress" / "in progress"); hata mesajlarında "authentıcatıon" gibi bozulmalar giderildi.
• Giriş sayfasında sunucu mesajları ve çalışma alanı adları textContent ile basılıyor.

Geliştirme

npm install
npm run build
npm test          # birim testleri: dönüştürücüler, doğrulama, sayfa ağacı, HTTP istemcisi, süreç çalıştırma
npm run kontrol   # yalnızca tip kontrolü

Ortam değişkenleri

| Değişken | İş | |---|---| | ORBIT_ALLOW_WRITE=1 | Yazma araçlarını etkinleştirir (varsayılan: kapalı) | | ORBIT_URL | login formunda adres önceden doldurulur | | ORBIT_EMAIL | login formunda e-posta önceden doldurulur | | ORBIT_NO_BROWSER=1 | Tarayıcı otomatik açılmaz, adres yalnızca yazdırılır (SSH/sunucu) | | ORBIT_TIMEOUT_MS | İstek başına zaman aşımı, ms (varsayılan 60000) | | ORBIT_MAX_CONCURRENCY | Aynı anda gönderilecek en fazla istek (varsayılan 4) | | ORBIT_PLAINTEXT_SESSION=1 | Windows'ta DPAPI kullanılamazsa oturumu düz metin kaydetmeyi kabul eder |

Kütüphane olarak kullanım

import { OrbitIstemci, projeCoz, isKalemiListele } from "orbit-mcp";

const istemci = await OrbitIstemci.olustur();          // ~/.orbit-mcp oturumunu kullanır
const proje = await projeCoz(istemci, "JKRP");
const { kalemler, sonrakiImlec } = await isKalemiListele(istemci, proje.id, {
  durumGruplari: ["started"],
  metin: "entegrasyon",
  adet: 200
});

Tip tanımları (.d.ts) pakete dahildir.

Bilinen sınırlar

• Oturum çerezinin ömrü Orbit sunucusuna bağlıdır; düştüğünde login tekrarlanır.
• Orbit'in iş kalemi listesinde type, type_id ve search parametreleri sessizce yok sayılır; araç bu yüzden issue_type ve name kullanır. Sayfa listesi per_page > 100 kabul etmez.
• Sayfa içeriği tümüyle değiştirilir; kısmi düzenleme için önce format=html ile okuyun.
• İş kalemi kalıcı olarak silinemez. Orbit çoğu rolde DELETE /issues/<id>/ isteğini 403 ile reddeder; orbit_is_kalemi_arsivle yalnızca arşivler. Sayfalar hem arşivlenebilir hem kalıcı silinebilir.
• Yazma araçları (sayfa ve iş kalemi oluşturma/güncelleme) canlı ortamda uçtan uca denenmedi; okuma araçlarının tamamı gerçek veriyle doğrulandı. İlk kullanımda deneme amaçlı bir proje üzerinde sınanması önerilir.