Filika MCP Server

Filika.co bordro hesaplama API'si için Model Context Protocol (MCP) server implementasyonu.

Özellikler

Bu MCP server aşağıdaki araçları sağlar:

• get-wage-codes: Filika.co sistemindeki maaş kodlarını listeler
• calculate-payroll: Verilen parametrelerle bordro hesaplar
• calculate-severance: Kıdem tazminatı hesaplar
• get-employee-list: Çalışanlarla ilgili detaylı liste getirir

Transport Modları

Bu server iki farklı transport modu destekler:

1. SSE (Server-Sent Events) Transport

HTTP server üzerinden SSE ile çalışır. Web tabanlı uygulamalar ve gelişmiş entegrasyonlar için idealdir.

2. Stdio Transport (Legacy)

Doğrudan stdin/stdout üzerinden çalışır. Claude Desktop ile basit entegrasyon için kullanılır.

Kurulum

NPM'den Kurulum (Önerilen)

npm install -g @alibugatekin/filika-mcp-server

Manuel Kurulum

git clone https://github.com/alibugatekin/filika-mcp-server.git
cd filika-mcp-server
npm install
npm run build

Kullanım

Environment Variables

Filika.co API token'ınızı environment variable olarak ayarlamanız gerekir:

export FILIKA_API_TOKEN="your_api_token_here"

SSE Transport ile Kullanım

Server'ı SSE modunda başlatın:

# Varsayılan port (3000) ile
npm run start:sse

# Özel port ile
PORT=8080 npm run start

# Production modunda
npm run start:prod

Server başladıktan sonra:

• Ana sayfa: http://localhost:3000/
• SSE Endpoint: http://localhost:3000/sse
• Health Check: http://localhost:3000/health

Claude Desktop ile Kullanım (Stdio Transport)

Claude Desktop konfigürasyonunuza aşağıdaki ayarları ekleyin:

NPM Package Kullanımı (Önerilen)

{
  "mcpServers": {
    "filika": {
      "command": "npx",
      "args": ["@alibugatekin/filika-mcp-server"],
      "env": {
        "FILIKA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Global Kurulum Kullanımı

{
  "mcpServers": {
    "filika": {
      "command": "filika-mcp",
      "env": {
        "FILIKA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Manuel Kurulum Kullanımı

{
  "mcpServers": {
    "filika": {
      "command": "node",
      "args": ["path/to/filika-mcp-server/build/index.js"],
      "env": {
        "FILIKA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Web Tabanlı MCP İstemcileri ile Kullanım

SSE endpoint'ini kullanarak web tabanlı MCP istemcileri ile entegre olabilirsiniz:

// Örnek JavaScript entegrasyonu
const eventSource = new EventSource('http://localhost:3000/sse');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('MCP Response:', data);
};

// MCP mesajı gönderme
fetch('http://localhost:3000/sse', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'get-wage-codes',
      arguments: {}
    }
  })
});

API Token Alma

1. filika.co hesabınızı oluşturun
2. platform.filika.co adresine gidin
3. API token'ınızı oluşturun
4. Token'ı FILIKA_API_TOKEN environment variable'ı olarak ayarlayın

Araçlar

get-wage-codes

Filika.co sistemindeki kullanılabilir maaş kodlarını listeler.

Parametreler: Yok

Örnek Kullanım:

Maaş kodlarını göster

calculate-payroll

Verilen parametrelerle bordro hesaplar.

Parametreler:

• period (zorunlu): Bordro periyodu (YYYY-MM formatında, örn: "2024-01")
• net_salary (opsiyonel): Net maaş tutarı
• gross_salary (opsiyonel): Brüt maaş tutarı
• working_days (opsiyonel): Çalışılan gün sayısı
• overtime_hours (opsiyonel): Fazla mesai saatleri
• payroll_type (opsiyonel): Bordro tipi (varsayılan: "salaryPayroll")

Örnek Kullanım:

2024-01 periyodu için 50000 TL net maaş ile bordro hesapla

calculate-severance

Kıdem tazminatı hesaplar.

Parametreler:

• job_start_date (zorunlu): İşe başlama tarihi (YYYY-MM-DD formatında)
• job_end_date (zorunlu): İşten ayrılma tarihi (YYYY-MM-DD formatında)
• gross_salary (zorunlu): Brüt maaş tutarı
• bonus_amount (opsiyonel): Yıllık ikramiye tutarı
• transportation_allowance (opsiyonel): Ulaşım yardımı
• meal_allowance (opsiyonel): Yemek yardımı
• other_payment (opsiyonel): Diğer ödemeler
• cumulative_amount (opsiyonel): Kümülatif vergi matrahı

Örnek Kullanım:

2020-01-01 ile 2024-01-01 arasında çalışan, 80000 TL brüt maaşlı personel için kıdem tazminatı hesapla

get-employee-list

Çalışanlarla ilgili detaylı liste getirir.

Parametreler:

• month (zorunlu): Rapor ayı (YYYY-MM formatında, örn: "2024-01")

Örnek Kullanım:

2024-01 ayı için çalışan listesini getir

Geliştirme

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

# TypeScript derle
npm run build

# SSE modunda geliştirme
npm run dev

# Watch modunda geliştirme
npm run dev:watch

Environment Variables

• FILIKA_API_TOKEN: Filika.co API token'ı (zorunlu)
• PORT: HTTP server portu (varsayılan: 3000)
• HOST: HTTP server host'u (varsayılan: localhost)

Lisans

MIT

Destek

Sorularınız için: api@filika.co