PeopleBox ATS MCP Server

# PeopleBox ATS — MCP Server

PeopleBox ATS için MCP (Model Context Protocol) server. Claude Desktop veya herhangi bir MCP uyumlu LLM client'ın ATS verilerine erişmesini sağlar.

---

## Kurulum

### Gereksinimler

- [Node.js](https://nodejs.org/) v18+
- [Git](https://git-scm.com/)

### Adımlar

```bash
# 1. Repo'yu klonla
git clone https://github.com/melihguven98/peoplebox-mcp.git

# 2. Bağımlılıkları kur
cd peoplebox-mcp
npm install

# 3. Derle
npm run build
```

---

## Claude Desktop Yapılandırması

Config dosyasını aç:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Aşağıdaki JSON'u yapıştır (`args` içindeki yolu kendi bilgisayarına göre düzelt):

### Windows

```json
{
  "mcpServers": {
    "PeopleBox": {
      "command": "node",
      "args": ["C:\\Users\\KULLANICI\\peoplebox-mcp\\dist\\cli.js"],
      "env": {
        "API_BASE_URL": "https://api.peoplebox.com/api/v1",
        "MCP_API_EMAIL": "recruiter@peoplebox.com",
        "MCP_API_PASSWORD": "sifre123"
      }
    }
  }
}
```

### macOS / Linux

```json
{
  "mcpServers": {
    "PeopleBox": {
      "command": "node",
      "args": ["/Users/KULLANICI/peoplebox-mcp/dist/cli.js"],
      "env": {
        "API_BASE_URL": "https://api.peoplebox.com/api/v1",
        "MCP_API_EMAIL": "recruiter@peoplebox.com",
        "MCP_API_PASSWORD": "sifre123"
      }
    }
  }
}
```

> **Önemli:** `KULLANICI` kısmını kendi kullanıcı adınla değiştir.

Claude Desktop'u yeniden başlat. Sol altta MCP tool ikonu görünecek.

---

## Yapılandırma

| Değişken | Varsayılan | Açıklama |
|----------|-----------|----------|
| `API_BASE_URL` | `http://localhost:3001/api/v1` | PeopleBox API adresi |
| `MCP_API_EMAIL` | `recruiter@peoplebox.com` | API login email |
| `MCP_API_PASSWORD` | `password123` | API login şifresi |
| `MCP_PORT` | `3002` | HTTP modu port (sadece `npm start` için) |

---

## Çalıştırma Modları

### Stdio Modu (Claude Desktop — önerilen)

Claude Desktop bu modu otomatik kullanır. Manuel test için:

```bash
API_BASE_URL=https://api.peoplebox.com/api/v1 node dist/cli.js
```

### HTTP Modu (MCP Inspector, Claude Code, vs.)

```bash
API_BASE_URL=https://api.peoplebox.com/api/v1 npm start
# → http://localhost:3002/mcp
```

---

## Mevcut Tool'lar (10 adet)

### Aday (Candidate)

| Tool | Açıklama |
|------|----------|
| `search_candidates` | Aday arama (isim, email, telefon, keyword) |
| `get_candidate` | Tam aday profili (skills, education, experience) |
| `create_candidate` | Yeni aday oluştur |
| `add_candidate_note` | Adaya not ekle |
| `check_candidate_email` | Email ile aday kontrol |

### Pozisyon (Position)

| Tool | Açıklama |
|------|----------|
| `search_positions` | Pozisyon arama |
| `get_position` | Pozisyon detayı |
| `get_position_statistics` | Genel pozisyon istatistikleri |

### Pipeline

| Tool | Açıklama |
|------|----------|
| `get_candidate_positions` | Adayın bulunduğu pozisyonlar |
| `get_candidate_timeline` | Aday aktivite geçmişi |

---

## Mevcut Resource'lar (5 adet)

| Resource | URI | Açıklama |
|----------|-----|----------|
| `sources` | `ats://lookups/sources` | Aday kaynakları |
| `skills` | `ats://lookups/skills` | Yetenek listesi |
| `companies` | `ats://lookups/companies` | Şirket listesi |
| `schools` | `ats://lookups/schools` | Okul listesi |
| `position_statistics` | `ats://positions/statistics` | Pozisyon istatistikleri |

---

## Test (MCP Inspector)

```bash
npx @modelcontextprotocol/inspector
```

1. Tarayıcıda **http://localhost:6274** adresine git
2. Transport type: **STDIO**
3. Command: `node`
4. Args: `dist/cli.js`
5. Environment: `API_BASE_URL=https://api.peoplebox.com/api/v1`
6. **Connect** butonuna tıkla

---

## Dosya Yapısı

```
peoplebox-mcp/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts              # HTTP server (Express + Streamable HTTP)
    ├── cli.ts                # Stdio CLI (Claude Desktop bu dosyayı çalıştırır)
    ├── config.ts             # Environment değişkenleri
    ├── api-client.ts         # API HTTP client (cookie auth, auto re-login)
    ├── tools/
    │   ├── index.ts          # Tool barrel
    │   ├── candidates.ts     # Aday tool'ları (5 tool)
    │   ├── positions.ts      # Pozisyon tool'ları (3 tool)
    │   └── pipeline.ts       # Pipeline tool'ları (2 tool)
    └── resources/
        ├── index.ts          # Resource barrel
        └── lookups.ts        # Lookup resource'ları (5 resource)
```

---

## Sorun Giderme

| Sorun | Çözüm |
|-------|-------|
| `Login failed (401)` | `MCP_API_EMAIL` / `MCP_API_PASSWORD` doğru mu? |
| `ECONNREFUSED` | `API_BASE_URL` doğru mu? API çalışıyor mu? |
| Claude Desktop tool ikonu yok | Config dosya yolu ve JSON syntax'ı doğru mu? Claude Desktop'u yeniden başlattın mı? |
| Windows'ta `ENOENT` hatası | `args` içindeki yolda `\\` (double backslash) kullandığından emin ol |