convez.ai
MCP ServerIntegração & APIsIntermediário
odanree

Beacon MCP – Gerenciador de Perfil e Busca de Empregos

odanree/beacon-mcp

Gerencie seu perfil Beacon e pipeline de empregos via Claude, sem terminal.

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe a API REST do Beacon (pipeline de busca de empregos) para Claude Code, permitindo adicionar projetos ao perfil, listar e inspecionar vagas conversacionalmente. Elimina a necessidade de chamar curl + JWT manualmente, transformando operações complexas em prompts naturais.

Instalação

$npx convez-ai odanree/beacon-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Adicionar projetos ao portfólio durante sessões de chat com Claude
  • Listar e filtrar vagas por estágio do pipeline (screen, interview, etc)
  • Inspecionar detalhes completos de uma vaga (JD, histórico, etc)
  • Automação de atualização de perfil profissional sem sair do IDE

Veredito

Solução bem arquitetada para quem usa Beacon + Claude Code. Reduz significativamente o atrito operacional ao converter fluxos curl complexos em prompts naturais. Cobertura de testes sólida (9 testes com mocks via respx) e autenticação JWT já considerada; pronto para uso em produção com extensões planejadas (busca + resume generator).

README

A tradução para o português deste README ainda está na fila.

beacon-mcp

MCP server wrapping the Beacon job-search-pipeline REST API so Claude Code can add projects, list/inspect jobs, and (eventually) drive the resume generator without me ever opening a terminal to write curl and a JWT heredoc again.

MCP · FastMCP · Beacon · Claude Code · Pydantic v2 · httpx · respx

ToolWhat it does
beacon_add_projectPOST /api/profile/projects — capture a project for resume generation
beacon_list_projectsGET /api/profile/projects — see what's already on the profile
beacon_list_jobsGET /api/jobs filtered by pipeline status
beacon_get_jobGET /api/jobs/{id} — full record + JD text

Why this exists

I added three portfolio projects to my Beacon profile during a single Claude session. Each one was 80 lines of curl + JSON-body + JWT-cookie-from-DevTools + bash-heredoc-syntax-vs-PowerShell. Three times. With encoding errors and reshuffled apostrophes.

This server reduces every one of those incidents to:

"Add a Beacon project — name: infra-mcp, url: https://github.com/odanree/infra-mcp, tech stack: MCP / FastMCP / pytest, outcome: …"

The model fills the schema, the tool POSTs, done.

Auth

Beacon uses Google OAuth → JWT. Easiest way to get the token:

  1. Sign in to your Beacon instance in the browser
  2. DevTools → Application → Cookies → copy the value of access_token
  3. Paste into .env as BEACON_JWT=… (and set BEACON_API_URL to your deployment)

When the token expires (typically 24h–30d depending on your config) any tool call returns {"ok": false, "error_kind": "auth", "error": "..."} and the model knows to ask you to refresh. The error message includes the exact step to do so.

Install

git clone https://github.com/odanree/beacon-mcp
cd beacon-mcp
python -m venv .venv
.venv/Scripts/activate
pip install -e ".[dev]"
cp .env.example .env       # paste BEACON_JWT

Register with Claude Code (user-scope)

claude mcp add beacon -s user -- "/abs/path/to/beacon-mcp/.venv/Scripts/python.exe" -m server.main
claude mcp list

Try:

"List my Beacon projects."

"Add a new Beacon project — name 'beacon-mcp', url 'https://github.com/odanree/beacon-mcp', tech stack ['MCP', 'FastMCP', 'pytest-asyncio'], outcome '4 tools, 9 tests, replaces the curl+JWT+heredoc dance every time I want to update my resume profile.'"

"List my jobs in the screen stage."

Tests

pytest
# All HTTP mocked via respx — no network calls, no real Beacon hits.

9 tests covering:

  • Authenticated POST flows (project create)
  • 401 vs 5xx error mapping (clear error kinds — auth vs http)
  • Missing JWT detection at the client boundary
  • Pagination + status filter param passing
  • Both envelope shapes Beacon endpoints can return ([…] and {items: […]})

Roadmap

  • beacon_search_jobs(query) — natural-language job search, once Beacon's search endpoint stabilizes
  • beacon_generate_resume(job_id) — kick the resume generator for one JD and return the markdown
  • beacon_score_resume(jd_text) — score arbitrary JD text against the user's profile (good for quick "should I apply?" calls)
  • Move JWT from .env to keyring storage on the host

License

MIT

Ver o original no GitHub

Bom para

Relacionados