zido AGENTS.md

zido AGENTS.md

PURPOSE

Zido는 Nest CLI workspace 기반의 MCP(Model Context Protocol) server입니다. 여러 지도 API provider를 공통 interface로 감싸 장소 검색과 geocoding 기능을 제공하며, stdio와 HTTP transport를 통해 MCP client에 연결됩니다.

이 문서는 Zido의 runtime ownership, directory structure, 실행 명령어와 변경 후 verification 기준을 정의합니다. 구현 시에는 configuration, provider fallback, place domain, MCP tool registration의 경계를 유지하고, 운영자가 재현할 수 있는 명령어와 검증 절차를 우선합니다.

STRUCTURE

• apps: application entry
  • http-server : zido http server /mcp transporter
  • stdio : zido stdio server
  • cli : zido cli application
• libs : libraries
  • common : common codes like validator, config ...
  • map-providers : map data API providers
    • kakao : Kakao map
    • naver : naver map
    • google : google map
  • mcp-runtime : mcp shim module
  • place-domain : place related codes

대표 Flow : apps > (mcp-runtime) > place-domain > map-providers

STRUCTURE GUIDE

• 구조는 stale해지기 쉬우므로 변경이 생기거나 관측상 변경이 있는 경우 STRUCTURE 섹션을 갱신해야합니다.
• common library는 config.ts를 configuration의 단일 source of truth로 사용하며 Nest ConfigurationService와 ConfigurationModule을 두지 않습니다.

RULES

• 작업 중 기록된 규칙에 벗어난 pattern을 발견하면, 동일한 pattern이 적용된 범위를 sweep하여 같은 task에서 함께 refactoring해야 한다. (MUST)
• 주의 : 문제가 생겼을 때, git clean revert를 하지 말 것 (변경사항 전체 취소 등)
• tool registration, schema wiring, query-only large-action gating, hook registration을 직접 소유하는 root runtime entrypoint로 src/main.ts를 유지
• 기술 용어, 핵심 용어는 알파벳을 유지하면서 서술은 한국어로 합니다.
• 사용자가 지시한 내용은 AGENTS.md에 기록한 후 해당 규칙에 따라 작업합니다.
• 작업 중 AGENTS.md의 RULES에 기술된 규칙에서 drift 또는 stale 상태인 부분을 발견하면 함께 sweep합니다.

GUIDE

HOW TO WRITE COMMENT

• Comment는 multi-line jsdoc 스타일로 해당 함수, 또는 메소드의 이름이 기계적으로 반복되지 않는 의미 있는 주석이어야합니다.
• 작업한 부분 중 const, type, property, function, method에는 multiline jsdoc 형식의 한글 주석을 작성해야합니다.
• comment는 method 또는 const name 의 반복된 서술이여서는 안되며, 구체적인 작동 방식 및 "어떤 역할을 하는지"를 충분히 설명 할 수 있어야합니다.
• property는 각 property에 inline multiline jsdoc으로 작성합니다.