🇩🇪 Germany Intelligence MCP

An evidence-based career intelligence layer for the German software job market, exposed to Claude as an MCP server.

Not a job search tool. A decision engine that answers one question every morning:

“What should I learn today to maximise my chances of getting a software engineering job in Germany?”

⚠️ Read this before using it

v1.0 Core is infrastructure, not a finished product. Its own QA pass graded it C — Needs Another Stabilization Sprint, and that assessment is published in full:

👉 docs/KNOWN-ISSUES.md — every defect, measured, reproducible, and pinned by a test.

This honesty is deliberate. The project's core promise is that no claim is made without evidence, and that has to apply to claims about the project itself.

Related MCP server: LinkedIn Profile MCP Server

The idea

Most job tools optimise for finding postings. This one assumes finding jobs is easy and knowing what to learn is hard. It treats the job market as a dataset and asks what the evidence actually says.

                          ┌──────────────────────────────┐
                          │   Claude (reasoning layer)   │
                          └───────────────┬──────────────┘
                                          │ MCP / JSON-RPC over stdio
    ┌─────────────────────────────────────▼─────────────────────────────────────┐
    │  L5  MCP TOOL SURFACE       10 coarse tools · Zod-validated · evidence     │
    ├───────────────────────────────────────────────────────────────────────────┤
    │  L4  ENGINES                trend · essentialism · gap · match · learning  │
    ├───────────────────────────────────────────────────────────────────────────┤
    │  L3  KNOWLEDGE STORE        SQLite + FTS5 · repositories own all SQL       │
    ├───────────────────────────────────────────────────────────────────────────┤
    │  L2  ANALYSIS PIPELINE      normalise → extract → classify → dedupe        │
    ├───────────────────────────────────────────────────────────────────────────┤
    │  L1  SOURCE ADAPTERS        anti-corruption layer · one interface, N APIs  │
    └───────────────────────────────────────────────────────────────────────────┘

Dependency rule: arrows point downward only. An engine never imports a source adapter; a source adapter never imports the database.

What "evidence-based" means here

No number is emitted without its denominator. This is enforced by the type system and the database schema, not by convention:

interface Evidence {
  subject: string;         // "ops.docker"
  frequency: number;       // 0.63
  observedIn: number;      // 214   ← the numerator
  totalAnalysed: number;   // 339   ← THE DENOMINATOR
  windowDays: number;      // 14
  sampleJobIds: string[];  // openable, verifiable
  meanConfidence: number;  // how good was the extraction behind this
  lowConfidence: boolean;  // sample too small to act on
}

recommendation.evidence is NOT NULL. pickTodayFocus() cannot compile without threading evidence through. A recommendation you cannot defend is unrepresentable.

Quick start

git clone https://github.com/mohitakki/germany-intelligence-mcp.git
cd germany-intelligence-mcp

npm ci                                              # no native build, no compiler
cp .env.example .env
cp config/profile.example.json config/profile.json  # then edit your skill levels

npm test          # 106 tests, ~40 against real SQLite
npm run ingest    # live fetch from the German market
npm run health    # is the data trustworthy right now?

No native dependencies. Storage is node:sqlite behind a driver port — see ADR-006 for why that decision and a production bug were the same decision.

npm run build

claude_desktop_config.json:

{
  "mcpServers": {
    "germany-intelligence": {
      "command": "node",
      "args": ["--no-warnings", "/absolute/path/to/germany-intelligence-mcp/dist/index.js"],
      "env": {
        "GIM_DATA_DIR": "/absolute/path/to/germany-intelligence-mcp/data",
        "GIM_PROFILE_PATH": "/absolute/path/to/germany-intelligence-mcp/config/profile.json"
      }
    }
  }
}

Restart Claude, then ask: "Run my daily briefing."

MCP tools

Ten coarse tools, not thirty. Every description is loaded into Claude's context on every turn, so tool sprawl directly degrades reasoning quality.

Data sources

Only sources that permit programmatic access are shipped.

None offer an open job-search API. All four prohibit automated access in their Terms of Service and enforce it technically. No adapter ships for them and none should be added — an IP ban is the mild outcome; a legal notice while applying for a German work visa is the bad one.

src/sources/custom/ exists for sources you have a legitimate route to: company career feeds, boards with a documented API, partner feeds, manual CSV import.

See ADR-001.

How a recommendation earns its place

Five gates, all of which must pass:

1. Sample floor — ≥ 20 deduplicated jobs analysed

2. Evidence floor — the skill appears in ≥ 5 postings

3. Relevance floor — ≥ 10% of jobs request it

4. Deficit — your self-assessed level is below 4/5

5. Cooldown — not recommended in the last 21 days

Survivors are ranked:

priority = marketFrequency × skillDeficit × momentum

Multiplicative, not additive — so a skill you already have scores ≈ 0 no matter how in-demand it is. That is the mechanism that stops the system telling you to learn React for the fortieth time.

The engineering story

This repo went through four adversarial cycles after "done". Each one is documented, because the findings are more interesting than the code.

🔴 The write path was dead and the run said ok

JobRepository.upsert ended with INSERT INTO job_fts (...) ON CONFLICT DO NOTHING. SQLite rejects UPSERT against a virtual table. Every insert threw, runIngest caught it per-job, and the run reported success having stored nothing.

The schema had been "verified" by running a hand-written query against hand-inserted rows — never the repository's own statement. A test that doesn't cross the boundary tests nothing. → ADR-006

🔴 A Berlin train line was inflating AWS demand

Eight of twelve ordinary German sentences produced phantom skill demand:

The defect wasn't the aliases — it was the default. A token was assumed technical unless something stopped it. Now ambiguous aliases are assumed non-technical unless a requirement marker or a confirmed technology list proves otherwise. → ADR-003

🔴 The dedup threshold was picked, not measured

Version one used Hamming ≤ 3 because it "felt safely conservative." It matched nothing but byte-identical text.

 0 bits  identical                    11 bits  ~15% extra boilerplate
 5 bits  hyphenation edit             13 bits  bullets reordered
 9 bits  one extra sentence           31 bits  a completely different job

Real variants cluster at 5–13; unrelated documents sit past 30. 12 sits in a wide, empty gap. → ADR-002

🔴 The extractor was accurate; the data was wrong

Ground truth over 111 real postings: 96.6% recall, 1 false positive in 59 mentions. The extractor is fine. The corpus genuinely contains almost no React/TypeScript work — TypeScript appears in 3 of 111 postings.

Diagnosing this as a source selection problem rather than an extraction problem is the difference between fixing it and tuning the wrong knob.

Documentation

Testing

106 tests. ~40 cross into real SQLite. Three suites, three jobs:

npm test                                   # everything
npx tsx --test tests/regressions.test.ts   # one block per shipped bug
npx tsx --test tests/corpus.test.ts        # 111 real postings, pinned baselines

• extraction.test.ts — pure logic: German gender markers, company suffixes, SimHash, the essentialism filter

• regressions.test.ts — one describe per critical bug, with the original defect in the comment so nobody "fixes" the test later

• ingest.test.ts — pipeline → repository → SQLite, error isolation, migration idempotency

• corpus.test.ts — 111 real German postings. Pins the measured baselines and the known defects. When you fix one, its test fails — that failure is the proof.

The corpus is committed so every number in the docs is reproducible.

Security

• Prompt injection — job text is attacker-controlled. Nonce-delimited envelope built before the LLM path exists; detection counts, never filters (ADR-004)

• Credential redaction — no query string ever reaches a log line, enforced at the boundary and again centrally

• SQL injection — fully parameterised; verified against '); DROP TABLE job;--

• Adversarial robustness — 27 hostile inputs (500 KB descriptions, malformed HTML, emoji, RTL, null bytes, FTS syntax), zero crashes

Contributing

Personal project, but the patterns are reusable. If you fork it:

1. Read ADR-003 before touching the taxonomy — several constraints look arbitrary and are load-bearing

2. npm test must stay green; the false-positive corpus is the guard rail

3. New decisions get a new ADR — template. ADRs are immutable once Accepted; supersede, don't edit

MIT · Built as a systems-engineering exercise in evidence-based recommendation. Not affiliated with Bundesagentur für Arbeit or Arbeitnow.