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.

Related MCP server: mcp-server-smallinvoice

🔐 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="user@example.com"
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": "your-email@example.com",
        "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": "your-email@example.com",
        "PARASUT_PASSWORD": "your-password"
      }
    }
  }
}

mcpc CLI ile Canlı Test ve Kullanım

# Sunucu bağlantısını test etme ve araçları listeleme (stdio modu)
mcpc connect "npx -y @yigitkonur/parasut-mcp-server" @parasut-local
mcpc @parasut-local tools-list

# Canlı araç çağrısı örneği
mcpc @parasut-local tools-call get_financial_summary

🌐 URL Tabanlı Dağıtım & Streamable HTTP Modu (Docker / Dokploy / Remote MCP)

Sunucu, standart stdio taşıma katmanının yanı sıra resmî MCP spesifikasyonuna tam uyumlu Streamable HTTP taşıma protokolünü (2024-11-05, 2025-11-25, 2026-07-28) destekler. Bu mod sayesinde MCP sunucusunu Docker, Dokploy, Kubernetes veya VPS üzerinde bağımsız bir web servisi olarak barındırabilir ve yapay zeka ajanlarınıza güvenli bir HTTP uç noktası sunabilirsiniz.

HTTP Taşıma Katmanını Başlatma

Aşağıdaki komutlardan veya ortam değişkenlerinden biriyle HTTP modu otomatik olarak devreye girer:

# 1. Ortam değişkeni ile başlatma
MCP_TRANSPORT=http PORT=3000 node packages/parasut-mcp-server/dist/server.js

# 2. CLI parametresi ile başlatma
parasut-mcp --http --port 3000

# 3. Bağımsız binary ile başlatma
parasut-mcp-http --port 3000

HTTP Uç Noktaları (Endpoints)

• POST /mcp — MCP protokol başlatma (initialize), araç listeleme ve JSON-RPC mesaj alışverişi.

• GET /mcp — Server-Sent Events (SSE) stream akışı ve bağlantı sürdürülebilirliği (resumability).

• DELETE /mcp — Oturum sonlandırma (mcp-session-id başlığı ile).

• GET /health — Liveness & readiness sağlık kontrolü (aktif oturum sayısı ve versiyon bilgisi döner).

• GET / — Sunucu kök meta verisi ve yetkilendirme durumu.

İsteğe Bağlı API Anahtarı Koruması (Bearer Auth)

HTTP sunucusunu dış dünyadan korumak için MCP_API_KEY tanımlayabilirsiniz. Tanımlandığında, /mcp uç noktasına yapılan tüm isteklere Authorization: Bearer <MCP_API_KEY> başlığı zorunlu hale gelir.

MCP_TRANSPORT=http
PORT=3000
MCP_API_KEY=gizli-guclu-api-anahtari

🛡️ Resmî OAuth 2.0 / 2.1 Yetkilendirme (RFC 9728, RFC 8414, RFC 7591)

Paraşüt MCP Sunucusu, IETF ve Model Context Protocol yetkilendirme spesifikasyonlarını eksiksiz uygular:

• RFC 9728 Protected Resource Metadata: GET /.well-known/oauth-protected-resource uç noktası üzerinden sunucunun kaynak URI'si, yetkilendirme sunucuları ve desteklenen kapsamları (scopes_supported) yayınlanır.

• RFC 8414 Authorization Server Metadata: GET /.well-known/oauth-authorization-server üzerinden uç noktalar, desteklenen grant türleri (authorization_code, client_credentials, refresh_token), PKCE yöntemleri (S256) ve kimlik doğrulama biçimleri ilan edilir.

• RFC 7591 Dynamic Client Registration (DCR): POST /oauth/register ile istemciler (mcpc, Claude Desktop, Cursor vb.) dinamik olarak istemci kaydı oluşturabilir.

• RFC 7636 PKCE ile Yetkilendirme Kodu Akışı: GET /oauth/authorize ve POST /oauth/token ile interaktif tarayıcı onay ekranı veya otomatik onay.

• M2M / CI/CD için Client Credentials: POST /oauth/token (grant_type=client_credentials) ile CLI ve otomasyon ajanları doğrudan access token temin edebilir.

• RFC 6750 WWW-Authenticate Başlığı: Yetkisiz (401) isteklerde istemciye WWW-Authenticate: Bearer error="invalid_token", resource_metadata="..." başlığı dönülerek istemcinin dinamik yetkilendirme akışını otomatik başlatması sağlanır.

• RFC 7009 Token Revocation: POST /oauth/revoke ile token iptali.

mcpc CLI ile OAuth Üzerinden Bağlanma

# 1. OAuth Client Credentials ile giriş yapma ve profil kaydetme
mcpc login https://parasut-mcp.example.com/mcp \
  --grant client-credentials \
  --client-id mcpc-default \
  --client-secret your-mcp-api-key \
  --profile parasut-oauth

# 2. Kaydedilen OAuth profiliyle güvenli bağlantı kurma
mcpc connect https://parasut-mcp.example.com/mcp @parasut-oauth --profile parasut-oauth

# 3. Oturum üzerinden canlı araç çalıştırma
mcpc @parasut-oauth tools-call get_financial_summary
mcpc @parasut-oauth tools-call list_accounts

Docker ve Dokploy ile Dağıtım

Monorepo kökünde bulunan Dockerfile çok aşamalı (multi-stage) ve optimize edilmiş node:22-alpine imajı üretir:

# Docker imajı derleme
docker build -t parasut-mcp:latest .

# Docker container çalıştırma
docker run -d \
  --name parasut-mcp \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e MCP_TRANSPORT=http \
  -e PORT=3000 \
  -e PARASUT_CLIENT_ID="your-client-id" \
  -e PARASUT_CLIENT_SECRET="your-client-secret" \
  -e PARASUT_ACCESS_TOKEN="your-access-token" \
  -e PARASUT_REFRESH_TOKEN="your-refresh-token" \
  parasut-mcp:latest

Dokploy Compose Örneği:

services:
  parasut-mcp:
    image: parasut-mcp:latest
    pull_policy: never
    restart: unless-stopped
    init: true
    stop_grace_period: 15s
    environment:
      NODE_ENV: production
      MCP_TRANSPORT: http
      HOST: 0.0.0.0
      PORT: "3000"
      PARASUT_CLIENT_ID: ${PARASUT_CLIENT_ID}
      PARASUT_CLIENT_SECRET: ${PARASUT_CLIENT_SECRET}
      PARASUT_ACCESS_TOKEN: ${PARASUT_ACCESS_TOKEN}
      PARASUT_REFRESH_TOKEN: ${PARASUT_REFRESH_TOKEN}
      MCP_API_KEY: ${MCP_API_KEY:-}
    networks:
      default: {}
      dokploy-network: {}
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

networks:
  dokploy-network:
    external: true

Uzaktan mcpc Bağlantısı

Canlı HTTP uç noktanıza doğrudan mcpc veya MCP istemcileri üzerinden bağlanabilirsiniz:

# Canlı Streamable HTTP uç noktasına bağlanma
mcpc connect https://parasut-mcp.example.com/mcp @parasut-remote

# Oturum durumunu kontrol etme ve ping atma
mcpc @parasut-remote ping

# Uzak sunucudaki araçları listeleme
mcpc @parasut-remote tools-list

🧰 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.

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:defaultpk@parasut.com',
});
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.