Skip to main content
Glama
mcp-job-radar

mcp-job-radar

by RaphaelCerri

MCP Job Radar

English · Português

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

CI Python 3.11+ MCP 2026-07-28 License MIT

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.

Related MCP server: entra-mcp

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.

Available Tools

4 tools
explain_matchB
Read-onlyIdempotent

Explain the score, supporting signals, and tradeoffs for one known job.

Inputs: job_id (required), profile (required). Returns: score, job_id, reasons, tradeoffs, +1 more

export_shortlistA
Read-onlyIdempotent

Render a shortlist for the client. This tool never writes files or applies to jobs.

Inputs: job_ids (required), format. Returns: format, content, persisted, item_count

rank_jobsA
Read-onlyIdempotent

Rank known jobs with a deterministic, transparent scoring policy.

Inputs: job_ids (required), profile (required), limit. Returns: jobs, returned

search_jobsC
Read-onlyIdempotent

Search trusted listing fields. Descriptions are sanitized and never interpreted.

Inputs: query (required), limit, remote_only. Returns: jobs, query, returned, total_scanned

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinctly different purpose: search finds jobs, rank orders known jobs, explain provides reasoning for one job, and export renders a shortlist. There is no overlap or ambiguity in their roles.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (export_shortlist, search_jobs, rank_jobs, explain_match), with clear action-oriented verbs and descriptive nouns. The pattern is uniform.

    Tool Count5/5

    With 4 tools, the server is precisely scoped for a job radar workflow: search, rank, explain, and export. Each tool is essential and there is no bloat or redundancy.

    Completeness5/5

    The tool set covers the complete lifecycle of the domain: discovering jobs (search), evaluating them (rank), understanding results (explain), and producing output (export). No critical operations are missing for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search and analyze job listings from verified company boards privately, matching resumes to roles with evidence and suggesting resume improvements.
      30 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search verified tech and AI jobs, match resumes to roles with explainable fit scores, retrieve salary statistics, and prepare human-in-the-loop applications via the ENTRA job platform.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to search live public job listings, compare roles side by side, retrieve full job details, and render interactive job cards with application links from AI chat clients.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to search public job listings and retrieve details for individual postings from inside AI assistants, including ranked results, filters, and pagination. It is read-only and requires no account, authentication, or API key.
      MIT