🤖 MCP — AI 에이전트 연결

Router Port Manager는 Model Context Protocol (2025-06-18) 위에서 AI 에이전트가 공유기 정보를 조회·조작할 수 있는 도구들을 노출합니다.

상태: 활성 (per-user tokens, env MCP_TOKEN)

👉 가장 빠른 길: 앱에 로그인한 뒤 상단 메뉴의 🤖 MCP 탭을 열면, 토큰 발급과 함께 클라이언트별 설정(Claude Desktop / Cursor / Cline / curl) 이 토큰까지 박힌 채로 자동 채워져 한 클릭 복사 가능합니다.
→ 앱으로 이동

토큰 발급 (권장)

로그인 한 사용자가 본인 계정으로 토큰을 발급하면, 그 토큰을 쓰는 AI 에이전트의 모든 호출이 자동으로 본인 이름으로 attribution 됩니다 — 포트포워딩을 추가하면 created_by 가 자동으로 채워져요.

웹앱에 로그인 → 우상단 설정 → MCP 토큰 섹션으로 이동
라벨(예: claude-desktop) 입력 후 "새 토큰 발급" 클릭
화면에 한 번만 보이는 원본 토큰을 AI 클라이언트 설정에 복사

참고

환경변수 MCP_TOKEN 도 여전히 동작하지만, 이건 attribution 이 안 되는 "system" 호출로 처리됩니다. 가능하면 개인 토큰을 쓰세요.

엔드포인트

POST https://rpm.k-sw.org/mcp

인증: HTTP 헤더 Authorization: Bearer <your-token>

제공 도구 (Tools)

전체 목록은 tools/list JSON-RPC 호출로 받습니다. AI 에이전트는 읽기 + 쓰기 둘 다 가능합니다 — 포트를 직접 열고 닫을 수 있어요.

읽기 도구

이름	설명
get_status	전체 카운트/통합 상태
get_overview	모든 포트포워딩 규칙을 공유기·지역 컨텍스트와 함께 평탄 리스트로
list_regions	모든 지역 목록
list_routers	공유기 목록 (region_id로 필터 가능)
get_router_details	한 공유기 상세 (비밀번호 제외)
list_port_forwards	해당 공유기의 포트포워딩 규칙 (DB 캐시)
crawl_port_forwards	장비 직접 크롤링 후 캐시 갱신
test_router_connection	도달성 + 인증 테스트 (network/auth/parse 사유 구분)
list_tags	모든 재사용 태그

쓰기 도구 (장비 + DB 변경)

이름	설명
create_port_forward_rule	장비에 새 포트 열기 (어댑터가 ipTIME/UniFi/OpenWRT 에 푸시)
delete_port_forward_rule	장비에서 포트 닫기 + DB 정리
update_rule_metadata	규칙의 description/tags/created_by 수정 (장비 미접근)
create_router / update_router / delete_router	공유기 등록·수정·삭제
create_region / update_region / delete_region	지역(라우터 그룹) 관리
create_tag / delete_tag	태그 관리

규칙 id는 (router, name) 기준으로 영속화돼서, create 직후 받은 rule_id 로 나중에 정확히 update/delete 할 수 있습니다.

create_port_forward_rule 의 컨텍스트 요구

AI 에이전트가 포트를 열 때, 운영자가 나중에 "이 포트는 무엇이지?" 라고 물어볼 수 있도록 다음 세 필드 중 최소 하나는 반드시 채워야 합니다 — 빠지면 호출이 거부됩니다.

필드	예시	의미
`code_url`	`https://github.com/team/svc`	소스 코드 위치
`deployment_url`	`https://app.example.com`	외부에서 접근하는 서비스 URL
`execution_server`	`k8s-pod-foo`, `srv-01:8080`	실제 워크로드가 도는 곳

created_by 는 토큰 주인 username 으로 자동 채워지므로 비워두면 됩니다. whoami 도구로 attribution 결과를 사전 확인할 수 있습니다.

curl 테스트

curl -X POST https://rpm.k-sw.org/mcp \
  -H 'Authorization: Bearer $MCP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

Claude Desktop 설정 (참고)

Claude Desktop의 claude_desktop_config.json 에 추가:

{
  "mcpServers": {
    "router-port-manager": {
      "url": "https://rpm.k-sw.org/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

참고

Claude Desktop은 HTTP transport를 직접 지원하지 않을 수 있습니다. 그 경우 mcp-remote 등의 어댑터로 stdio→HTTP 변환을 거쳐 연결하세요.

mcp-remote 로 stdio→HTTP 어댑팅

HTTP transport 를 못 쓰는 클라이언트(현행 Claude Desktop, Cline 등)는 npm 패키지 mcp-remote 를 통해 우회합니다. 설치는 노드만 있으면 끝:

npm i -g mcp-remote
# 또는 npx로 (다운로드 자동)
npx -y mcp-remote https://rpm.k-sw.org/mcp --header "Authorization: Bearer $MCP_TOKEN"

Claude Desktop 설정에서는 다음처럼 stdio 명령으로 감쌉니다:

{
  "mcpServers": {
    "router-port-manager": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://rpm.k-sw.org/mcp", "--header", "Authorization: Bearer "]
    }
  }
}

Cursor / Continue / Cline 연결

Cursor: ~/.cursor/mcp.json 에 위의 stdio 형식 그대로 추가하세요. 도구 호출은 채팅창에서 @router-port-manager 로 트리거됩니다.

Cline (VS Code): settings → "Add MCP Server" → "stdio" 선택 → command npx, args ["-y","mcp-remote","https://rpm.k-sw.org/mcp","--header","Authorization: Bearer <YOUR_MCP_TOKEN>"].

Continue: ~/.continue/config.json 의 mcpServers 배열에 위 stdio 항목을 추가합니다.

tip — whoami 와 permissions_self_check 를 가장 먼저 호출해 attribution / 가시 라우터를 확인한 뒤 write 도구를 사용하세요.

예시 — 한 공유기의 규칙 가져오기

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_port_forwards",
    "arguments": { "router_id": "<router-uuid>" }
  }
}