Career Scout

CI CodeQL License: MIT Python 3.13 Debian

A production-grade Model Context Protocol (MCP) server demonstrating the wrapping pattern for AI-augmented data pipelines. Built as a standalone artifact: one LXC container, one Cloudflare Tunnel, one repo. Self-hosted via Ollama + LiteLLM SDK.

This server demonstrates the pattern I would apply to wrap Career Scout — my private job-search scoring pipeline. Synthetic data committed here for portability and reproducibility.

Documentation

Full architecture and design decisions: career-scout-mcp.stojadinovic.at

Stack

• Python 3.13 (mypy strict)
• MCP SDK with decorator-based primitive registration
• LiteLLM SDK — provider-agnostic LLM routing, model-swappable via env
• Ollama + Qwen 2.5 3B (default) — self-hosted, biomedical-research-portable
• Pydantic for config + tool schemas
• loguru structured JSON logging with secret redaction
• Debian 13 LXC, cloudflared edge termination, nginx static docs

Prerequisites

• Python 3.13 (uv manages this automatically)
• uv — dependency and environment management
• Ollama — default local LLM provider for qwen2.5:3b

Memory: Ollama's headroom calc for qwen2.5:3b requires ~6 GiB of available memory (it counts buff/cache as unavailable). A 4 GiB system may fail to load the model even though it's 1.9 GB on disk.

Debian 13

sudo apt-get update && sudo apt-get install -y curl ca-certificates zstd
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:3b

Note: zstd is required by the Ollama installer for archive extraction on minimal Debian; not all base images include it.

macOS

brew install uv ollama
ollama serve &
ollama pull qwen2.5:3b

Windows

uv installer · Ollama installer, then ollama pull qwen2.5:3b.

Quick start (local stdio)

uv sync
uv run python -m career_scout_mcp

The server exposes 4 tools, 5 resources (6 URIs), and 2 prompts via stdio. Connect from Claude Desktop, Claude Code, or OpenCode by pointing them at this binary.

Try it out

The fastest way to exercise the server is via MCP Inspector:

npx @modelcontextprotocol/inspector uv run python -m career_scout_mcp

Opens a browser UI at localhost:6274 where you can list resources, render prompts, and invoke tools end-to-end against your local Ollama.

Development

Dev workflow uses OpenCode + standard Python tooling. See CONTRIBUTING.md.

Security

See SECURITY.md for reporting. Key posture:

• All SQL parameterized (never f-string)
• Pydantic input validation on every tool entry
• Path traversal prevention on resource URIs
• systemd hardening (non-root, ProtectSystem=strict, etc.)
• MCP server NEVER publicly exposed (stdio default, HTTP bound 127.0.0.1 only)
• TLS via Cloudflare edge — no local cert management surface
• Docs deploy via manual scripts/deploy_docs.sh. MCP server is never publicly exposed — stdio default; HTTP transport loopback-only behind Bearer auth (hmac.compare_digest).

License

MIT — see LICENSE.

Built by Stefan Stojadinovic, Vienna. Contact: [email protected]