Skip to main content
Glama
deenesjakoruzh
paladini

portmap

by paladini
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

portmap

에이전트가 localhost:3000을 하드코딩했습니다. 이 도구는 실제로 실행 중인 것을 매핑합니다.

License: MIT CI

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

결정적 · LLM 없음 · 네트워크 불필요 · 읽기 전용

이건 뭔가요?

portmap은 한 가지 질문에 답하는 커맨드라인 도구 + MCP 서버입니다:

에이전트가 curl localhost:3000을 실행하기 전에, 실제로 그 포트에서 대기 중인 것이 있나요?

로컬 개발 현실의 세 가지 계층을 하나의 지도로 결합합니다:

  1. 선언(Declared) — vite.config, package.json 스크립트, .env URL, docker-compose의 포트

  2. 실제(Actual) — OS가 지금 실제로 수신 중이라고 알려주는 포트 (Windows, macOS, Linux)

  3. 연결(Connected) — 환경 변수(VITE_API_URL, API_URL, …)가 서비스를 서로 연결하는 방식

출력: .portmap.json + 에이전트와 CI가 추측 없이 바로 쓸 수 있는 실행 가능한 탐지 결과(PRT-01 … PRT-07)

누구를 위한 도구인가요?

  • **"포트 3000 죽이기"**와 "내 컴퓨터에서는 되는데" 같은 포트 드리프트에 지친 개발자

  • 잘못된 localhost URL을 하드코딩하는 AI 코딩 에이전트(Cursor, Claude Code, Copilot)를 사용하는 팀

  • 프런트엔드와 API가 형제 폴더에 있고 env 참조가 `레포지터리를 넘나드는 모노레포

  • API 연결 문제를 디버깅하기 전에 **5초짜리 안전 확인(sanity check)**을 원하는 모든 사람

무엇이 아닌가

기대

현실

개발 서버를 시작/중지함

아니요 — 수명 주기는 Switchboard 또는 PortPilot을 사용하세요

직접 유지하는 수동 포트 레지스트리

아니요 — portmap은 설정 파일 + OS에서 탐색합니다

프로덕션 모니터링 / 가동 시간

아니요 — 로컬 개발 토폴로지만 다룹니다

LLM으로 포트를 추론함

아니요 — 100% 결정적(deterministic) 파일 시스템 + 소켓 테이블입니다

프로세스를 종료해야 한다면 OS 도구를 사용하세요. portmap은 20분을 낭비하기 전에 어느 포트로 접속하해야 할지 알려줍니다.

Related MCP server: devenv-doctor-mcp

문제

모든 AI 보조 개발 세션은 결국 이런 상황에 부딪힙니다:

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

왜 그럴까요?

  • Next.js는 기본적으로 :3000을 사용합니다 — 에이전트는 그것을 외워버립니다

  • Vite는 기본적으로 :5173을 사용합니다 — 스택이 다르면 포트도 다릅니다

  • Docker는 8080:3000을 리매핑합니다 — 앱은 컨테이너 안에서 대기하지, 생각한 곳이 아닙니다

  • **.env.local**이 오늘 아무도 시작하지 않은 포트를 가리킵니다

  • 실제 버그가 PRT-04인데도 CORS, 인증, "network error"를 20분 동안 디버깅합니다

portmap은 선언된 포트 vs 실제 수신 포트 vs env 연결을 몇 초 드러내서, 증상이 아닌 URL을 고치게 해줍니다.

동작 방식

스캐너 두 개, 조정 단계 하나, 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

전체 규칙 목록: docs/FINDINGS.md · 수정 전/후 예시: docs/EXAMPLES.md · JSON 스펙: docs/SCHEMA.md

30초 만에 체험해 보기

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

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 …

그것이 바로 에이전트가 .portmap.json을 먼저 읽으면 건너뛰는 디버깅 세션 전체입니다.

설치 및 실행

옵션 A — 클론(지금 바로 사용 가능)

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

옵션 B — npm(게시 후)

npx portmap scan .

일반적인 워크플로우

  1. 실행 portmap scan . (아직 실행 중인 것이 없으면 declare .)

  2. 읽기 올바른 localhost URL을 위해 references[]를 확인 — 절대 :3000이라고 가정하지 마세요

  3. 수정 API 연결을 디버깅하기 전에 PRT-04(잘못된 env URL)를 고치세요

  4. 저장 향후 에이전트 세션을 위해 .portmap.json 생성: portmap scan . --write

  5. 선택: --min-findings 1 --min-severity error로 CI에 게이트 적용

명령어

명령

기능

portmap scan [path]

전체 스캔: 정적 설정 + OS 리스너

portmap declare [path]

정적 스캔만 — 실행 중인 프로세스 불필요

portmap listen

OS 리스너 목록 보기(디버그)

portmap workspace [dir]

멀티 레포: 폴더 간 env 참조 해결

portmap mcp

읽기 전용 MCP stdio 서버 시작

플래그: --json · --markdown · --write (.portmap.json 저장) · --out <file> · --min-findings N · --quiet

탐지 결과 한눈에 보기

ID

규칙

심각도

PRT-01

선언된 포트가 수신 중이 아닌 경우

error

PRT-02

선언된 설정 없이 수신 중인 리스너

warning

PRT-03

두 서비스가 같은 포트를 선언함

error

PRT-04

env URL이 리스너 없는 포트를 가리킴

error

PRT-05

리스너가 선언된 포트와 다른 포트에 있음

warning

PRT-06

Docker 호스트:컨테이너 포트 불일치

warning

PRT-07

워크스페이스 간 env 참조가 해결 안 됨

error

해결 방법 포함 전체 목록: docs/FINDINGS.md

에이전트용 MCP (읽기 전용)

.cursor/mcp.json 또는 Claude Code 설정에 추가:

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

도구

사용 시점

portmap_scan

전체 .portmap.json 보고서

portmap_graph

간단한 { services, edges, references }

portmap_resolve_url

"VITE_API_URL에는 어떤 URL을 써야 하나요?"

portmap_findings

심각도로 필터링된 PRT-* 이슈 목록

Cursor/Claude용 스킬: .cursor/skills/portmap/SKILL.md

.portmap.json — 에이전트가 읽는 결과물

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

스펙: docs/SCHEMA.md

에이전트 대비 파이프라인

paladini agent toolkit의 일부 — 결정적 검사 세 가지, 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?

도구

질문

harness-score

AGENTS.md, 규칙, hooks, CI 성숙도

portmap

선언된 포트, 리스너, env 그래프

unhappypath

로딩, 빈 상태, 오류, 재시도 UI 상태

한계 (정직하게)

  • **PID → 레포 소속 판정(attribution)**은 휴리스틱입니다. 신뢰도가 낮은 매칭은 숨기지 않고 플래그로 표시합니다.

  • WSL / Docker 네트워킹 — 컨테이너 내부의 리스너가 호스트에 예상대로 보이지 않을 수 있습니다.

  • 런타임 전용 포트 (구성 없이 JS에 하드코딩된 것)는 선언되지 않습니다 — PRT-02 경고가 발생할 수 있습니다.

  • YAML compose — v1은 일반적인 ports: 패턴을 파싱하지만, 흔하지 않은 compose 기능은 건너뜁니다.

  • 시끄러운 **오탐(false positive)**보다 **미탐(false negative)**을 선호합니다 — 확실하지 않으면 portmap은 조용히 넘어갑니다.

기여

이슈, 오탐 보고, 파서 기여를 모두 환영합니다.

채널

링크

버그 신고

이슈 열기

오탐 신고

PRT-* 오탐 보고

기능 요청

파서 / 규칙 요청

질문 및 아이디어

토론

CONTRIBUTING.md · ROADMAP.md · CODE_OF_CONDUCT.md 를 참고하세요.

보안 이슈: SECURITY.md — 공개적으로 등록하지 마세요.

개발

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

에이전트/기여자 가이드: AGENTS.md

라이선스

MIT © 2026 Fernando Paladini

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Harbor MCP Server

    luke-fairbanks
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to discover, configure, and manage local development servers. Provides tools for app registration, port allocation, lifecycle control, and log access without manual config editing.
    338
    MIT

  • devenv-doctor-mcp

    Madiocre
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables LLM clients to inspect local dev environments—Docker container health, pnpm workspace integrity, and stuck process detection—without manual terminal copy-pasting.
    MIT

  • tidyports

    dan-fetch-studio
    A
    license
    Not graded
    quality
    B
    maintenance
    See and control the local dev servers your coding agents leave running. Lists listeners with provenance — which agent, terminal and git worktree started each — kills strays, and allocates collision-free ports so parallel agents stop fighting over :3000.
    MIT

  • wharfy

    egebilge
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server for managing local dev ports on macOS. It enables AI agents to inspect listening ports, identify owning processes and parent chains, kill processes safely, wait for ports, and report LAN exposure.
    29
    1
    MIT

View all related MCP servers

Related MCP Connectors

  • Umtri

    Give your AI agent a persistent map of your project's structure, dependencies, and bugs.

  • Synapse — GEO Growth Layer

    Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.

  • Agent Ready

    Scan any URL for AI agent readability — Vercel Spec, llmstxt.org, and agent-protocol manifests.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/paladini/portmap'

If you have feedback or need assistance with the MCP directory API, please join our Discord server