neosql-mcp: Instructions file for Codex

Repository Guidelines

프로젝트 맥락

이 저장소는 neosql-mcp의 TypeScript ESM 패키지다. stdio MCP 클라이언트가 npx neosql-mcp로 실행하는 로컬 MCP 중계 서버를 구현한다.

목표 아키텍처:

[mcp-client] -- stdio MCP --> [neosql-mcp Node]
  -- JSON-RPC over HTTP on UDS/Named Pipe --> [electron-main]
  -- IPC --> [electron-renderer]

중요한 경계:

• 클라이언트 ↔ Node 구간은 표준 MCP JSON-RPC over stdio를 사용한다.
• Node ↔ electron-main 구간은 neosql 자체 JSON-RPC over HTTP endpoint를 사용한다.
• upstream transport는 POSIX에서는 Unix Domain Socket, Windows에서는 Named Pipe다. 아키텍처 문서가 명시적으로 바뀌기 전까지 TCP port를 도입하지 않는다.
• Tool catalog와 MCP handler는 이 Node 패키지에 둔다. handler는 하나 이상의 upstream HTTP method를 electron-main에 위임할 수 있으며, MCP tool과 upstream method는 1:1 매핑을 보장하지 않는다.
• electron-main, renderer, embedded-server 변경은 이 저장소 범위 밖이다. 단, 작업이 neosql main app 변경을 명시적으로 포함하면 예외다.

현재 상태와 로드맵:

• Phase 0 완료: package scaffold, MCP server, ping tool, logger, build, unit test, spawn integration test.
• Phase 1 완료: endpoint resolution은 config file, environment variable, process discovery가 아니라 deterministic socket path 규칙을 사용한다.
• Phase 2: embedded-server MCP tool을 이 Node 패키지로 이관한다. 순서는 Phase 2-1 channel infrastructure + 9개 tool signature + mock UDS round-trip, Phase 2-2 contract analysis, Phase 2-3 Node handler, Phase 2-4 ContextTools real Electron pilot이다.
• Phase 3+는 Phase 2-4 pilot 결과를 확인한 뒤 범위와 우선순위를 다시 정한다.

문서 기준:

• README.md: npm/GitHub에 노출되는 end-user 문서. 공개 설정 예시와 사용자-facing 설명은 README에 둔다.
• README.ko.md: README.md의 한국어판. 사용자에게 보이는 동작, 옵션, 도구 목록, 설정 예시를 바꿀 때는 같은 변경에서 두 파일을 함께 갱신한다.
• PLAN.md: 아키텍처 결정과 phase 전략의 단일 진실의 원천.
• CHECKLIST.md: 현재 진행 상태의 단일 진실의 원천.
• docs/project-structure.md: 파일 배치 규칙의 단일 진실의 원천.
• docs/testing.md: 필수 테스트 워크플로.
• docs/mcp-client-config.md: 내부 개발자용 CLI option, profile, legacy HTTP header → stdio/npx CLI arg 매핑 참고 문서. end-user용 설정 예시는 README를 우선 갱신한다.

AGENTS.md는 AI coding agent용 repository guide다. 세부 내용이 다르면 더 구체적인 계획 문서(PLAN.md, CHECKLIST.md, docs/project-structure.md)를 우선한다.