# MCP Job Radar

> **English** · [Português](README.pt-BR.md)

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

[![CI](https://github.com/RaphaelCerri/mcp-job-radar/actions/workflows/ci.yml/badge.svg)](https://github.com/RaphaelCerri/mcp-job-radar/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP 2026-07-28](https://img.shields.io/badge/MCP-2026--07--28-5A45FF)](https://modelcontextprotocol.io/)
[![License MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

```bash
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

```mermaid
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](docs/ARCHITECTURE.md) and the
[adversarial test matrix](docs/ADVERSARIAL-TESTS.md).

## 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

```json
{
  "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:

```bash
uv run mcp-job-radar
```

Example host configuration:

```json
{
  "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`](https://github.com/RaphaelCerri/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.