phalanx-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,47 @@
+// 생성자 parameter property는 쓰지 않는다. node --test가 strip-only 모드로 .ts를 실행하는데
+// 그 문법은 변환이 필요해 거절된다.
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+    }
+}
+const ENV_HELP = "PHALANX_URL과 PHALANX_API_KEY 환경변수가 필요합니다. 툴의 /api-keys 화면에서 키를 발급하면 MCP 설정 JSON이 함께 나옵니다.";
+// 서버 시작이 아니라 도구를 부를 때 읽는다. 시작 자체가 죽으면 호스트는 이유를 보여 주지 않는다.
+export function readEnv(env) {
+    const url = env.PHALANX_URL?.replace(/\/+$/, "");
+    const key = env.PHALANX_API_KEY;
+    if (!url) {
+        throw new Error(`PHALANX_URL이 없습니다. ${ENV_HELP}`);
+    }
+    if (!key) {
+        throw new Error(`PHALANX_API_KEY가 없습니다. ${ENV_HELP}`);
+    }
+    return { url, key };
+}
+// 사용자가 따라갈 수 있는 문구로 바꾼다. 401은 키 문제라 발급 화면을 가리킨다.
+export function describeApiError(status, serverMessage, serverUrl) {
+    const base = serverMessage ?? `서버가 ${status}를 돌려주었습니다.`;
+    if (status === 401) {
+        return `API 키가 없거나 폐기되었습니다. ${serverUrl}/api-keys 에서 새로 발급해 PHALANX_API_KEY에 넣으세요. (${base})`;
+    }
+    return base;
+}
+export function createClient(config, fetchFn = fetch) {
+    return {
+        async get(path, query = {}) {
+            const params = new URLSearchParams(Object.entries(query).filter((entry) => entry[1] !== undefined));
+            const search = params.size > 0 ? `?${params}` : "";
+            const response = await fetchFn(`${config.url}${path}${search}`, {
+                headers: { "x-api-key": config.key, accept: "application/json" },
+            });
+            if (!response.ok) {
+                const body = (await response.json().catch(() => null));
+                throw new ApiError(response.status, describeApiError(response.status, body?.error ?? null, config.url));
+            }
+            return response.json();
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createClient, readEnv } from "./client.js";
+import { registerTools } from "./tools/index.js";
+// env 검증은 도구를 부를 때 한다. 여기서 던지면 호스트는 "연결 실패"만 보여 주고 이유를 감춘다.
+serveStdio(() => {
+    const server = new McpServer({ name: "phalanx", version: "0.1.0" });
+    registerTools(server, () => createClient(readEnv(process.env)));
+    return server;
+});

package/dist/tools/get-naming-rules.js

@@ -0,0 +1,8 @@
+import * as z from "zod";
+import { run } from "./shared.js";
+export function registerGetNamingRules(server, getClient) {
+    server.registerTool("get_naming_rules", {
+        description: "이 프로젝트의 리소스 이름 규칙과 카테고리별 폴더. 리소스 이름을 짓거나 코드에서 경로를 추측할 때 본다.",
+        inputSchema: z.object({ project: z.string().describe("프로젝트 slug") }),
+    }, ({ project }) => run(getClient, (client) => client.get(`/api/projects/${encodeURIComponent(project)}/naming-rules`)));
+}

package/dist/tools/index.js

@@ -0,0 +1,12 @@
+import { registerListProjects } from "./list-projects.js";
+import { registerListRecentFiles } from "./list-recent-files.js";
+import { registerListBundles } from "./list-bundles.js";
+import { registerListBundleFiles } from "./list-bundle-files.js";
+import { registerGetNamingRules } from "./get-naming-rules.js";
+export function registerTools(server, getClient) {
+    registerListProjects(server, getClient);
+    registerListRecentFiles(server, getClient);
+    registerListBundles(server, getClient);
+    registerListBundleFiles(server, getClient);
+    registerGetNamingRules(server, getClient);
+}

package/dist/tools/list-bundle-files.js

@@ -0,0 +1,8 @@
+import * as z from "zod";
+import { run } from "./shared.js";
+export function registerListBundleFiles(server, getClient) {
+    server.registerTool("list_bundle_files", {
+        description: "묶음 하나의 파일 전체. error 상태 파일의 error 필드가 왜 막혔는지, result.warnings가 확인할 점을 담는다.",
+        inputSchema: z.object({ bundle_id: z.string().uuid().describe("list_bundles가 돌려준 id") }),
+    }, ({ bundle_id }) => run(getClient, (client) => client.get(`/api/bundles/${bundle_id}/files`)));
+}

package/dist/tools/list-bundles.js

@@ -0,0 +1,20 @@
+import * as z from "zod";
+import { run } from "./shared.js";
+const STATUSES = [
+    "uploaded",
+    "analyzing",
+    "needs_art_fix",
+    "branch_ready",
+    "in_review",
+    "merged",
+    "rejected",
+];
+export function registerListBundles(server, getClient) {
+    server.registerTool("list_bundles", {
+        description: "리소스 묶음(업로드 단위) 목록. needs_art_fix는 막힌 파일이 있어 사람 처리가 필요한 묶음, in_review는 승인 대기다.",
+        inputSchema: z.object({
+            project: z.string().describe("프로젝트 slug"),
+            status: z.enum(STATUSES).optional().describe("이 상태만"),
+        }),
+    }, ({ project, status }) => run(getClient, (client) => client.get(`/api/projects/${encodeURIComponent(project)}/bundles`, { status })));
+}

package/dist/tools/list-projects.js

@@ -0,0 +1,8 @@
+import * as z from "zod";
+import { run } from "./shared.js";
+export function registerListProjects(server, getClient) {
+    server.registerTool("list_projects", {
+        description: "내가 접근할 수 있는 프로젝트 목록. 다른 도구의 project 인자에는 여기 나온 slug를 넣는다.",
+        inputSchema: z.object({}),
+    }, () => run(getClient, (client) => client.get("/api/projects")));
+}

package/dist/tools/list-recent-files.js

@@ -0,0 +1,13 @@
+import * as z from "zod";
+import { run } from "./shared.js";
+export function registerListRecentFiles(server, getClient) {
+    server.registerTool("list_recent_files", {
+        description: "이름이 확정된 리소스를 최근 순으로. status가 committed면 레포에 들어가 targetPath를 코드에 바로 쓸 수 있고, proposed면 승인 대기 중이라 경로가 바뀔 수 있다.",
+        inputSchema: z.object({
+            project: z.string().describe("프로젝트 slug"),
+            limit: z.number().int().min(1).max(200).optional().describe("최대 개수. 기본 60"),
+        }),
+    }, ({ project, limit }) => run(getClient, (client) => client.get(`/api/projects/${encodeURIComponent(project)}/resources`, {
+        limit: limit === undefined ? undefined : String(limit),
+    })));
+}

package/dist/tools/shared.js

@@ -0,0 +1,19 @@
+// 결과는 JSON 문자열 하나로 넘긴다. 호스트 모델이 그대로 읽는다.
+export function textResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+// 오류는 isError로 표시해 모델이 사용자에게 문구를 전달하게 한다. 예외로 던지면 호스트가 삼킨다.
+export function errorResult(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+    };
+}
+export async function run(getClient, call) {
+    try {
+        return textResult(await call(getClient()));
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "phalanx-mcp",
+  "version": "0.1.0",
+  "description": "gamedev-phalanx MCP server. 개인 AI에서 프로젝트·리소스·묶음·네이밍 규칙을 읽는다.",
+  "type": "module",
+  "bin": { "phalanx-mcp": "./dist/index.js" },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5"
+  },
+  "engines": { "node": ">=20" },
+  "license": "UNLICENSED"
+}