gencow 0.1.4 → 0.1.5

package/bin/gencow-mcp.mjs

@@ -6,14 +6,12 @@
  * MCP (Model Context Protocol) 서버를 stdio 전송으로 제공합니다.
  *
  * Resources:
- *   - gencow://openapi-spec   → OpenAPI 3.0 JSON
- *   - gencow://api-list       → 등록된 API 경로 목록
+ *   - gencow://api-list       → 등록된 API 목록
  *
  * Tools:
  *   - list_apis        → 등록된 query/mutation 목록
- *   - call_query       → query 호출
- *   - call_mutation    → mutation 호출
- *   - get_openapi_spec → OpenAPI 스펙 조회
+ *   - call_query       → query 호출 (POST /api/query)
+ *   - call_mutation    → mutation 호출 (POST /api/mutation)
  *
  * Usage:
  *   gencow mcp                              (기본 포트 5456)
@@ -67,12 +65,12 @@ const server = new Server(
 const TOOLS = [
     {
         name: "list_apis",
-        description: "등록된 전체 API 목록을 조회합니다. 각 API의 이름, 경로, 타입(query/mutation), 지원 HTTP 메서드를 반환합니다.",
+        description: "등록된 전체 API 목록을 조회합니다. 각 API의 이름과 타입(query/mutation)을 반환합니다.",
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "call_query",
-        description: "Gencow query를 호출합니다. 예: name='tasks.list', args={}. 경로: POST /api/fn/{module}/{name}",
+        description: "Gencow query를 호출합니다. 예: name='tasks.list', args={}. RPC 방식: POST /api/query",
         inputSchema: {
             type: "object",
             required: ["name"],
@@ -84,7 +82,7 @@ const TOOLS = [
     },
     {
         name: "call_mutation",
-        description: "Gencow mutation을 호출합니다. 예: name='tasks.create', args={ title: '새 태스크' }. 경로: POST /api/fn/{module}/{name}",
+        description: "Gencow mutation을 호출합니다. 예: name='tasks.create', args={ title: '새 태스크' }. RPC 방식: POST /api/mutation",
         inputSchema: {
             type: "object",
             required: ["name"],
@@ -94,11 +92,6 @@ const TOOLS = [
             },
         },
     },
-    {
-        name: "get_openapi_spec",
-        description: "OpenAPI 3.0 스펙을 JSON으로 반환합니다. API 구조, 요청/응답 스키마, 인증 방법을 포함합니다.",
-        inputSchema: { type: "object", properties: {} },
-    },
 ];
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
@@ -109,23 +102,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (toolName) {
             case "list_apis": {
-                const list = await fetchJSON("/api/fn");
-                return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
+                // Use the health endpoint which returns queries list
+                const info = await fetchJSON("/");
+                return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
             }
             case "call_query": {
-                const path = "/api/fn/" + toolArgs.name.replace(/\./g, "/");
-                const result = await postJSON(path, toolArgs.args || {});
+                const result = await postJSON("/api/query", { name: toolArgs.name, args: toolArgs.args || {} });
                 return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
             }
             case "call_mutation": {
-                const path = "/api/fn/" + toolArgs.name.replace(/\./g, "/");
-                const result = await postJSON(path, toolArgs.args || {});
+                const result = await postJSON("/api/mutation", { name: toolArgs.name, args: toolArgs.args || {} });
                 return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
             }
-            case "get_openapi_spec": {
-                const spec = await fetchJSON("/api/openapi.json");
-                return { content: [{ type: "text", text: JSON.stringify(spec, null, 2) }] };
-            }
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${toolName}` }], isError: true };
         }
@@ -137,16 +125,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // ── Resources ───────────────────────────────────────────
 
 const RESOURCES = [
-    {
-        uri: "gencow://openapi-spec",
-        name: "openapi-spec",
-        description: "Gencow OpenAPI 3.0 specification (auto-generated from registered queries/mutations)",
-        mimeType: "application/json",
-    },
     {
         uri: "gencow://api-list",
         name: "api-list",
-        description: "List of all registered API endpoints with paths and methods",
+        description: "List of all registered API queries and server information",
         mimeType: "application/json",
     },
 ];
@@ -157,13 +139,9 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const { uri } = request.params;
 
     switch (uri) {
-        case "gencow://openapi-spec": {
-            const spec = await fetchJSON("/api/openapi.json");
-            return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(spec, null, 2) }] };
-        }
         case "gencow://api-list": {
-            const list = await fetchJSON("/api/fn");
-            return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(list, null, 2) }] };
+            const info = await fetchJSON("/");
+            return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(info, null, 2) }] };
         }
         default:
             throw new Error(`Unknown resource: ${uri}`);

package/bin/gencow.mjs

@@ -362,56 +362,37 @@ function generateReadmeMd(config, apiObj) {
         md += `\n`;
     }
 
-    // ── 1-1. REST API Direct Call ────────────────────────────
-    md += `---\n\n## 🌐 REST API 직접 호출\n\n`;
-    md += `> 📡 아래 REST 경로로 API를 호출하세요.\n`;
-    md += `> 모든 요청에 \`credentials: "include"\` (쿠키)를 포함해야 합니다.\n\n`;
-
-    md += `### Query (읽기 — GET 또는 POST)\n\n`;
-    md += `| 경로 | 메서드 | 설명 |\n`;
-    md += `| :--- | :--- | :--- |\n`;
+    // ── 1-1. React 사용법 (Primary — 최상단 배치) ────────────
+    md += `---\n\n## ⚡ 데이터 사용법 (필수 — 반드시 이 방식을 사용하세요)\n\n`;
+    md += `> ⚠️ **\`useQuery\` / \`useMutation\` Hook을 반드시 사용하세요.**\n`;
+    md += `> Gencow는 WebSocket 실시간 동기화를 내장하고 있어, Hook을 사용하면 데이터가 **자동으로 동기화**됩니다.\n`;
+    md += `> \`fetch()\`를 직접 호출하거나 \`apiPost()\` 같은 래퍼를 만들지 마세요.\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `import { api } from "@/gencow/api";  // 자동 생성됨\n`;
+    md += `import { useQuery, useMutation } from "@gencow/react";\n\n`;
     for (const [ns, fns] of Object.entries(apiObj)) {
-        for (const q of fns.queries) {
-            md += `| \`/api/fn/${ns}/${q}\` | GET, POST | ${ns}.${q} |\n`;
+        if (fns.queries.length > 0) {
+            md += `// ${ns} 데이터 조회 (실시간 자동 갱신)\n`;
+            md += `const ${ns} = useQuery(api.${ns}.${fns.queries[0]});  // ${ns.charAt(0).toUpperCase() + ns.slice(1)}[] | undefined\n`;
         }
-    }
-
-    md += `\n### Mutation (쓰기 — POST만)\n\n`;
-    md += `| 경로 | 메서드 | 설명 |\n`;
-    md += `| :--- | :--- | :--- |\n`;
-    for (const [ns, fns] of Object.entries(apiObj)) {
-        for (const m of fns.mutations) {
-            md += `| \`/api/fn/${ns}/${m}\` | POST | ${ns}.${m} |\n`;
+        if (fns.mutations.length > 0) {
+            md += `// ${ns} 데이터 변경 (로딩/에러 자동 관리)\n`;
+            md += `const [${fns.mutations[0]}${ns.charAt(0).toUpperCase() + ns.slice(1)}, isPending] = useMutation(api.${ns}.${fns.mutations[0]});\n`;
         }
+        md += `\n`;
     }
-
-    md += `\n### 호출 예시\n\n`;
+    md += `\`\`\`\n\n`;
+    md += `### ❌ 절대 하지 마세요\n\n`;
     md += `\`\`\`typescript\n`;
-    md += `// Query (GET)\n`;
-    md += `const res = await fetch("http://localhost:5456/api/fn/${namespaces[0]}/${Object.values(apiObj)[0]?.queries?.[0] || "list"}", {\n`;
-    md += `    credentials: "include",  // ← 쿠키 전송 필수!\n`;
-    md += `});\n\n`;
-    md += `// Query (POST)\n`;
-    md += `const res = await fetch("http://localhost:5456/api/fn/${namespaces[0]}/${Object.values(apiObj)[0]?.queries?.[0] || "list"}", {\n`;
-    md += `    method: "POST",\n`;
-    md += `    headers: { "Content-Type": "application/json" },\n`;
-    md += `    credentials: "include",\n`;
-    md += `    body: JSON.stringify({}),  // args\n`;
-    md += `});\n\n`;
-    if (Object.values(apiObj)[0]?.mutations?.length > 0) {
-        const firstMut = Object.values(apiObj)[0].mutations[0];
-        md += `// Mutation\n`;
-        md += `const res = await fetch("http://localhost:5456/api/fn/${namespaces[0]}/${firstMut}", {\n`;
-        md += `    method: "POST",\n`;
-        md += `    headers: { "Content-Type": "application/json" },\n`;
-        md += `    credentials: "include",\n`;
-        md += `    body: JSON.stringify({ /* args */ }),\n`;
-        md += `});\n`;
-    }
+    md += `// ❌ fetch()로 직접 API 호출하지 마세요\n`;
+    md += `fetch("/api/query", { body: JSON.stringify({ name: "tasks.create", args: {...} }) })\n`;
+    md += `apiPost("tasks/create", { ... })  // ❌ 래퍼도 만들지 마세요\n\n`;
+    md += `// ✅ useMutation을 사용하세요 — 실시간 동기화 + 로딩 상태 자동 관리\n`;
+    md += `const [create] = useMutation(api.tasks.create);\n`;
+    md += `await create({ title: "새 태스크" });\n`;
+    md += `// → 서버가 WebSocket으로 useQuery를 자동 갱신 — fetchTasks() 같은 수동 리페치 불필요!\n`;
     md += `\`\`\`\n\n`;
 
-    md += `> **API 목록 자동 조회:** \`GET /api/fn\` 으로 등록된 전체 API 목록을 JSON으로 받을 수 있습니다.\n\n`;
-
     // ── 1-2. Auth ────────────────────────────────────────────
     md += `---\n\n## 🔐 인증 (better-auth, 세션 기반)\n\n`;
     md += `| 엔드포인트 | 메서드 | 설명 |\n`;
@@ -421,22 +402,36 @@ function generateReadmeMd(config, apiObj) {
     md += `| \`/api/auth/sign-out\` | POST | 로그아웃 |\n\n`;
     md += `> ⚠️ 모든 API 요청에 \`credentials: "include"\`를 포함해야 합니다 (세션 쿠키 전송)\n`;
     md += `> ⚠️ JWT 토큰이나 \`/auth/register\` 같은 커스텀 경로를 만들지 마세요.\n\n`;
-    md += `---\n\n## ⚡ React 사용법 (Next.js / Vite)\n\n`;
+
+    // ── 1-3. RPC 직접 호출 (접힘 — 비-React 환경용) ──────────
+    md += `---\n\n`;
+    md += `<details>\n`;
+    md += `<summary>📡 RPC 직접 호출 (Node.js / cURL / 비-React 환경)</summary>\n\n`;
+    md += `> ⚠️ React에서는 이 방법을 사용하지 마세요. 위의 \`useQuery\`/\`useMutation\`을 사용하세요.\n\n`;
     md += `\`\`\`typescript\n`;
-    md += `import { api } from "@/gencow/api";\n`;
-    md += `import { useQuery, useMutation } from "@gencow/react";\n\n`;
-    for (const [ns, fns] of Object.entries(apiObj)) {
-        if (fns.queries.length > 0) {
-            md += `// ${ns} 데이터 조회\n`;
-            md += `const ${ns} = useQuery(api.${ns}.${fns.queries[0]});\n`;
-        }
-        if (fns.mutations.length > 0) {
-            md += `// ${ns} 데이터 변경\n`;
-            md += `const [${fns.mutations[0]}${ns.charAt(0).toUpperCase() + ns.slice(1)}] = useMutation(api.${ns}.${fns.mutations[0]});\n`;
-        }
-        md += `\n`;
+    md += `// Query 호출\n`;
+    md += `const res = await fetch("http://localhost:5456/api/query", {\n`;
+    md += `    method: "POST",\n`;
+    md += `    headers: { "Content-Type": "application/json" },\n`;
+    md += `    credentials: "include",\n`;
+    if (namespaces.length > 0 && Object.values(apiObj)[0]?.queries?.[0]) {
+        md += `    body: JSON.stringify({ name: "${namespaces[0]}.${Object.values(apiObj)[0].queries[0]}", args: {} }),\n`;
+    } else {
+        md += `    body: JSON.stringify({ name: "namespace.functionName", args: {} }),\n`;
+    }
+    md += `});\n\n`;
+    if (Object.values(apiObj)[0]?.mutations?.length > 0) {
+        const firstMut = Object.values(apiObj)[0].mutations[0];
+        md += `// Mutation 호출\n`;
+        md += `const res = await fetch("http://localhost:5456/api/mutation", {\n`;
+        md += `    method: "POST",\n`;
+        md += `    headers: { "Content-Type": "application/json" },\n`;
+        md += `    credentials: "include",\n`;
+        md += `    body: JSON.stringify({ name: "${namespaces[0]}.${firstMut}", args: { /* ... */ } }),\n`;
+        md += `});\n`;
     }
     md += `\`\`\`\n\n`;
+    md += `</details>\n\n`;
 
     // ── 3. Copy-Paste AI Prompt ────────────────────────────
     md += `---\n\n## 🤖 AI Vibe-Coding Prompt (복사해서 AI에게 전달)\n\n`;
@@ -450,11 +445,15 @@ function generateReadmeMd(config, apiObj) {
     }
     md += `\n`;
     md += `React Hook 사용법:\n`;
-    md += `  useQuery(api.namespace.fnName)        // 데이터 구독\n`;
-    md += `  useMutation(api.namespace.fnName)     // 데이터 변경\n`;
+    md += `  useQuery(api.namespace.fnName)        // 데이터 구독 (실시간 자동 갱신)\n`;
+    md += `  useMutation(api.namespace.fnName)     // 데이터 변경 (로딩/에러 자동 관리)\n`;
+    md += `\n`;
+    md += `⚠️ 중요 규칙:\n`;
+    md += `- 반드시 useQuery와 useMutation을 사용해서 데이터와 연결해줘.\n`;
+    md += `- fetch()를 직접 호출하거나 apiPost() 같은 래퍼를 만들지 마.\n`;
+    md += `- gencow/api.ts는 자동 생성된 파일이야. 수동으로 만들지 마.\n`;
     md += `\n`;
     md += `위 API를 기반으로 Next.js + Tailwind CSS UI 컴포넌트를 만들어줘.\n`;
-    md += `- useQuery와 useMutation을 사용해서 실제 데이터와 연결해줘.\n`;
     md += `- TypeScript 타입을 최대한 활용하고, 로딩/에러 상태도 처리해줘.\n`;
     md += `\`\`\`\n\n`;
 

package/package.json

@@ -1,31 +1,30 @@
 {
-    "name": "gencow",
-    "version": "0.1.4",
-    "description": "Gencow — Backend OS for AI Agents",
-    "type": "module",
-    "bin": {
-        "gencow": "./bin/gencow.mjs"
-    },
-    "files": [
-        "bin/",
-        "templates/",
-        "server/",
-        "scripts/",
-        "dashboard/"
-    ],
-    "scripts": {
-        "build": "node scripts/bundle-server.mjs",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.27.1",
-        "open": "^10.1.0",
-        "tar": "^7",
-        "ws": "^8.19.0",
-        "zod": "^4.3.6"
-    },
-    "devDependencies": {
-        "@types/node": "^25",
-        "esbuild": "^0.27.3"
-    }
-}
+  "name": "gencow",
+  "version": "0.1.5",
+  "description": "Gencow — Backend OS for AI Agents",
+  "type": "module",
+  "bin": {
+    "gencow": "./bin/gencow.mjs"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "server/",
+    "scripts/",
+    "dashboard/"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "open": "^10.1.0",
+    "tar": "^7",
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25",
+    "esbuild": "^0.27.3"
+  },
+  "scripts": {
+    "build": "node scripts/bundle-server.mjs"
+  }
+}