API & Entegrasyonlar

1. Ön koşullar

MCP API erişimi Expert paketine dahildir.

• Devam eden bir Expert aboneliğine sahip aktif bir CVforge hesabınız olsun.
• Ayarlar → API & Entegrasyonlar sayfasından bir Personal Access Token (PAT) oluşturun.

2. Kimlik doğrulama

CVforge iki kimlik doğrulama yöntemini destekler. Çoğu kişisel entegrasyon için (n8n, betikler, Claude Desktop) bir PAT kullanın. Üçüncü taraf uygulamalar için OAuth 2.0 Authorization Code + PKCE akışını kullanın.

2.1 Personal Access Token (PAT)

PAT, mcp_pat_ önekine sahip opak bir jetondur. Oluşturulduğu anda yalnızca bir kez gösterilir — özenle saklayın.

Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

2.2 OAuth 2.0 (Authorization Code + PKCE)

Birden fazla kullanıcı hesabına hizmet veren uygulamalar için standart OAuth 2.0 akışını kullanın.

2.3 Scope'lar

3. MCP çağrısı yapma

MCP API, HTTP üzerinden JSON-RPC 2.0 protokolünü kullanır. Her istek, https://api.cvforge.co/mcp adresine yapılan bir POST isteğidir.

İstek formatı

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<nom_de_l_outil>",
    "arguments": { /* paramètres de l'outil */ }
  }
}

Yanıt formatı (başarılı)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ...données... }"
      }
    ]
  }
}

Yanıt formatı (hata)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Token invalide ou révoqué",
    "data": { "error_code": "MCP_TOKEN_INVALID" }
  }
}

4. Kullanılabilir araçlar

API 10 araç sunar. Okuma araçları read:profile veya read:cv gerektirir. Yükleme, ilan gönderme ve optimizasyonlar write:cv gerektirir.

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_profile", "arguments": {} }
}

{
  "id": "uuid",
  "email": "alice@example.com",
  "full_name": "Alice Martin",
  "subscription_plan": "Expert",
  "subscription_status": "active"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_credits", "arguments": {} }
}

{
  "total": 7,
  "subscription_credits": 5,
  "paid_credits": 2,
  "free_credits": 0
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_cvs", "arguments": { "limit": 10, "offset": 0 } }
}

{
  "cvs": [
    {
      "id": "uuid",
      "original_filename": "CV_Alice_2026.pdf",
      "created_at": "2026-04-10T14:30:00Z",
      "generation_count": 3
    }
  ],
  "total": 1
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_cv", "arguments": { "cv_id": "uuid" } }
}

{
  "id": "uuid",
  "original_filename": "CV_Alice_2026.pdf",
  "extracted_text": "Alice Martin — Product Manager...",
  "created_at": "2026-04-10T14:30:00Z"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "upload_cv", "arguments": {
  "filename": "mon_cv.pdf",
  "file_base64": "JVBERi0xLjQ...",
  "mime_type": "application/pdf"
} }
}

{
  "cv_profile_id": "uuid",
  "message": "CV uploaded and parsed successfully."
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "submit_offer", "arguments": {
  "offer_url": "https://www.linkedin.com/jobs/view/1234567890/"
} }
}

{
  "offer_id": "uuid",
  "offer_url": "https://www.linkedin.com/jobs/view/1234567890/",
  "job_title": "Product Manager Senior",
  "company_name": "Acme Corp"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "optimize_cv", "arguments": {
  "cv_profile_id": "uuid-du-cv",
  "offer_id": "uuid-de-l-offre"
} }
}

{
  "generation_id": "uuid",
  "status": "processing",
  "message": "CV optimization started"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_generations", "arguments": { "limit": 5 } }
}

{
  "generations": [
    {
      "id": "uuid",
      "cv_id": "uuid",
      "job_title": "Product Manager Senior",
      "ats_score": 87,
      "status": "completed",
      "created_at": "2026-04-11T09:00:00Z"
    }
  ],
  "total": 1
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_generation", "arguments": { "generation_id": "uuid" } }
}

{
  "id": "uuid",
  "job_title": "Product Manager Senior",
  "ats_score": 87,
  "optimized_text": "Alice Martin — Product Manager Senior...",
  "analysis": { "missing_keywords": ["OKR", "roadmap"], "strengths": [...] },
  "status": "completed",
  "created_at": "2026-04-11T09:00:00Z"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "download_generation", "arguments": { "generation_id": "uuid" } }
}

{
  "filename": "CV_Alice_PM_Senior.pdf",
  "content_b64": "JVBERi0xLjQ...",
  "mime_type": "application/pdf",
  "size_bytes": 124580
}

5. Entegrasyon örnekleri

5.1 Tam akış: yükleme → ilan → optimizasyon → indirme

Tam süreci 4 adımda gösteren Python örneği.

import requests, base64, time, json, os

PAT     = os.environ["CVFORGE_PAT"]
MCP     = "https://api.cvforge.co/mcp"
HEADERS = {"Content-Type": "application/json", "Authorization": f"Bearer {PAT}"}

def mcp(tool: str, args: dict = {}):
    r = requests.post(MCP, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": tool, "arguments": args}
    }, headers=HEADERS, timeout=60)
    r.raise_for_status()
    data = r.json()
    if "error" in data:
        raise RuntimeError(data["error"]["message"])
    return json.loads(data["result"]["content"][0]["text"])

# Étape 1 — Upload du CV
with open("mon_cv.pdf", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

cv = mcp("upload_cv", {
    "filename": "mon_cv.pdf",
    "file_base64": b64,
    "mime_type": "application/pdf",
})
cv_id = cv["cv_profile_id"]
print(f"CV uploadé : {cv_id}")

# Étape 2 — Soumission de l'offre
offer = mcp("submit_offer", {
    "offer_url": "https://www.linkedin.com/jobs/view/1234567890/"
})
offer_id = offer["offer_id"]
print(f"Offre : {offer['job_title']} @ {offer['company_name']} ({offer_id})")

# Étape 3 — Lancement de l'optimisation (1 crédit consommé)
gen = mcp("optimize_cv", {"cv_profile_id": cv_id, "offer_id": offer_id})
gen_id = gen["generation_id"]
print(f"Génération démarrée : {gen_id}")

# Étape 4 — Attente + téléchargement
for _ in range(20):
    time.sleep(5)
    details = mcp("get_generation", {"generation_id": gen_id})
    print(f"  statut : {details['status']}")
    if details["status"] == "completed":
        dl = mcp("download_generation", {"generation_id": gen_id})
        print(f"Téléchargement : {dl['download_url']} (valide 15 min)")
        break
    if details["status"] == "failed":
        raise RuntimeError("Optimisation échouée")

5.2 curl

# Remplacez YOUR_PAT par votre Personal Access Token
export PAT="mcp_pat_XXXXXXXXXXXXXXXXXXXX"

# Récupérer le profil
curl -X POST https://api.cvforge.co/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_profile","arguments":{}}}'

# Vérifier le solde de crédits
curl -X POST https://api.cvforge.co/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAT" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_credits","arguments":{}}}'

5.3 Claude Desktop / Claude.ai

Aşağıdaki bloğu Claude Desktop yapılandırma dosyanıza ekleyin (macOS'te ~/Library/Application Support/Claude/claude_desktop_config.json).

{
  "mcpServers": {
    "cvforge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.cvforge.co/mcp",
        "--header",
        "Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX"
      ]
    }
  }
}

Yeniden başlatıldıktan sonra Claude, CVforge araçlarına doğrudan sohbet içinden erişebilir. Örneğin şöyle diyebilirsiniz: "CVforge'daki CV'lerimi listele" veya "CVim.pdf dosyasını CVforge'a yükle".

5.4 n8n — HTTP Request düğümü

n8n'de aşağıdaki parametrelerle bir HTTP Request düğümü oluşturun:

JSON sonucu, bir sonraki düğümde {{ $json.result.content[0].text }} aracılığıyla kullanılabilir. Alanları çıkarmak için bir Set veya Function düğümüyle ayrıştırın.

5.5 Cursor / Windsurf

.cursor/mcp.json dosyasında (veya Windsurf için eşdeğerinde):

{
  "mcpServers": {
    "cvforge": {
      "url": "https://api.cvforge.co/mcp",
      "headers": {
        "Authorization": "Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

6. Hata kodları

7. Limitler ve en iyi uygulamalar

Rate limiting

Limit aşıldığında API, Retry-After başlığıyla birlikte HTTP 429 döndürür. Otomasyonlarınızda üstel geri çekilme (exponential backoff) uygulayın.

En iyi uygulamalar

• Entegrasyon başına bir token oluşturun (n8n için bir tane, Claude Desktop için bir tane…) — böylece diğerlerini etkilemeden tek tek iptal etmek kolaylaşır.
• Her token'a yalnızca gerekli scope'ları verin.
• Token'ları ortam değişkenlerinde veya bir gizli anahtar yöneticisinde saklayın; asla koda gömmeyin.
• Ele geçirilmiş herhangi bir token'ı Ayarlar sayfasından derhal iptal edin.
• MCP endpoint'i açık CORS destekler — kendi entegrasyonlarınızda origin'i sunucu tarafında doğrulamayı unutmayın.

Keşfedilebilirlik

CVforge, LLM'ler ve arama motorları tarafından okunabilen bir MCP manifestosu yayınlar:

• /.well-known/mcp.json — MCP manifestosu
• /.well-known/oauth-authorization-server — OAuth2 keşfi (RFC 8414)
• /llms.txt — LLM'ler için MCP bağlamı