@gaonjs/cli 0.4.0 → 0.10.0

package/dist/mcp/server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @gaonjs/cli · MCP 서버 배선 — v0.15 §13.5 M10 · 질문 8.
+ *
+ * `gaon mcp` 가 이 함수를 stdio 트랜스포트로 부트업한다. Node.js MCP SDK
+ * (@modelcontextprotocol/sdk) 의 Server + StdioServerTransport 를 사용해
+ * JSON-RPC 2.0 over stdio 로 4 도구를 노출한다(§9 실 프로토콜).
+ *
+ * 도구 목록/호출은 tools.ts 의 TOOLS 카탈로그를 그대로 소비 — 카탈로그가
+ * 단일 진실 원천(SSOT). 여기서 도구를 추가하지 않는다.
+ *
+ * transport:
+ *   - stdio (기본 · MCP 표준)
+ *   - http 는 v1 범위 외(§13.5 M10 명시 X · 필요 시 후속 마일스톤에서 추가)
+ *
+ * 종료: transport 가 닫히면(SIGINT / stdin 종료) close() 로 정리한다.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/** 서버 이름·버전 — MCP initialize 응답의 serverInfo. */
+export declare const SERVER_NAME = "gaon";
+/**
+ * 서버 버전 — CLI 가 주입한다(호출자가 넘긴 값 · 미주입 시 'dev').
+ * 실제 값은 packages/cli/package.json 의 version(파사드 gaonjs 로 재수출됨).
+ */
+export type McpServerVersion = string;
+export interface McpServerOptions {
+    /** 프로젝트 루트 — 각 도구가 이 cwd 기준으로 관례를 해석. */
+    readonly cwd: string;
+    /** 서버 버전 — 미주입 시 'dev'. */
+    readonly version?: McpServerVersion;
+}
+/** 서버 핸들 — 종료 대기·강제 종료용. */
+export interface McpServerHandle {
+    /** transport 가 종료될 때까지 대기. stdin close / SIGINT 시 resolve. */
+    wait(): Promise<void>;
+    /** 강제 종료 — server + transport 정리. */
+    close(): Promise<void>;
+}
+/**
+ * MCP 서버 인스턴스 만들기 + tool handlers 등록.
+ * transport 연결은 startMcpServer 에서 한다(테스트 격리를 위해 분리).
+ */
+export declare function createMcpServer(opts: McpServerOptions): Server;
+/**
+ * `gaon mcp` 본체 — stdio transport 로 서버를 부트업하고 stdin close 를 기다린다.
+ * 반환 핸들의 wait() 는 transport 가 종료될 때 resolve.
+ *
+ * 테스트에서는 stdio 를 파이프로 감싼 자식 프로세스로 실행하고, 이 함수는
+ * 자식 프로세스 내부에서 호출된다(§9 실 프로토콜 왕복).
+ */
+export declare function startMcpServer(opts: McpServerOptions): Promise<McpServerHandle>;

package/dist/mcp/server.js

@@ -0,0 +1,102 @@
+/**
+ * @gaonjs/cli · MCP 서버 배선 — v0.15 §13.5 M10 · 질문 8.
+ *
+ * `gaon mcp` 가 이 함수를 stdio 트랜스포트로 부트업한다. Node.js MCP SDK
+ * (@modelcontextprotocol/sdk) 의 Server + StdioServerTransport 를 사용해
+ * JSON-RPC 2.0 over stdio 로 4 도구를 노출한다(§9 실 프로토콜).
+ *
+ * 도구 목록/호출은 tools.ts 의 TOOLS 카탈로그를 그대로 소비 — 카탈로그가
+ * 단일 진실 원천(SSOT). 여기서 도구를 추가하지 않는다.
+ *
+ * transport:
+ *   - stdio (기본 · MCP 표준)
+ *   - http 는 v1 범위 외(§13.5 M10 명시 X · 필요 시 후속 마일스톤에서 추가)
+ *
+ * 종료: transport 가 닫히면(SIGINT / stdin 종료) close() 로 정리한다.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { TOOLS, findTool } from './tools.js';
+/** 서버 이름·버전 — MCP initialize 응답의 serverInfo. */
+export const SERVER_NAME = 'gaon';
+/**
+ * MCP 서버 인스턴스 만들기 + tool handlers 등록.
+ * transport 연결은 startMcpServer 에서 한다(테스트 격리를 위해 분리).
+ */
+export function createMcpServer(opts) {
+    const version = opts.version ?? 'dev';
+    const server = new Server({ name: SERVER_NAME, version }, { capabilities: { tools: {} } });
+    // tools/list — TOOLS 카탈로그를 그대로 노출.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: TOOLS.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        };
+    });
+    // tools/call — 이름으로 도구를 찾아 실행. 결과를 MCP 스키마로 감싼다.
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        const tool = findTool(name);
+        if (!tool) {
+            const known = TOOLS.map((t) => t.name).join(', ');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `[gaon mcp] 알 수 없는 도구: '${name}'\n  사용 가능: ${known}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const result = await tool.run((args ?? {}), opts.cwd);
+        return {
+            content: [{ type: 'text', text: result.text }],
+            structuredContent: result.data,
+            isError: result.isError,
+        };
+    });
+    return server;
+}
+/**
+ * `gaon mcp` 본체 — stdio transport 로 서버를 부트업하고 stdin close 를 기다린다.
+ * 반환 핸들의 wait() 는 transport 가 종료될 때 resolve.
+ *
+ * 테스트에서는 stdio 를 파이프로 감싼 자식 프로세스로 실행하고, 이 함수는
+ * 자식 프로세스 내부에서 호출된다(§9 실 프로토콜 왕복).
+ */
+export async function startMcpServer(opts) {
+    const server = createMcpServer(opts);
+    const transport = new StdioServerTransport();
+    // transport 가 닫힐 때(=stdin EOF · 상대편이 pipe 닫음)를 감지하기 위한 gate.
+    let resolveClosed = () => { };
+    const closed = new Promise((r) => {
+        resolveClosed = r;
+    });
+    // MCP SDK 의 Server 는 close() 로 transport 도 함께 닫는다.
+    // onclose 는 transport 레벨에서 발생 — Server 의 onclose 핸들러가 이를 위임한다.
+    server.onclose = () => {
+        resolveClosed();
+    };
+    await server.connect(transport);
+    // StdioServerTransport 는 stdin 'end' 를 감지하지 않고 'data' 만 청취한다.
+    // 클라이언트가 파이프를 닫으면(=stdin EOF) 자동 종료가 되지 않아 서버가
+    // 무한 대기한다. 그래서 여기서 stdin.on('end') 를 잡아 명시적으로 close.
+    // (SDK 자체 이슈 회피 — MCP 프로토콜상 stdin close = 세션 종료 관례.)
+    const stdin = process.stdin;
+    const onStdinEnd = () => {
+        void server.close();
+    };
+    stdin.on('end', onStdinEnd);
+    return {
+        wait: () => closed,
+        close: async () => {
+            stdin.off('end', onStdinEnd);
+            await server.close();
+        },
+    };
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,109 @@
+/**
+ * MCP 도구의 실행 결과. text 는 사람 UI(Claude Desktop 에 그대로 표시),
+ * data 는 에이전트가 파싱하기 좋은 구조화 형태. isError 는 도구 실행 자체가
+ * 실패했음을 알린다(에러도 도구 응답으로 낸다 — MCP 관례).
+ */
+export interface ToolResult {
+    readonly text: string;
+    readonly data: unknown;
+    readonly isError: boolean;
+}
+/** 도구가 받는 인자 — 각 도구가 구체 타입으로 사용. */
+export type ToolArgs = Record<string, unknown>;
+/**
+ * `list_routes` — 프로젝트의 모든 앱과 라우트를 나열한다.
+ *
+ * 관례(§3.3): apps/<name>/routes.ts 의 default export 가 routes(...) 결과
+ * (RouteDef · entries[]). @gaonjs/config resolveApps 가 발견·로드한다.
+ *
+ * 인자:
+ *   { app?: string }   — 지정 시 그 앱만. 없으면 전 앱.
+ *
+ * 반환:
+ *   data.apps: [{ name, routeCount, routes: [{ method, path, controller, action }] }]
+ */
+export declare function listRoutesTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `get_schema` — domain/schema/ 의 테이블 정의를 조회한다.
+ *
+ * 관례(§4.1): domain/schema/*.ts 의 export 로 table(...) 결과가 놓인다.
+ * @gaonjs/data scanSchemaDir 로 모듈을 로드하고, TableDef 만 추려 컬럼 메타를
+ * 함께 낸다. 커넥션 키(§4.5) · 복합 제약(§4.2) 도 포함.
+ *
+ * 인자:
+ *   { table?: string, db?: string }
+ *      table — 지정 시 그 테이블만
+ *      db    — 지정 시 그 커넥션 것만 (기본: 전 커넥션)
+ *
+ * 반환:
+ *   data.tables: [{ name, db, columns: [...], constraints: { unique, index, check } }]
+ */
+export declare function getSchemaTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `run_migration` — 스키마 diff 를 계산해 DB 에 적용한다.
+ *
+ * 실제 로직은 `../db/migrate.ts` (M9-D · gaon db migrate) 를 그대로 재사용.
+ * 실 DB 필요(§9) — 목업 없이 진짜 커넥션에 실행한다.
+ *
+ * 인자:
+ *   { db?: string, dryRun?: boolean }
+ *      db     — 커넥션 키(§4.5). 기본 'main'.
+ *      dryRun — true 면 SQL 만 계산·출력, DB 미변경.
+ *
+ * 반환: runDbMigrate 의 결과 그대로(text + json).
+ */
+export declare function runMigrationTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ *
+ * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
+ * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ *
+ * 인자:
+ *   { scope?: 'unit'|'integration'|'all', filter?: string }
+ *      scope  — 기본 'all'
+ *      filter — vitest 위치 인자(파일 패턴 substring)
+ *
+ * 반환:
+ *   data: { exitCode, scope, filter, output }
+ *   text: vitest 자체 출력(사람 UI 그대로)
+ */
+export declare function runTestsTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `read_agent_doc` — 관례 문서 2층 구조(결정 40)의 카테고리 문서를 조회한다.
+ *
+ * 루트 AGENTS.md(코어) 색인은 "해당 영역 작업 전에 agents/<카테고리>.md 를
+ * 읽어라" 고 지시한다. 파일시스템 접근이 제한된 MCP 클라이언트도 이 지시를
+ * 이행할 수 있도록 문서 조회를 구조화 도구로 노출한다 — grep 대체 원칙
+ * (§7.5.3) 의 문서판.
+ *
+ * 인자:
+ *   { category?: string }  — data·web·frontend·async·realtime·testing·security.
+ *                            생략 시 사용 가능한 카테고리 목록을 반환.
+ */
+export declare function readAgentDocTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/** MCP 도구 스펙 — MCP 클라이언트에게 노출할 이름·설명·입력 스키마. */
+export interface McpToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly run: (args: ToolArgs, cwd: string) => Promise<ToolResult>;
+}
+/**
+ * 정본 §12 질문 8 확정 명세 4종을 카탈로그로 제공한다. 순서 = 원문 순서
+ * (라우트 · 스키마 · 마이그레이션 · 테스트).
+ */
+export declare const TOOLS: readonly McpToolSpec[];
+/**
+ * 이름으로 도구를 찾는다. 없으면 undefined.
+ */
+export declare function findTool(name: string): McpToolSpec | undefined;
+/**
+ * 앱 관례 검사(진단용) — apps/ 존재만 확인. 도구 실행 전에 조기 종료를 하지 않고,
+ * 각 도구가 자체 관례 검사를 하도록 한다(에러 = 수리 안내 · §7.5.3).
+ * 이 함수는 외부에서 문서 생성용으로만 쓴다(현재 unused 지만 진단 훅 자리).
+ */
+export declare function projectSummary(cwd: string): {
+    hasApps: boolean;
+    hasSchema: boolean;
+};