portmap

Dein Agent hat localhost:3000 hartkodiert. Dies bildet ab, was tatsächlich läuft.

git clone https://github.com/paladini/portmap.git && cd portmap
npm ci && npm run build && node dist/cli.js scan /path/to/your-app

Deterministisch · Kein LLM · Kein Netzwerk · Nur Lesen

Was ist das?

portmap ist ein Kommandozeilen-Tool + MCP-Server, der eine einzige Frage beantwortet:

Bevor dein Agent curl localhost:3000 ausführt, lauscht dort überhaupt etwas?

Es verschmilzt drei Ebenen der lokalen Dev-Realität zu einer einzigen Karte:

1. Deklariert — Ports in vite.config, package.json-Skripten, .env-URLs, docker-compose

2. Tatsächlich — was dein Betriebssystem gerade als lauschend meldet (Windows, macOS, Linux)

3. Verbunden — wie Umgebungsvariablen (VITE_API_URL, API_URL, …) Dienste miteinander verknüpfen

Ausgabe: .portmap.json + umsetzbare Findings (PRT-01 … PRT-07), die Agents und CI ohne Raten konsumieren können.

Für wen ist das?

• Entwickler, die den „Port 3000 killen“- und „läuft bei mir“-Port-Drift satt haben

• Teams, die KI-Coding-Agenten (Cursor, Claude Code, Copilot) einsetzen, die falsche localhost-URLs hartkodieren

• Monorepos, in denen Frontend und API in Schwesterordnern liegen und Env-Referenzen Repos kreuzen

• Menschen, die einen 5-Sekunden-Plausibilitätscheck brauchen, bevor sie API-Verbindungen debuggen

Was es nicht ist

Wenn du einen Prozess beenden willst, nutze die Tools deines Betriebssystems. portmap sagt dir welchen Port du treffen solltest, bevor du zwanzig Minuten mit Debugging verschwendest.

Related MCP server: devenv-doctor-mcp

Das Problem

Jede KI-gestützte Dev-Session stößt irgendwann darauf:

Agent:  fetch('http://localhost:3000/api/users')
Reality: Vite on :5173, API on :8080, nothing on :3000

Warum passiert das:

• Next.js nutzt standardmäßig :3000 — das merken sich Agents

• Vite nutzt standardmäßig :5173 — anderer Stack, anderer Port

• Docker mappt 8080:3000 — die App lauscht im Container, nicht dort, wo du denkst

• .env.local zeigt auf einen Port, den heute niemand gestartet hat

• Du debugst CORS, Auth und den „network error“ zwanzig Minuten lang, obwohl der eigentliche Bug PRT-04 ist

portmap deckt die Abweichung in Sekunden auf — deklariert vs. lauschend vs. Env — damit du die URL fixst, nicht das Symptom.

So funktioniert es

Zwei Scanner, ein Abgleich, kein LLM:

┌─────────────────────────────────────────────────────────────┐
│  Your repo on disk                                          │
├─────────────────────────────────────────────────────────────┤
│  1. Static discovery                                        │
│     package.json scripts · vite.config · .env localhost URLs│
│     docker-compose port mappings                            │
├─────────────────────────────────────────────────────────────┤
│  2. Runtime scan (optional)                                 │
│     OS listeners → port, PID, process, command line           │
├─────────────────────────────────────────────────────────────┤
│  3. Reconcile                                               │
│     declared ↔ actual ↔ env references → service graph        │
│     → .portmap.json + findings (PRT-01 … PRT-07)            │
└─────────────────────────────────────────────────────────────┘
         ↓                    ↓                    ↓
    CLI pretty          MCP tools            CI --min-findings

Vollständige Regelliste: docs/FINDINGS.md · Vorher/Nachher-Fixes: docs/EXAMPLES.md · JSON-Spezifikation: docs/SCHEMA.md

Probier es in 30 Sekunden

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build

npm run demo:mismatch     # classic agent mistake → 3 errors
npm run demo:workspace    # frontend + API in sibling folders → resolved

So sieht demo:mismatch aus

portmap — mismatch-app
root: …/fixtures/mismatch

Services:
  [down] vite — Vite dev server
    declared :5173 (vite.config.ts:server.port)
    not listening

Env references:
  NEXT_PUBLIC_API_URL=http://localhost:3000 → :3000 [unresolved]
  VITE_API_URL=http://localhost:8080 → :8080 [unresolved]

Findings: 3 error(s), 0 warning(s)
  ✖ PRT-01 Declared port 5173 is not listening …
  ✖ PRT-04 NEXT_PUBLIC_API_URL points to localhost:3000 but nothing is listening …
  ✖ PRT-04 VITE_API_URL points to localhost:8080 but nothing is listening …

Das ist die gesamte Debug-Session, die sich ein Agent spart, wenn er zuerst .portmap.json liest.

Installation & Ausführung

Option A — Klonen (funktioniert heute)

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build
node dist/cli.js scan /path/to/your-app

Option B — npm (sobald veröffentlicht)

npx portmap scan .

Typischer Ablauf

1. Führe aus portmap scan . (oder declare ., wenn noch nichts läuft)

2. Lies references[] für die korrekten localhost-URLs — nimm niemals :3000 an

3. Behebe PRT-04 (defekte Env-URL), bevor du API-Verbindungen debugst

4. Schreibe .portmap.json für zukünftige Agent-Sessions: portmap scan . --write

5. Optional: CI mit --min-findings 1 --min-severity error absichern

Befehle

Flags: --json · --markdown · --write (speichert .portmap.json) · --out <file> · --min-findings N · --quiet

Findings auf einen Blick

Vollständiger Katalog mit Fixes: docs/FINDINGS.md

MCP für Agents (nur Lesen)

Füge es zu .cursor/mcp.json oder der Claude-Code-Konfiguration hinzu:

{
  "mcpServers": {
    "portmap": {
      "command": "node",
      "args": ["/path/to/portmap/dist/cli.js", "mcp"]
    }
  }
}

Skill für Cursor/Claude: .cursor/skills/portmap/SKILL.md

.portmap.json — das Artefakt, das Agents lesen

portmap scan . --write
git add .portmap.json   # optional: commit for stable agent context

Spezifikation: docs/SCHEMA.md

Pipeline für die Agent-Bereitschaft

Teil der present — drei deterministische Checks, kein LLM:

harness-score  →  Is the repo harness ready for agents?
portmap        →  Do ports and env URLs align locally?
unhappypath    →  Is the UI ready for real users?

Einschränkungen (ehrlich)

• Die PID → Repo-Zuordnung ist heuristisch; Treffer mit niedriger Konfidenz werden markiert, nicht versteckt

• WSL / Docker-Netzwerk — Listener in Containern erscheinen evtl. nicht wie erwartet auf dem Host

• Reine Laufzeit-Ports (ohne Konfig in JS hartkodiert) werden nicht deklariert — PRT-02 kann warnen

• YAML-Compose — v1 parst gängige ports:-Muster; exotische Compose-Features werden ausgelassen

• Falsch-Negative werden lauten Falsch-Positiven vorgezogen — bei Unsicherheit bleibt portmap ruhig

Beitragen

Issues, Falsch-Positive-Meldungen und Parser-Beiträge sind willkommen.

Siehe CONTRIBUTING.md · ROADMAP.md · CODE_OF_CONDUCT.md

Sicherheitsprobleme: SECURITY.md — bitte nicht öffentlich melden.

Entwicklung

npm ci
npm run build
npm test
npm run demo:mismatch
npm run demo:workspace

Agent-/Contributor-Guide: AGENTS.md

Lizenz

MIT © 2026 Fernando Paladini