portmap

Tu agente tiene localhost:3000 hardcodeado. Esto es un mapa de lo que realmente se ejecuta.

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

Determinista · Sin LLM · Sin red · Solo lectura

¿Qué es esto?

portmap es una herramienta de línea de comandos y un servidor MCP que responde a una pregunta:

Antes de que tu agente ejecute curl localhost:3000, ¿hay algo escuchando de verdad ahí?

Fusiona tres capas de la realidad del desarrollo local en un único mapa:

1. Declarado — puertos en vite.config, scripts de package.json, URLs de .env, docker-compose

2. Real — lo que tu sistema operativo dice que está escuchando ahora mismo (Windows, macOS, Linux)

3. Conectado — cómo las variables de entorno (VITE_API_URL, API_URL, …) conectan servicios entre sí

Salida: .portmap.json + hallazgos accionables (PRT-01 … PRT-07) que los agentes y la CI pueden consumir sin adivinar.

¿Para quién es?

• Desarrolladores cansados del «liberar el puerto 3000» y de la deriva de puertos del «en mi máquina funciona»

• Equipos que usan agentes de codificación con IA (Cursor, Claude Code, Copilot) y que hardcodean URLs incorrectas de localhost

• Monorepos donde el frontend y la API viven en carpetas hermanas y las referencias de entorno cruzan repositorios

• Cualquier persona que quiera una comprobación rápida, de cinco segundos, antes de depurar la conectividad de una API

Lo que no es

Si necesitas terminar un proceso, usa las herramientas de tu sistema operativo. portmap te dice a qué puerto apuntar antes de que pierdas veinte minutos.

Related MCP server: devenv-doctor-mcp

El problema

Toda sesión de desarrollo asistida por IA acaba topándose con esto:

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

Por qué ocurre:

• Next.js usa :3000 por defecto — los agentes se lo memorizan

• Vite usa :5173 por defecto — otra pila, otro puerto

• Docker redirige 8080:3000 — la app escucha dentro del contenedor, no en el host que tú crees

• .env.local apunta a un puerto que no ha arrancado hoy nadie

• Pierdes veinte minutos con CORS, autenticación y «error de red» cuando el fallo real es PRT-04

portmap saca a relucir el desajuste en segundos — lo declarado frente a lo que escucha y las variables de entorno — para que arregles la URL, no el síntoma.

Cómo funciona

Dos escáneres, un paso de conciliación, cero pasos de 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

Reglas completas: docs/FINDINGS.md · Antes/después de las correcciones: docs/EXAMPLES.md · Especificación JSON: docs/SCHEMA.md

Pruébalo en 30 segundos

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

Cómo se ve demo:mismatch

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 …

Esa es toda la sesión de depuración que un agente se salta cuando lee .portmap.json antes.

Instalación y uso

Opción A — Clonar (funciona hoy)

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

Opción B — npm (cuando se publique)

npx portmap scan .

Flujo de trabajo habitual

1. Ejecuta portmap scan . (o portmap declare . si aún no está corriendo nada)

2. Lee las references[] para las URLs correctas de localhost — nunca des :3000 por obvio

3. Corrige PRT-04 (URL de entorno rota) antes de depurar la conectividad de una API

4. Escribe .portmap.json para futuras sesiones de agente: portmap scan . --write

5. Opcional: convierte CI en una puerta con --min-findings 1 --min-severity error

Comandos

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

Hallazgos de un vistazo

Catálogo completo con correcciones: docs/FINDINGS.md

MCP para agentes (solo lectura)

Añádelo a .cursor/mcp.json o a la configuración de Claude Code:

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

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

.portmap.json — el artefacto que leen los agentes

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

Especificación: docs/SCHEMA.md

Pipeline de preparación de agentes

Parte del paladini agent toolkit — tres comprobaciones deterministas, cero 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?

Limitaciones (con honestidad)

• La atribución PID → repositorio es heurística; las coincidencias de baja confianza se marcan, no se ocultan

• Redes WSL / Docker — los listeners dentro de contenedores pueden no aparecer como se espera en el host

• Los solo-runtime (hardcodeados en JS con sin config) no se declararán; PRT-02 puede emitir un aviso

• YAML compose — v2 se enfoca, v1 parsea patrones comunes de ports:; las features exóticas de compose se omiten

• Preferimos falsos negativos a falsos positivos ruidosos — si hay duda, portmap se queda en silencio

Contribuciones y contribuciones

Issues, informes de falsos positivosser bienvenidos.

Consulta CONTRIBUTING.md · ROADMAP.md · CODE_OF_CONDUCT.md

Problemas de seguridad: SECURITY.md — no los notifiques en público, por favor.

Desarrollo

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

Guía para agentes y colaboradores: AGENTS.md

Licencia

MIT © 2026 Fernando Paladini