MCP Job Radar

English · Português

A secure, read-only Model Context Protocol server for job discovery and explainable matching.

Job descriptions can contain prompt injections, commands, secret requests, and malicious links. This server exposes job-search capabilities to AI hosts without turning untrusted listings into an instruction channel. Every tool is typed, bounded, audited, read-only, and exercised through a real in-memory MCP client.

What a reviewer can verify in three minutes

uv sync --extra dev
uv run pytest
uv run mcp-job-radar-demo

The demo connects an official MCP client to the server, discovers the tools through tools/list, calls search_jobs, and prints its structured result. Tests cover tool discovery, JSON Schema, deterministic ranking, typed errors, timeouts, retries, circuit breaking, and adversarial content.

Tools

Tool	What it returns	Safety boundary
search_jobs	Bounded matches from title and declared skills	Descriptions do not affect search
rank_jobs	Score, reasons, and tradeoffs against a typed profile	Deterministic policy, no hidden LLM judgment
explain_match	Exact factors behind one score	Same policy as ranking, no post-hoc explanation
export_shortlist	Markdown or JSON inside the response	No filesystem write or job application

All inputs and outputs use strict Pydantic models. Invalid, missing, duplicate, or excessive input produces a stable machine-readable error rather than an implementation traceback.

Architecture

flowchart LR
    H[AI host] -->|MCP| M[MCP adapter]
    M --> A[Safe audit boundary]
    A --> S[Typed job service]
    S --> R[Deterministic ranker]
    S --> G[Untrusted-content gateway]
    S --> D[Timeout, retry, circuit breaker]
    D --> F[(Normalized fixtures)]
    G -->|bounded and redacted| M

The MCP adapter contains no ranking logic. The application service owns use cases, the security gateway owns the trust boundary, and the repository owns source resilience. This separation keeps the protocol replaceable and the critical policies independently testable.

Read the full architecture and threat model and the adversarial test matrix.

Security controls

• Job descriptions are bounded, normalized, scanned, and redacted before entering agent context.
• Prompt-injection phrases, secret requests, commands, and embedded URLs become explicit findings.
• Listing URLs must use public HTTPS and cannot contain credentials or target local/private hosts.
• Result count and batch IDs are capped at 25.
• Source access has a timeout, bounded retry, and an in-process circuit breaker.
• Audit events contain tool name, status, duration, and error type, never arguments or result bodies.
• There is intentionally no command execution, arbitrary fetch, local-file read, auto-apply, or persistent export capability.

Example request

{
  "job_ids": ["remoteok-1001", "remotive-3003"],
  "profile": {
    "target_titles": ["AI Engineer", "AI Solutions Architect"],
    "skills": ["Python", "RAG", "LLM", "MCP"],
    "remote_required": true,
    "seniority": "senior",
    "minimum_salary_brl": 20000
  },
  "limit": 10
}

The result carries a numerical score plus positive signals and explicit tradeoffs. Explanations are generated by the same scoring function, so they cannot drift from the ranking.

Run as an MCP server

The default transport is stdio:

uv run mcp-job-radar

Example host configuration:

{
  "mcpServers": {
    "job-radar": {
      "command": "uv",
      "args": ["--directory", "ABSOLUTE_PATH_TO_REPOSITORY", "run", "mcp-job-radar"]
    }
  }
}

The project uses the official Python SDK v2 and its current MCP 2026-07-28 protocol line. The automated integration test uses Client(mcp), the SDK's in-memory client, rather than invoking Python functions directly.

Relationship to radar-de-vagas

radar-de-vagas owns ingestion from six public sources, two-layer relevance filtering, normalization, global deduplication, and priority ordering. mcp-job-radar adds the agent-facing contract and security boundary. Its checked-in normalized dataset makes tests deterministic and keeps CI independent of scraping, credentials, rate limits, and third-party outages.

Measured behavior

The acceptance suite verifies:

• exactly four discoverable MCP tools;
• structured MCP results and generated input schemas;
• repeatable ranking and matching explanations;
• all defined hostile-content classes redacted;
• unsafe URL classes rejected;
• malformed and slow sources returned as typed retryable failures;
• no auto-application or persistent-write surface.

Coverage is enforced at 85% in CI. The README reports only behaviors asserted by the repository, not production traffic or synthetic business-accuracy claims.

Verification-driven adjustments

• The implementation was aligned to the installed MCP SDK v2 API after an integration test verified the moved ToolError boundary and the typed list_tools() response envelope.
• The normalized fixture was moved inside the Python package after inspecting the built wheel. This prevents a demo that works only from an editable source checkout.
• Read-only, non-destructive, idempotent, and closed-world annotations are asserted on all four discovered tools, so the published metadata is checked rather than merely documented.

Limitations and next steps

• The demo data is synthetic and normalized. It proves the agent boundary, not live-source uptime.
• Ranking is lexical and policy-based; semantic equivalence and career nuance remain outside v0.1.
• The circuit breaker is process-local. A distributed deployment would require shared state and metrics.
• A live adapter should consume a versioned normalized output from radar-de-vagas, not import its script or duplicate source-specific scraping.
• Authentication and Streamable HTTP deployment are intentionally absent from this local stdio demonstration. They become necessary only when exposing the server beyond a trusted host.

AI assistance disclosure

The repository was developed with AI-assisted implementation and review. Architecture, security claims, tests, limitations, and published artifacts were checked against executable behavior. Authorship responsibility and final technical decisions remain with Raphael Caveagna.