Stepstone

Servidor MCP de Busca de Empregos Stepstone

Um servidor Model Context Protocol (MCP) que permite que clientes compatíveis com MCP pesquisem no portal de empregos alemão Stepstone.de. O serviço expõe um par de ferramentas para executar buscas de empregos com múltiplos termos e obter detalhes ricos de vagas, para que assistentes como Claude Desktop ou Smithery possam exibir vagas atualizadas.

Sumário

1. Recursos Principais
2. Início Rápido
3. Configuração
4. Uso
5. Visão Geral da Arquitetura
6. Desenvolvimento Local
7. Testes
8. Solução de Problemas
9. Contribuição
10. Suporte
11. Histórico de Versões
12. Licença

Recursos Principais

• 🔍 Busca Multi-termo – Consulta o Stepstone simultaneamente para cada frase de pesquisa fornecida e remove duplicatas de anúncios.
• 📍 Segmentação por Localização – Suporta códigos postais alemães com raio configurável (1–100 km) para buscas regionais.
• 🧠 Acompanhamentos com Sessão – Salva resultados por uma hora para que você possa solicitar detalhes completos da vaga posteriormente via get_job_details.
• 🛡️ Validação Robusta – Validação defensiva de parâmetros, registro de logs e mensagens de erro elegantes para solicitações malformadas.
• 🐳 Compatível com Contêiner e CLI – Funciona como um processo Python simples ou dentro do Docker; integra-se perfeitamente com Smithery e Claude Desktop.

ℹ️ Nota: Um cache Redis e outros recursos de escalabilidade são mencionados como melhorias futuras. Eles não estão habilitados na versão atual.

Início Rápido

Pré-requisitos

• Python 3.8+
• pip
• Acesso à internet para alcançar Stepstone.de ao executar buscas reais.

Opções de Instalação

npx -y @smithery/cli install @kdkiss/mcp-stepstone --client claude

# Clone the repository
git clone https://github.com/kdkiss/mcp-stepstone.git
cd mcp-stepstone

# Install runtime dependencies
pip install -r requirements.txt

# (Optional) make the server script executable on Unix-like systems
chmod +x stepstone_server.py

# Build the image
docker build -t mcp-stepstone .

# Run the container
docker run -it --rm mcp-stepstone

Configuração

Configuração do Cliente MCP

Smithery mcp.json

{
  "mcpServers": {
    "stepstone-job-search": {
      "command": "python",
      "args": ["/path/to/stepstone_server.py"],
      "description": "Search for job listings on Stepstone.de",
      "env": {
        "LOG_LEVEL": "INFO",
        "REQUEST_TIMEOUT": "10"
      }
    }
  }
}

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stepstone-job-search": {
      "command": "python",
      "args": ["/absolute/path/to/stepstone_server.py"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "USER_AGENT": "MCP-Stepstone-Bot/1.0"
      }
    }
  }
}

Variáveis de Ambiente

Uso

Ferramentas Disponíveis

search_jobs

Executa uma ou mais buscas por palavras-chave no Stepstone.

Parâmetros

• search_terms (array de strings, opcional) – Frases de pesquisa para consultar. Padrão: ["fraud", "betrug", "compliance"].
• zip_code (string, opcional) – Código postal alemão de 5 dígitos. Padrão: "40210" (Düsseldorf).
• radius (inteiro, opcional) – Raio em quilômetros ao redor do código postal. Padrão: 5; deve estar entre 1 e 100.

get_job_details

Busca uma vaga armazenada e a enriquece com descrição completa e metadados.

Parâmetros

• job_index (inteiro, opcional) – Índice baseado em 1 nos resultados da sessão mais recente.
• job_query (string, opcional) – Correspondência difusa (fuzzy) com vagas armazenadas. O alias query também é aceito.
• session_id (string, opcional) – Identificador explícito de sessão (seleciona automaticamente a sessão ativa mais recente quando omitido).

⚠️ Forneça job_index ou job_query. Fornecer ambos prioriza job_index.

Exemplos de Invocação

// Basic search
{
  "tool": "search_jobs",
  "parameters": {
    "search_terms": ["software engineer", "developer"]
  }
}

// Location constrained search
{
  "tool": "search_jobs",
  "parameters": {
    "search_terms": ["marketing manager", "digital marketing"],
    "zip_code": "10115",
    "radius": 15
  }
}

// Fetch job details by index
{
  "tool": "get_job_details",
  "parameters": {
    "job_index": 1
  }
}

// Fetch job details by query string
{
  "tool": "get_job_details",
  "parameters": {
    "job_query": "AML Specialist",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Exemplo de Saída

Job Search Summary:
Search Terms: fraud analyst, compliance officer
Location: 60329 (±25km)
Total Jobs Found: 23
Session ID: 550e8400-e29b-41d4-a716-446655440000

--- Results for 'fraud analyst' ---

1. Senior Fraud Analyst - Digital Banking
   Company: Deutsche Bank AG
   Description: Join our fraud prevention team to analyze transaction patterns...
   Link: https://www.stepstone.de/stellenangebote--Senior-Fraud-Analyst-Frankfurt-Deutsche-Bank-AG--1234567

📋 Job Details: Senior Fraud Analyst - Digital Banking
🏢 Company: Deutsche Bank AG
📍 Location: Frankfurt am Main
💰 Salary: €65,000 - €85,000 per year
⏰ Employment Type: Full-time, Permanent

📝 Description:
Join our fraud prevention team to analyze transaction patterns and develop detection algorithms...

✅ Requirements:
  • Bachelor's degree in Computer Science, Finance, or related field
  • 3+ years experience in fraud detection or financial crime prevention
  • Strong analytical skills with SQL, Python, or R
  • Knowledge of AML regulations and compliance frameworks

Visão Geral da Arquitetura

┌────────────────────┐    ┌─────────────────────┐    ┌───────────────────┐
│    MCP Client      │ ──▶ │  MCP Stepstone      │ ──▶ │   Stepstone.de     │
│ (Claude/Smithery)  │    │      Server          │    │    Job Portal      │
└────────────────────┘    └─────────────────────┘    └───────────────────┘
                                │
                        ┌─────────────────────┐
                        │   Job Scraper       │
                        │ - URL Builder       │
                        │ - HTML Parser       │
                        │ - Data Cleaner      │
                        └─────────────────────┘

1. Solicitação – O cliente MCP envia a invocação da ferramenta.
2. Validação – Entradas validadas (termos, código postal, raio).
3. Busca – URLs construídas e buscadas simultaneamente.
4. Processamento – HTML analisado e entradas de vagas normalizadas produzidas.
5. Sessão – Resultados armazenados em memória por uma hora para consultas de acompanhamento.
6. Resposta – Resumo textual retornado ao cliente MCP.
7. Detalhes – get_job_details busca a página original da vaga e extrai especificidades.

Módulos principais:

• StepstoneJobScraper – Constrói URLs de busca, busca e analisa listagens de vagas.
• JobDetailParser – Extrai páginas detalhadas de vagas para salário, requisitos, etc.
• SessionManager – Armazena sessões de busca, suporta consulta por índice ou correspondência difusa.
• stepstone_server.py – Registra ferramentas/recursos MCP e lida com invocações de ferramentas.

Desenvolvimento Local

# Clone repository
git clone https://github.com/kdkiss/mcp-stepstone.git
cd mcp-stepstone

# Create & activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install dev tooling
pip install pytest pytest-asyncio black flake8

# Run formatter and linter
black stepstone_server.py
flake8 stepstone_server.py

Fixtures de Depuração

Um servidor HTTP leve está incluído para servir fixtures HTML empacotadas. Inicie-o ao ajustar seletores ou parsers:

python debug_server.py

Visite http://127.0.0.1:5000 para inspecionar as páginas simuladas do Stepstone usadas nos testes.

Adaptador de Transporte HTTP

Alguns ambientes MCP hospedados (como Smithery) exigem um endpoint HTTP com cabeçalhos CORS liberais em vez do transporte STDIO padrão. O projeto inclui um pequeno adaptador baseado em Starlette que expõe o servidor existente sobre o protocolo HTTP transmissível:

python stepstone_http_server.py

O servidor escuta em 0.0.0.0:8000 por padrão e responde a solicitações de preflight com Access-Control-Allow-Origin: *. Ajuste as variáveis de ambiente HOST e PORT ao implantar em plataformas que exigem interfaces ou portas específicas.

Testes

A suíte de testes usa respostas de rede simuladas para evitar contato com Stepstone.de.

pip install -r requirements.txt pytest
pytest

Para validar fluxos específicos de ferramentas interativamente, você pode executar stepstone_server.py diretamente ou chamar handle_call_tool de um shell Python.

Solução de Problemas

O Servidor Não Inicia

python --version            # Expect 3.8+
pip list | grep -E "(requests|beautifulsoup4|mcp)"
ls -la stepstone_server.py   # Confirm execute permissions when running directly

Nenhuma Vaga Retornada

• Verifique se o código postal é um PLZ alemão válido de cinco dígitos.
• Aumente radius ou amplie search_terms.
• Confirme a conectividade com a internet.
• Mudanças no layout do Stepstone podem exigir atualização dos seletores—use o servidor de depuração para comparar fixtures.

Erros de Importação

pip install -r requirements.txt
pip install --upgrade pip

Habilitar Logs Detalhados

export LOG_LEVEL=DEBUG
python stepstone_server.py

Os logs são emitidos para stdout; integre com sua própria infraestrutura de logs, se desejado.

O Scanner Smithery Não Consegue Inicializar a Conexão

Se a CLI do Smithery relatar mensagens repetidas de HTTP error: This operation was aborted ou McpError: MCP error -32001: Request timed out ao escanear o servidor, o processo MCP iniciou com sucesso, mas o handshake JSON-RPC falhou. Causas e soluções típicas:

1. Cabeçalhos CORS ausentes – Garanta que seu transporte HTTP retorne cabeçalhos CORS permissivos:

   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
   res.setHeader("Access-Control-Allow-Headers", "Content-Type");
   

2. Inicialização lenta – Aumente os timeouts do cliente (exemplo de snippet mcp.json do Smithery):

   {
     "mcpServers": {
       "stepstone-job-search": {
         "type": "streamable-http",
         "url": "http://localhost:3000/mcp",
         "initTimeout": 30000,
         "timeout": 60000
       }
     }
   }
   

3. Incompatibilidade de endpoint – Confirme que o servidor está acessível onde o cliente espera (por exemplo, curl -v http://localhost:3000/mcp). Se os logs do Smithery mostrarem HTTP POST → undefined, verifique novamente a URL configurada ou o vínculo de transporte.

Ao depurar, inicie o servidor manualmente via npx -y @smithery/cli serve para observar se ele sai prematuramente ou registra problemas de vínculo.

Contribuição

1. Faça um fork do repositório e crie um branch de recurso: git checkout -b feature/my-change.
2. Implemente suas alterações e adicione testes.
3. Execute pytest e faça lint/formatação do código (black, flake8).
4. Abra um pull request descrevendo a alteração.

Diretrizes de codificação:

• Siga PEP 8 e inclua dicas de tipo quando prático.
• Documente funções públicas com docstrings.
• Trate erros de rede e análise defensivamente.

Suporte

• 📖 Consulte este README para dicas de configuração e uso.
• 🧪 Use o servidor de depuração para inspecionar o HTML dos fixtures quando os seletores quebrarem.
• 🐛 Registre bugs ou solicitações de recursos via GitHub Issues.
• 💬 Participe da comunidade Discord do projeto (link em breve).

Histórico de Versões

v1.2.0 (Atual)

• Adicionada a ferramenta get_job_details para consultas de acompanhamento.
• Introduzido gerenciamento de sessão com TTL de uma hora.
• Aprimorada a análise de detalhes para salário, requisitos e benefícios.
• Os resumos agora incluem IDs de sessão para facilitar o acompanhamento.

v1.1.0

• Documentação e exemplos de uso expandidos.
• Adicionado suporte a Docker e configuração por variáveis de ambiente.
• Melhorias no tratamento de erros e validação.

v1.0.0

• Lançamento inicial com busca de empregos multi-termo e conformidade com MCP.

Licença

Distribuído sob a Licença MIT.

Feito com ❤️ para o mercado de trabalho alemão.