Career Agent

Karriere-Agent, der über MCP in Claude Desktop integriert ist. Findet Stellen, berechnet die Kompatibilität mit Ihrem Profil, personalisiert Ihren Lebenslauf auf legitime Weise, generiert Nachrichten und Antworten und führt das Bewerbungsprotokoll.

Die letzte externe Aktion liegt immer bei Ihnen. Der Agent bereitet vor; Sie klicken.

Neues in v1.1

Details zu jeder Quelle mit den gemessenen Werten: docs/FONTES.md

Related MCP server: job-search-mcp

Inhaltsverzeichnis

1. Architektur

2. Voraussetzungen

3. Installation

4. Konfiguration

5. Konfiguration von Claude Desktop

6. So starten Sie

7. So testen Sie

8. So fügen Sie eine neue Stellenquelle hinzu

9. So fügen Sie einen neuen Lebenslauf hinzu

10. So registrieren Sie eine Bewerbung

11. Beispiele für Befehle in Claude Desktop

12. Aktuelle Einschränkungen

13. Nächste Schritte

1. Architektur

Überblick

                        Claude Desktop
                              |
              +---------------+---------------+
              |               |               |
        career-agent     job-search     career-files
         (MCP stdio)     (MCP stdio)     (MCP stdio)
              |               |               |
              +---------------+---------------+
                              |
                        career_core
              (dominio puro - nao conhece MCP)
                              |
         +--------+-----------+-----------+--------+
         |        |           |           |        |
      profile  scoring   applications  resume  job_sources
       (.md)   (7 dim.)  (SQLite+JSON) (tailor) (IJobSource)

Architekturentscheidungen

Domäne getrennt von den Adaptern. Die gesamte Geschäftslogik liegt in src/career_core/, das nichts von MCP importiert. Die drei server.py sind dünne Adapter: Sie übersetzen Argumente, rufen die Domäne auf und formatieren die Antwort. Das ermöglicht es, 100 % der Logik zu testen, ohne einen Server zu starten.

SQLite als Quelle der Wahrheit, JSON als Spiegel. SQLite bietet transaktionales Schreiben (das Protokoll wird nicht beschädigt, wenn der Prozess mitten in der Operation stirbt) und günstige Duplikatabfragen, mit null Konfiguration — im Gegensatz zu PostgreSQL, das einen Server und Anmeldedaten erfordern würde, ohne bei der Skalierung einer Person einen Gewinn zu bringen. Die applications.json existiert weiterhin, wird bei jeder Änderung atomar neu geschrieben, für die Sichtprüfung und die Versionsverwaltung in Git. Sie ist nur zum Schreiben: Sie wird nie zurückgelesen, sodass kein Risiko besteht, dass zwei Quellen divergieren.

Score als steckbare Dimensionen. Jede der 7 Dimensionen ist eine Klasse, die IScoreDimension implementiert und einen einzigen Aspekt bewerten und erklären kann. Der JobScorer summiert und sortiert nur. Eine neue Dimension hinzuzufügen ändert den Summierer nicht (Open/Closed).

Stellenquellen hinter einer Schnittstelle. IJobSource hat vier Implementierungen: MockJobSource (offline), RemotiveJobSource und ArbeitnowJobSource (echte öffentliche APIs, ohne Authentifizierung) und UnavailableJobSource (LinkedIn/Indeed/Gupy — deklariert, aber im manuellen Modus). Eine Quelle hinzuzufügen bedeutet, eine Klasse zu schreiben und sie zu registrieren; sonst ändert sich nichts.

Einzige Composition Root. CareerServices baut den Objektgraphen auf. Die Server instanziieren keine Abhängigkeiten von Hand, und die Tests injizieren Doubles.

Verzeichnisstruktur

career-agent/
├── pyproject.toml            # deps + config do pytest (fonte unica)
├── .env.example              # modelo de configuracao (versionado)
├── .env                      # sua configuracao real (NAO versionado)
│
├── src/career_core/          # DOMINIO - nao conhece MCP
│   ├── config.py             # Settings por ambiente
│   ├── models.py             # Job, CandidateProfile, Application, JobScore
│   ├── text.py               # normalizacao (aliases de stack, URL, empresa)
│   ├── security.py           # politica + maquina de estados (ApprovalGate)
│   ├── paths.py              # SandboxedFileSystem (jail em data/)
│   ├── errors.py             # hierarquia de erros de dominio
│   ├── logging_setup.py      # logging para stderr + arquivo
│   ├── services.py           # composition root
│   ├── job_input.py          # vaga colada -> Job normalizado
│   ├── profile/repository.py # perfil .md -> CandidateProfile
│   ├── scoring/              # dimensions.py (7 dimensoes) + scorer.py
│   ├── applications/         # repository.py, dedupe.py, builder.py
│   ├── resume/tailor.py      # personalizacao + FactGuard
│   └── job_sources/          # base.py, mock.py, http_sources.py,
│                             # unavailable.py, registry.py
│
├── mcp-career/               # MCP 1 - logica de carreira
├── mcp-job-search/           # MCP 2 - obtencao de vagas
├── mcp-career-files/         # MCP 3 - leitura de arquivos (sandbox)
│
├── data/                     # UNICO diretorio visivel ao career-files
│   ├── profile/              # profile.md, skills.md, preferences.md
│   ├── resumes/              # curriculo-principal.md (+ variantes)
│   └── applications/         # applications.db (verdade) + .json (espelho)
│
├── agent/career-agent.md     # instrucoes de comportamento do agente
├── scripts/                  # install.ps1, start.ps1, test.ps1, configure-*
├── tests/                    # pytest
└── docs/                     # SECURITY.md, SCORING.md, ARCHITECTURE.md

2. Voraussetzungen

3. Installation

cd C:\career-agent
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Das Skript prüft Python, installiert uv, falls es fehlt, erstellt das .venv, installiert die Abhängigkeiten, erstellt die data/-Baumstruktur, generiert die .env aus der .env.example und validiert, dass die drei MCPs hochfahren.

Um die Konfiguration von Claude Desktop im selben Schritt zu speichern:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ConfigureClaude

4. Konfiguration

4.1 Füllen Sie Ihr Profil aus

Diese Dateien sind die einzige Wahrheit. Der Agent behauptet nie etwas, das nicht in ihnen steht.

Suchen Sie nach [PREENCHEN] — das sind die Felder, die der Agent nicht erfinden kann.

Zwei davon ändern den Score sofort:

• Anos de experiencia in profile.md: Solange es nao informado ist, bleibt der „Jahre“-Teil der Erfahrungsdimension neutral. Der Agent leitet diese Zahl nicht ab.

• Minimo / Alvo in preferences.md: Solange sie [PREENCHER] sind, bleibt die Gehaltsdimension für Stellen mit veröffentlichter Spanne neutral.

4.2 Passen Sie die .env an

CAREER_DATA_ROOT=C:\career-agent\data
CAREER_MIN_SCORE=70

JOB_SEARCH_ENABLE_NETWORK=true
JOB_SEARCH_SOURCES=ats
JOB_SEARCH_ATS_COMPANIES=greenhouse:stone,ashby:nubank,greenhouse:vtex,...
JOB_SEARCH_USER_AGENT=career-agent/1.0 (personal job search; contact: SEU-EMAIL)

Setzen Sie Ihre E-Mail in den User-Agent — sich zu identifizieren ist die höfliche Art, eine öffentliche API zu nutzen.

Unternehmen zur Suche hinzufügen

Die Quelle ats findet nur Stellen von Unternehmen, die Sie auflisten. Um ein Unternehmen hinzuzufügen, öffnen Sie dessen Karriereseite und schauen Sie sich die URL an:

Unternehmen, deren Karriereseite auf Gupy liegt, können nicht hinzugefügt werden — Gupy bietet keine öffentliche Suche. Für diese verwenden Sie den manuellen Modus.

Es gibt keine LinkedIn-Anmeldevariable in diesem Projekt. Das ist beabsichtigt.

5. Konfiguration von Claude Desktop

Automatisch (empfohlen)

powershell -ExecutionPolicy Bypass -File .\scripts\configure-claude-desktop.ps1

Das Skript erstellt ein Backup der vorhandenen Datei (.backup-AAAAMMDD-HHMMSS), erhält alle Ihre Konfigurationen und aktuellen MCPs und fügt/aktualisiert nur die drei Einträge des Career Agent.

Manuell

Datei: %APPDATA%\Claude\claude_desktop_config.json (in Ihrem Fall: C:\Users\Roger\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "career-agent": {
      "command": "C:\\career-agent\\.venv\\Scripts\\python.exe",
      "args": ["C:\\career-agent\\mcp-career\\server.py"]
    },
    "job-search": {
      "command": "C:\\career-agent\\.venv\\Scripts\\python.exe",
      "args": ["C:\\career-agent\\mcp-job-search\\server.py"]
    },
    "career-files": {
      "command": "C:\\career-agent\\.venv\\Scripts\\python.exe",
      "args": ["C:\\career-agent\\mcp-career-files\\server.py"]
    }
  }
}

Absolute Pfade. Wenn Sie das Projekt an einem anderen Ort installiert haben, ersetzen Sie C:\\career-agent durch Ihren tatsächlichen Pfad, in allen Vorkommen. Die umgekehrten Schrägstriche müssen verdoppelt werden — das ist JSON.

Warum das Python aus .venv und nicht uv? Claude Desktop startet die Server, ohne Ihr Benutzer-PATH zu laden. Direkt auf das Python der virtuellen Umgebung zu zeigen, eliminiert die PATH-Abhängigkeit und macht den Start schneller und vorhersehbarer. Das uv bleibt das Werkzeug für Installation und Testausführung.

Nach dem Speichern: Schließen Sie Claude Desktop vollständig (einschließlich des Symbols in der Taskleiste, neben der Uhr — das Schließen des Fensters beendet den Prozess nicht) und öffnen Sie es erneut.

Um zu bestätigen, fragen Sie im Chat: „Welche Career-Tools haben Sie?“

6. So starten Sie

Die Server werden von Claude Desktop selbst gestartet — Sie müssen nichts laufen lassen.

Um manuell zu prüfen, dass die drei hochfahren:

powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1

Logs: C:\career-agent\logs\ (mcp-career.log, mcp-job-search.log, mcp-career-files.log).

7. So testen Sie

powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1

Das Skript führt die pytest-Suite aus und anschließend eine Ende-zu-Ende-Validierung: Import der Module, Initialisierung der drei MCPs, Lesen des Profils, Berechnung des Scores, Registrierung einer Bewerbung, Abfrage des Verlaufs und Erkennung von Duplikaten.

Nur die Unit-Tests:

C:\career-agent\.venv\Scripts\python.exe -m pytest tests -v

8. So fügen Sie eine neue Stellenquelle hinzu

Vor allem: Prüfen Sie, ob die Quelle eine dokumentierte öffentliche API hat. Wenn sie Login, Cookie oder Scraping erfordert, kommt sie nicht in Frage — verwenden Sie UnavailableJobSource und den manuellen Modus.

1. Erstellen Sie die Klasse in src/career_core/job_sources/:

from .base import IJobSource, JobQuery, SourceResult, detect_seniority

class MinhaFonteJobSource(IJobSource):
    name = "minhafonte"
    provenance = "API JSON publica de X, sem autenticacao."
    usable = True

    def search(self, query: JobQuery) -> SourceResult:
        # ... chamar a API e converter cada item em `Job`
        return SourceResult(source=self.name, jobs=jobs, ok=True, message="...")

2. Registrieren Sie sie in src/career_core/job_sources/registry.py:

_FACTORIES = {
    ...,
    "minhafonte": (lambda s: MinhaFonteJobSource(...), True),  # True = precisa de rede
}

3. Aktivieren Sie sie in der .env: JOB_SEARCH_SOURCES=mock,minhafonte

4. Fügen Sie einen Test in tests/test_job_sources.py hinzu.

Keine andere Datei des Systems ändert sich. Score, Deduplizierung und Bewerbung funktionieren automatisch, weil die Quelle ein normalisiertes Job-Objekt zurückgibt.

9. So fügen Sie einen neuen Lebenslauf hinzu

Legen Sie eine .md-Datei in C:\career-agent\data\resumes\ ab. Der Dateiname ist wichtig: Der Agent wählt automatisch den Lebenslauf aus, dessen Name die meisten gemeinsamen Wörter mit der Stelle hat.

data/resumes/
├── curriculo-principal.md      # padrao / fallback
├── curriculo-backend-dotnet.md # vence em vagas .NET/backend
├── curriculo-fullstack.md      # vence em vagas fullstack/React
└── curriculo-sap.md            # vence em vagas SAP

Um einen bestimmten zu erzwingen: „Bereiten Sie die Bewerbung mit curriculo-sap.md vor“.

10. So registrieren Sie eine Bewerbung

Lebenszyklus:

   generate_application          register_application
   (mostra o pacote)      -->    (grava o historico)
                                        |
                                        v
                                pending_approval
                                        |
                          voce aprova   |
                                        v
                                    approved
                                        |
                    VOCE se candidata no site
                                        v
                                     applied
                                        |
              +-------------+-----------+-----------+
              v             v           v           v
          interview  technical_test   offer     rejected

rejected und withdrawn sind Endzustände.

Es gibt keinen Weg von pending_approval direkt zu applied. Der Versuch wird von der Zustandsmaschine abgelehnt. Das ist die Garantie im Code, dass nichts voranschreitet, ohne dass Sie es gesehen haben.

11. Beispiele für Befehle in Claude Desktop

Suchen

Procure vagas Backend .NET compativeis com meu perfil.
Priorize remoto e hibrido em Goiania.
Mostre somente vagas com score >= 80.

Eine eingefügte Stelle analysieren

Analise esta vaga:
[cole aqui a URL e a descricao completa]

Bewerbung vorbereiten

Prepare minha candidatura para a vaga da Nexatech.

Verfolgen

Mostre minhas candidaturas pendentes.
Quais candidaturas estao aguardando minha aprovacao?
Atualize a candidatura app-xxxx para entrevista.

Genehmigen

Aprovo a candidatura app-xxxx.

Diagnose

Esta tudo configurado no Career Agent?
De onde vem as vagas que voce busca?
Voce consegue se candidatar por mim no LinkedIn?

12. Aktuelle Einschränkungen

• LinkedIn, Indeed und Gupy funktionieren im manuellen Modus. Keiner von ihnen bietet eine öffentliche Such-API für Kandidaten. Sie kopieren die Stelle; der Agent macht den Rest. Das ist eine Sicherheitsentscheidung, keine offene Aufgabe.

• Die automatische Abdeckung hängt davon ab, welche Unternehmen Sie konfigurieren. Die Quelle ats durchsucht die öffentlichen Boards der Unternehmen in JOB_SEARCH_ATS_COMPANIES. Die Standardliste hat 10 verifizierte Unternehmen (~1.160 Stellen), aber der brasilianische Markt hat viel mehr — fügen Sie die Unternehmen hinzu, die Sie interessieren.

• Nicht jedes ATS ist abgedeckt. Greenhouse, Lever und Ashby haben einen öffentlichen Endpunkt. Gupy, Solides und Kenoby bieten keine öffentliche Suche für Kandidaten.

• Remotive und Arbeitnow dienen nur wenig (gemessen im August/2026): Remotive liefert einen Stichproben-Feed von 14 Stellen, der den Parameter search ignoriert; Arbeitnow hat 175 Stellen, fast alle europäisch und in Präsenz, null mit .NET/C#. Sie bleiben verfügbar, aber außerhalb des Standards.

• LinkedIn, Indeed und Gupy bleiben im manuellen Modus — sie haben keine öffentliche Such-API für Kandidaten, und dieses Projekt automatisiert weder Login noch Scraping.

• Die Anforderungsextraktion ist heuristisch. Sie funktioniert gut mit Beschreibungen in Aufzählungspunkten; bei Fließtext kommen die Anforderungen weniger strukturiert heraus.

• Die Senioritätserkennung erfolgt per Stichwort im Titel und in der Beschreibung. Mehrdeutige Titel können als nao_informado ausgegeben werden — geben Sie manuell an, wenn Sie importieren.

• Gehalt wird nur verglichen, wenn die Stelle die Spanne veröffentlicht. Die meisten brasilianischen Stellen veröffentlichen sie nicht; in diesem Fall bleibt die Dimension neutral.

• Der personalisierte Lebenslauf wird in Markdown ausgegeben. Es gibt keinen Export nach PDF oder DOCX in V1.

• Einzelbenutzer-Installation, lokal. Kein Mehrbenutzer, keine Synchronisierung.

13. Nächste Schritte

Sortiert nach Wert/Aufwand-Verhältnis:

1. Lebenslauf als PDF/DOCX exportieren — heute wird das Material in Markdown ausgegeben und du konvertierst es von Hand.

2. Stellenausschreibung von einer öffentlichen URL lesen (offene Karriereseiten, ohne Anmeldung), um das Kopieren und Einfügen zu reduzieren.

3. Brasilianische Quellen — ATSs identifizieren, die einen öffentlichen Endpunkt für Stellenausschreibungen pro Unternehmen bereitstellen, und als IJobSource implementieren.

4. Follow-up-Erinnerungen — Bewerbungen markieren, die seit mehr als N Tagen auf applied stehen.

5. Trichter-Kennzahlen — Antwortrate nach Score, Stack und Arbeitsmodell, um die Gewichte mit echten Daten zu kalibrieren.

6. Gewichtskalibrierung — aktuell sind es die in der Spezifikation festgelegten Gewichte; mit ausreichend Verlauf basierend auf dem anpassen, was tatsächlich konvertiert.

7. Erkennung semantischer Duplikate — derzeit über Textähnlichkeit; Embeddings würden „Dev Backend .NET“ vs. „Softwareentwickler C#“ erfassen.

Sicherheit

Zusammenfassung dessen, was dieses Projekt nicht tut, by design:

Details in docs/SECURITY.md.

Der Zugriff auf Claudes Dateien ist auf C:\career-agent\data beschränkt. Er sieht weder C:\ noch deinen Benutzerordner noch den Code des Projekts selbst.