API i integracje

1. Wymagania wstępne

Dostęp do API MCP jest zawarty w pakiecie Expert.

• Posiadaj aktywne konto CVforge z bieżącą subskrypcją Expert.
• Utwórz Personal Access Token (PAT) na stronie Ustawienia → API i integracje.

2. Uwierzytelnianie

CVforge obsługuje dwie metody uwierzytelniania. Do większości integracji osobistych (n8n, skrypty, Claude Desktop) używaj tokenu PAT. Dla aplikacji zewnętrznych używaj przepływu OAuth 2.0 Authorization Code + PKCE.

2.1 Personal Access Token (PAT)

PAT to nieprzezroczysty token z prefiksem mcp_pat_. Jest wyświetlany tylko raz podczas tworzenia — przechowuj go bezpiecznie.

Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

2.2 OAuth 2.0 (Authorization Code + PKCE)

Dla aplikacji obsługujących wiele kont użytkowników używaj standardowego przepływu OAuth 2.0.

2.3 Zakresy (scopes)

3. Wykonanie wywołania MCP

API MCP wykorzystuje protokół JSON-RPC 2.0 przez HTTP. Każde żądanie to POST na https://api.cvforge.co/mcp.

Format żądania

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 */ }
  }
}

Format odpowiedzi (sukces)

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

Format odpowiedzi (błąd)

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

4. Dostępne narzędzia

API udostępnia 10 narzędzi. Narzędzia do odczytu wymagają zakresu read:profile lub read:cv. Przesyłanie, zgłaszanie ofert i optymalizacje wymagają write:cv.

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. Przykłady integracji

5.1 Pełny przepływ: przesłanie → oferta → optymalizacja → pobranie

Przykład w Pythonie ilustrujący pełną ścieżkę w 4 krokach.

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

Dodaj poniższy blok do pliku konfiguracyjnego Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json na macOS).

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

Po ponownym uruchomieniu Claude będzie mieć dostęp do narzędzi CVforge bezpośrednio w rozmowie. Powiedz na przykład: "Wylistuj moje CV na CVforge" lub "Prześlij plik MojeCV.pdf na CVforge".

5.4 n8n — węzeł HTTP Request

W n8n utwórz węzeł HTTP Request z następującymi parametrami:

Wynik JSON jest dostępny w kolejnym węźle poprzez {{ $json.result.content[0].text }}. Sparsuj go węzłem Set lub Function, aby wyodrębnić pola.

5.5 Cursor / Windsurf

W .cursor/mcp.json (lub odpowiedniku dla Windsurf):

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

6. Kody błędów

7. Limity i dobre praktyki

Rate limiting

W przypadku przekroczenia limitu API zwraca HTTP 429 z nagłówkiem Retry-After. Zaimplementuj w swoich automatyzacjach wykładniczy backoff.

Dobre praktyki

• Utwórz jeden token na integrację (jeden dla n8n, jeden dla Claude Desktop…) — ułatwisz sobie w ten sposób pojedyncze unieważnianie bez wpływu na pozostałe.
• Przyznawaj każdemu tokenowi wyłącznie niezbędne zakresy.
• Przechowuj tokeny w zmiennych środowiskowych lub menedżerze sekretów, nigdy na sztywno w kodzie.
• Natychmiast unieważnij każdy skompromitowany token na stronie Ustawienia.
• Endpoint MCP obsługuje otwarty CORS — pamiętaj o walidacji pochodzenia po stronie serwera we własnych integracjach.

Wykrywalność

CVforge publikuje manifest MCP czytelny dla LLM-ów i wyszukiwarek:

• /.well-known/mcp.json — manifest MCP
• /.well-known/oauth-authorization-server — wykrywanie OAuth2 (RFC 8414)
• /llms.txt — kontekst MCP dla LLM-ów