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 v18+
• Git

Adımlar

# 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

{
  "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

{
  "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:

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

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

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)

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