Paraşüt MCP & Node.js SDK

Resmî olmayan (unofficial), tam tip güvenli (type-safe) TypeScript Node.js SDK ve Model Context Protocol (MCP) Sunucusu.

Paraşüt REST API V4 altyapısı üzerine inşa edilmiştir. Claude Desktop, Cursor, Claude Code, Windsurf veya herhangi bir MCP istemcisi üzerinden Türkçe doğal dil komutlarıyla cari hesapları, satış/alış faturalarını, kasa/banka hareketlerini, stokları ve GİB resmî e-belgelerini (e-Fatura, e-Arşiv, e-SMM) yönetmenizi sağlar.

# Node.js SDK Kurulumu
npm install @yigitkonur/parasut-node-sdk

# MCP Sunucusunu Doğrudan Çalıştırma
npx @yigitkonur/parasut-mcp-server

📦 Paket Mimarisi

Bu repo pnpm workspace tabanlı bir monorepo olup iki ana paketten oluşur:

1. @yigitkonur/parasut-node-sdk
   • Paraşüt REST API V4'ü saran hafif ve sıfır çalışma zamanı bağımlılığına (zero runtime dependencies) sahip TypeScript SDK.
   • Yerel fetch API'si, JSON:API v1.0 standardı serileştirme/ayrıştırma, Token Bucket rate limiting (10 istek / 10 saniye), exponential backoff retry mekanizması ve otomatik 401 token yenileme (onUnauthorized) içerir.
2. @yigitkonur/parasut-mcp-server
   • Claude Desktop, Cursor, Claude Code ve diğer MCP uyumlu yapay zeka istemcilerine stdio üzerinden 34 adet AI-optimize araç sunar.
   • Finansal işlemlerde kazara veri kaybını önlemek için Önizleme (Preview/Dry-run) ve GİB e-belgelerinde Çift Aşamalı Teyit (Double Confirmation) mekanizmasına sahiptir.

[!NOTE]
Bu proje Paraşüt Yazılım Teknolojileri A.Ş. ile resmî bir bağlantıya sahip değildir; açık kaynak topluluk projesidir.

🔐 Kimlik Doğrulama Yöntemleri (Authentication)

SDK ve MCP sunucusu iki farklı kimlik doğrulama yöntemini tam olarak destekler:

1. Kullanıcı Adı & Şifre (OAuth2 Resource Owner Password Flow)

Paraşüt API Client ID/Secret ve kullanıcı giriş bilgilerinizle doğrudan oturum açar:

PARASUT_CLIENT_ID="your-client-id"
PARASUT_CLIENT_SECRET="your-client-secret"
PARASUT_USERNAME="[email protected]"
PARASUT_PASSWORD="your-password"
PARASUT_COMPANY_ID="123456" # Opsiyonel: Verilmezse otomatik tespit edilir

2. Token Tabanlı Kimlik Doğrulama (Access & Refresh Token)

Önceden alınmış OAuth token'ları veya harici servislerle entegrasyon için kullanıcı adı/şifre gerekmeden çalışır:

PARASUT_ACCESS_TOKEN="your-access-token"
PARASUT_REFRESH_TOKEN="your-refresh-token" # Opsiyonel: 401 yenileme için önerilir
PARASUT_CLIENT_ID="your-client-id"         # Refresh token kullanıldığında gereklidir
PARASUT_CLIENT_SECRET="your-client-secret" # Refresh token kullanıldığında gereklidir
PARASUT_COMPANY_ID="123456"               # Opsiyonel: Otomatik tespit edilebilir

⚡ Öne Çıkan Kimlik Doğrulama Özellikleri

• Otomatik Şirket (Company ID) Tespiti: PARASUT_COMPANY_ID belirtilmediğinde SDK ve MCP sunucusu GET /v4/me uç noktasına bağlanarak kullanıcının erişim yetkisi olan ilk şirket ID'sini otomatik olarak keşfeder ve isteklerde kullanır.
• Otomatik 401 Token Yenileme (Transparent Refresh & Retry): Paraşüt API'sinde access token süresi (2 saat) dolup 401 Unauthorized döndüğünde, SDK arka planda refresh token ile yeni bir access token temin eder, authorization başlığını günceller ve başarısız olan isteği otomatik olarak yeniden dener.

🛠️ MCP Sunucusu Kurulumu

Claude Desktop Kurulumu

Aşağıdaki yapılandırmayı işletim sisteminize göre ilgili dosyaya ekleyin:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "parasut": {
      "command": "npx",
      "args": ["-y", "@yigitkonur/parasut-mcp-server"],
      "env": {
        "PARASUT_CLIENT_ID": "your-client-id",
        "PARASUT_CLIENT_SECRET": "your-client-secret",
        "PARASUT_USERNAME": "[email protected]",
        "PARASUT_PASSWORD": "your-password",
        "PARASUT_COMPANY_ID": "123456"
      }
    }
  }
}

Alternatif olarak Token tabanlı kurulum:

{
  "mcpServers": {
    "parasut": {
      "command": "npx",
      "args": ["-y", "@yigitkonur/parasut-mcp-server"],
      "env": {
        "PARASUT_ACCESS_TOKEN": "your-access-token",
        "PARASUT_REFRESH_TOKEN": "your-refresh-token",
        "PARASUT_CLIENT_ID": "your-client-id",
        "PARASUT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor Kurulumu

Cursor ayarlarında (Features > MCP Servers) veya .cursor/mcp.json dosyasında tanımlayabilirsiniz:

{
  "mcpServers": {
    "parasut": {
      "command": "npx",
      "args": ["-y", "@yigitkonur/parasut-mcp-server"],
      "env": {
        "PARASUT_CLIENT_ID": "your-client-id",
        "PARASUT_CLIENT_SECRET": "your-client-secret",
        "PARASUT_USERNAME": "[email protected]",
        "PARASUT_PASSWORD": "your-password"
      }
    }
  }
}

mcpc CLI ile Canlı Test ve Kullanım

# Sunucu bağlantısını test etme ve araçları listeleme
mcpc npx -y @yigitkonur/parasut-mcp-server tools-list

# Canlı araç çağrısı örneği
mcpc npx -y @yigitkonur/parasut-mcp-server tools-call get_financial_summary

🧰 MCP Araçları Kataloğu (34 Araç - Detaylı Türkçe Rehber)

MCP sunucusu 8 ana faaliyet alanında toplam 34 aracı kullanıma sunar. Tüm yazma/güncelleme araçları varsayılan olarak Önizleme (Preview/Dry-Run) modunda çalışarak yanlış işlem yapılmasını engeller.

Güvenlik Seviyeleri:
🔍 Salt Okunur   : Veri okur, sistemde değişiklik yapmaz. Doğrudan çalışır.
⚠️ Önizleme Korumalı: confirm=true verilmedikçe sadece yapılacak işlemin özetini sunar.
🚨 Çift Onay Korumalı: confirm=true VE i_understand_this_is_irreversible="YES" gerektirir (GİB e-Belge).

1. Cari Hesaplar & İletişim (Contacts - 4 Araç)

Müşteri ve tedarikçi kayıtlarını aramak, görüntülemek, yeni cari kart açmak ve güncellemek için kullanılır.

2. Satış Faturaları (Sales Invoices - 7 Araç)

Satış faturalarını listeleme, filtreleme, yeni fatura kesme, iptal etme, arşivden çıkarma, PDF alma ve tahsilat ekleme işlemleri.

3. Alış Faturaları & Gider Fişleri (Purchase Bills - 4 Araç)

Tedarikçilerden gelen faturaların ve işletme gider fişlerinin takibi, sisteme işlenmesi ve ödemelerinin kaydedilmesi.

4. Ürün & Hizmet Yönetimi (Products - 4 Araç)

Stok kartları, satılan mal ve hizmetlerin tanımlanması, birim fiyat ve KDV oranlarının yönetimi.

5. Resmî E-Belgeler & GİB Entegrasyonu (E-Documents - 4 Araç)

Gelir İdaresi Başkanlığı (GİB) e-Fatura mükellefiyet sorgulama ve e-Fatura / e-Arşiv / e-SMM düzenleme ve gönderme işlemleri.

[!CAUTION]
E-Belge gönderme araçları resmî mali mühür ile imzalanıp GİB portalına iletildiğinden kesinlikle geri alınamaz. Bu araçlar güvenliğiniz için Çift Aşamalı Teyit gerektirir.

6. Finans, Kasa/Banka & Raporlar (Financial - 4 Araç)

Nakit akışı, banka hesapları, hesap hareketleri, banka masrafları ve anlık finansal durum özeti.

7. Stok & Depo Hareketleri (Inventory - 2 Araç)

Depolardaki anlık stok miktarları ve stok giriş/çıkış hareketlerinin incelenmesi.

8. Şirket, Kategori & Bordro (Organization - 5 Araç)

Kategoriler, etiketler, çalışan listesi, maaş ödemeleri ve vergi/SGK tahakkuklarının kaydı.

💻 SDK Doğrudan Kullanım Örnekleri

TypeScript projenizde doğrudan @yigitkonur/parasut-node-sdk kullanmak isterseniz:

import { ParasutClient } from '@yigitkonur/parasut-node-sdk';

// 1. İstemci Tanımlama (Token veya Kullanıcı Adı/Şifre ile)
const client = new ParasutClient({
  accessToken: process.env.PARASUT_ACCESS_TOKEN,
  refreshToken: process.env.PARASUT_REFRESH_TOKEN,
  credentials: {
    clientId: process.env.PARASUT_CLIENT_ID!,
    clientSecret: process.env.PARASUT_CLIENT_SECRET!,
  },
  // companyId verilmezse client.resolveCompanyId() ile otomatik keşfedilir
});

// 2. Müşteri Sorgulama
const contacts = await client.contacts.list({
  filter: { name: 'Acme' },
  page: { number: 1, size: 25 },
});

// 3. Fatura Oluşturma
const newInvoice = await client.salesInvoices.create({
  contact_id: 12345,
  description: 'Yazılım Danışmanlık Hizmeti',
  issue_date: '2026-09-25',
  due_date: '2026-10-25',
  details: [
    {
      product_id: 67890,
      quantity: 1,
      unit_price: 15000,
      vat_rate: 20,
    },
  ],
});

// 4. Otomatik Sayfalama (Async Iterator ile Bellek Dostu Tarama)
for await (const product of client.products.iterate()) {
  console.log(`Ürün: ${product.attributes.name} - Stok Kodu: ${product.attributes.code}`);
}

// 5. GİB e-Fatura Gönderme ve Asenkron Takip
const eInv = await client.eInvoices.submitAndWait(newInvoice.data.id, {
  scenario: 'commercial',
  to: 'urn:mail:[email protected]',
});
console.log('e-Fatura GİB Onayı Tamamlandı, Belge No:', eInv.data.attributes.invoice_number);

🔒 Güvenlik İlkeleri & Gizlilik Garantisi

• Sıfır İstem Dışı Finansal İşlem: Bütün yazma işlemleri (create_invoice, record_bill_payment, create_salary vb.) varsayılan olarak confirm=false kabul eder ve kullanıcıya yalnızca işlem simülasyonu sunar. Kullanıcı onaylamadıkça veritabanına hiçbir kayıt yazılmaz.
• Resmî Belge İptal Edilemezlik Güvencesi: GİB e-Fatura ve e-Arşiv bildirimlerinde yanlışlıkla resmî beyanda bulunmayı önlemek için iki aşamalı güvenlik sorusu (i_understand_this_is_irreversible="YES") uygulanır.
• Sıfır Gizli Anahtar / Özel Veri Sızıntısı: Bu açık kaynak kod tabanında veya git geçmişinde hiçbir üçüncü taraf şirket bilgisi, staging ortamı veya gerçek gizli anahtar (secret) bulunmaz. .env yerel dosyası git tarafından tamamen yoksayılır.

🧪 Geliştirme ve Test

# Bağımlılıkları yükle
pnpm install

# Tüm paketleri derle (TypeScript tsc)
pnpm build

# Birim ve entegrasyon testlerini çalıştır
pnpm test

# mcpc CLI ile smoke check
mcpc packages/parasut-mcp-server/dist/index.js tools-list

📄 Lisans

Bu proje MIT lisansı ile dağıtılmaktadır. Detaylar için LICENSE dosyasına göz atabilirsiniz.