portmap

Your agent hardcoded localhost:3000. This maps what actually runs.

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

Deterministic · No LLM · No network · Read-only

What is this?

portmap is a command-line tool + MCP server that answers one question:

Before your agent runs curl localhost:3000, does anything actually listen there?

It fuses three layers of local dev reality into a single map:

1. Declared — ports in vite.config, package.json scripts, .env URLs, docker-compose

2. Actual — what your OS says is listening right now (Windows, macOS, Linux)

3. Connected — how env vars (VITE_API_URL, API_URL, …) link services together

Output: .portmap.json + actionable findings (PRT-01 … PRT-07) that agents and CI can consume without guessing.

Who is it for?

• Developers tired of "kill port 3000" and "works on my machine" port drift

• Teams using AI coding agents (Cursor, Claude Code, Copilot) that hardcode wrong localhost URLs

• Monorepos where frontend and API live in sibling folders and env refs cross repos

• Anyone who wants a 5-second sanity check before debugging API connectivity

What it is not

If you need to kill a process, use your OS tools. portmap tells you which port to hit before you waste twenty minutes.

Related MCP server: devenv-doctor-mcp

The problem

Every AI-assisted dev session hits this eventually:

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

Why it happens:

• Next.js defaults to :3000 — agents memorize that

• Vite defaults to :5173 — different stack, different port

• Docker remaps 8080:3000 — the app listens inside the container, not where you think

• .env.local points at a port nobody started today

• You debug CORS, auth, and "network error" for twenty minutes when the real bug is PRT-04

portmap surfaces the mismatch in seconds — declared vs listening vs env — so you fix the URL, not the symptom.

How it works

Two scanners, one reconcile step, zero 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

Full rule list: docs/FINDINGS.md · Before/after fixes: docs/EXAMPLES.md · JSON spec: docs/SCHEMA.md

Try it in 30 seconds

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

What demo:mismatch looks like

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 …

That's the entire debug session an agent skips when it reads .portmap.json first.

Install & run

Option A — Clone (works today)

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 (when published)

npx portmap scan .

Typical workflow

1. Run portmap scan . (or declare . if nothing is running yet)

2. Read references[] for correct localhost URLs — never assume :3000

3. Fix PRT-04 (broken env URL) before debugging API connectivity

4. Write .portmap.json for future agent sessions: portmap scan . --write

5. Optional: gate CI with --min-findings 1 --min-severity error

Commands

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

Findings at a glance

Full catalog with fixes: docs/FINDINGS.md

MCP for agents (read-only)

Add to .cursor/mcp.json or Claude Code config:

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

Skill for Cursor/Claude: .cursor/skills/portmap/SKILL.md

.portmap.json — the artifact agents read

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

Spec: docs/SCHEMA.md

Agent-readiness pipeline

Part of the paladini agent toolkit — three deterministic checks, zero 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?

Limitations (honest)

• PID → repo attribution is heuristic; low-confidence matches are flagged, not hidden

• WSL / Docker networking — listeners inside containers may not appear as expected on the host

• Runtime-only ports (hardcoded in JS with no config) won't be declared — PRT-02 may warn

• YAML compose — v1 parses common ports: patterns; exotic compose features are skipped

• Prefer false negatives over noisy false positives — if unsure, portmap stays quiet

Contributing

Issues, false-positive reports, and parser contributions welcome.

See CONTRIBUTING.md · ROADMAP.md · CODE_OF_CONDUCT.md

Security issues: SECURITY.md — please do not file publicly.

Development

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

Agent/contributor guide: AGENTS.md

License

MIT © 2026 Fernando Paladini