mcp-chat

docker compose up -d      # Neo4j (bolt 7687 / browser 7474)
pnpm install
pnpm start:dev            # http://localhost:3000/mcp

모델          "과거에 무신사 팝업 한 공간 알려줘"
  │
  │  tools/call  { name: "search_events",
  │                arguments: { brandName: "무신사", type: "팝업", period: "과거" } }
  ▼
POST /mcp     McpController — 요청마다 McpServer + Transport를 새로 만든다
  ▼
zod           inputSchema로 인자 검증. 타입·enum·범위가 안 맞으면 여기서 끝
  ▼
Service       EventService.searchEvents() — 필터링과 정렬. MCP를 모른다
  ▼
Formatter     결과 배열 → markdown 표
  ▼
모델          | 행사 | 브랜드 | 유형 | 기간 | 공간 | 건물 | spaceId |
              | 무신사 테라스 팝업 | 무신사 | 팝업 | 2025-05-01 ~ ... |

                     ┌─ 도메인 tool 4개 ─→ SpaceService / EventService ─→ in-memory 배열
tools/call ─→ 라우팅 ─┤
                     └─ read_cypher ─→ 검증기 ─→ Neo4jService ─→ Neo4j
                        get_schema  ─→ SchemaService ─┘

모델이 쓴 Cypher
  ▼ 주석 제거          실행 쿼리에서 지운다. 안 그러면 뒤에 붙인 LIMIT이 주석에 먹힌다
  ▼ 문자열 리터럴 마스킹  n.name = 'DELETE' 를 쓰기 구문으로 오해하지 않도록
  ▼ 레이블·프로퍼티 마스킹 (n:Set), n.merge 를 키워드로 오해하지 않도록
  ▼ statement 개수      세미콜론으로 여러 개를 이어 붙였는지
  ▼ 쓰기 구문 15종       CREATE / MERGE / DELETE / SET / DROP ...
  ▼ 프로시저 허용목록     db.labels, db.schema.* 등 읽기 전용만
  ▼ LIMIT 보장          없으면 주입, 상한을 넘으면 낮춤
실행

(:Building)-[:HAS_FLOOR]->(:Floor)-[:HAS_SPACE]->(:Space)
(:Brand)-[:HELD]->(:Event)-[:AT]->(:Space)

src/
  main.ts                  진입점 — Nest HTTP 부트스트랩
  app.module.ts            ConfigModule(전역) + McpModule

  mcp/                     MCP 프로토콜 계층
    mcp.controller.ts        POST /mcp — 요청마다 server+transport 생성 (stateless)
    mcp-server.factory.ts    McpServer 조립 + Neo4j tool 등록
    tools/
      space-tools.registrar.ts   도메인 tool 4개 등록 (description = 프롬프트)

  space/                   도메인 계층 — DB 없이 도는 부분
    space.data.ts            건물·층·공간 (in-memory)
    event.data.ts            브랜드·행사 이력 (in-memory)
    space.service.ts         공간 조회
    event.service.ts         행사 조회 (시점 필터의 기준일을 주입받는다)
    space-formatter.ts       결과 → 표 / 키:값 블록

  neo4j/                   Neo4j 접근 계층
    neo4j.service.ts         드라이버 lazy 초기화, 읽기 전용 세션
    schema.service.ts        db.schema.* 로 스키마 수집 (APOC 불필요)

  cypher/                  Cypher 취급 유틸
    cypher-validator.ts      읽기 전용 검증 + LIMIT 강제
    result-formatter.ts      Neo4j 결과 → markdown 표 (formatRows는 공용)
    schema-formatter.ts      스키마 → 압축 텍스트

scripts/probe.mjs          실행 중인 서버에 붙어 tool을 차례로 호출

pnpm test          # 67개 — 검증기, 포매터, 조회 로직
pnpm build
pnpm probe         # 서버가 떠 있을 때, tool 호출 결과를 눈으로 확인
pnpm inspector     # MCP Inspector UI (Streamable HTTP / http://localhost:3000/mcp)

claude mcp add --transport http mcp-chat http://localhost:3000/mcp