aimakeall-mcp 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# aimakeall-mcp
+
+Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영상을 만드는 stdio MCP 서버입니다.
+
+- **클라우드 툴**: 기획 → 씬 이미지/영상 생성 → TTS/음악 → 타임라인 스티치 → YouTube 퍼블리시 (PAT 인증, aimakeall.com API)
+- **로컬 툴**: mp4 렌더 — **항상 이 PC의 AImakeAll 컴패니언(127.0.0.1:9876)에서 수행**됩니다. 서버는 렌더하지 않습니다.
+
+## 설정
+
+1. [aimakeall.com](https://aimakeall.com) 로그인 → **API 키 설정 → MCP 토큰**에서 토큰 발급 (발급 직후 1회만 표시)
+2. AImakeAll 컴패니언 앱 설치·실행 (렌더용)
+3. MCP 클라이언트 설정 — 버전을 고정해 주세요:
+
+```json
+{
+  "mcpServers": {
+    "aimakeall": {
+      "command": "npx",
+      "args": ["-y", "aimakeall-mcp@0.1.0"],
+      "env": { "AIMAKEALL_PAT": "aio_pat_..." }
+    }
+  }
+}
+```
+
+## 환경변수
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `AIMAKEALL_PAT` | (필수) | MCP 토큰 (`aio_pat_...`) |
+| `AIMAKEALL_API_BASE` | `https://aimakeall.com` | API 서버 |
+| `AIMAKEALL_COMPANION_URL` | `http://127.0.0.1:9876` | 로컬 컴패니언 (SSH 터널 시 변경) |
+| `AIMAKEALL_OUTPUT_DIR` | `~/Downloads/AImakeAll` | 렌더 결과 mp4 저장 위치 |
+
+## 기본 플로우 (쇼츠)
+
+```
+plan_shorts_video → (씬마다) generate_scene_image → generate_scene_video_prompt → generate_scene_video
+→ tts_narration → stitch_timeline → render_start → render_status(폴링) → render_result
+→ ai_publish_metadata → publish_youtube
+```
+
+- 씬 영상 생성은 동기 호출로 최대 15분 걸립니다 — MCP 클라이언트의 툴 타임아웃(`MCP_TIMEOUT`)을 충분히 잡아주세요.
+- 렌더 잡은 `~/.aimakeall/render-jobs.json`에 기록되어 프록시 재시작 후 `list_render_jobs`로 복구할 수 있습니다.
+- 대용량 산출물(TTS mp3, 스티치 매니페스트)은 파일 경로로 주고받아 모델 컨텍스트를 오염시키지 않습니다.
+
+## 한도
+
+- 쓰기(생성) 호출 분당 20회, 조회 분당 120회, 동시 생성 2개 (서버 강제)
+- 사용자당 활성 PAT 5개, 기본 만료 90일

package/index.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// AImakeAll MCP 서버 (stdio) — Claude Code/Codex에서 자연어로 영상 제작.
+// 클라우드 툴은 PAT(AIMAKEALL_PAT)로 aimakeall.com API를, 렌더 툴은 이 PC의
+// 컴패니언(127.0.0.1:9876)을 호출한다. 렌더는 절대 서버에서 수행되지 않는다.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { createApiClient } from "./lib/api-client.mjs";
+import { registerCloudTools } from "./lib/cloud-tools.mjs";
+import { registerCompanionTools } from "./lib/companion-tools.mjs";
+import { MCP_PROXY_VERSION, resolveConfig } from "./lib/config.mjs";
+import { pruneOldMedia } from "./lib/media-store.mjs";
+
+const config = resolveConfig();
+
+// 오래된 스테이징 미디어 정리 (48h TTL) — 숨김 디렉터리가 무한정 커지는 것 방지.
+try {
+  pruneOldMedia(config.stateDir);
+} catch {
+  // 정리 실패는 무시
+}
+
+if (!config.pat) {
+  console.error("[aimakeall-mcp] AIMAKEALL_PAT 미설정 — 클라우드 툴은 안내만 반환합니다. aimakeall.com → API 키 설정에서 MCP 토큰을 발급해 환경변수로 넣어주세요.");
+} else if (!config.patLooksValid) {
+  console.error("[aimakeall-mcp] AIMAKEALL_PAT 형식이 올바르지 않습니다 (aio_pat_... 이어야 함).");
+}
+
+const server = new McpServer({ name: "aimakeall", version: MCP_PROXY_VERSION });
+
+const api = createApiClient({ apiBase: config.apiBase, pat: config.pat });
+registerCloudTools(server, config, api);
+registerCompanionTools(server, config);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[aimakeall-mcp] v${MCP_PROXY_VERSION} 시작 — API ${config.apiBase}, 컴패니언 ${config.companionUrl}`);

package/lib/api-client.mjs

@@ -0,0 +1,143 @@
+import { MCP_PROXY_VERSION } from "./config.mjs";
+
+// aimakeall.com API 클라이언트 — PAT(Bearer) 인증 + 프록시 버전 핸드셰이크.
+// 서버 오류 코드를 사용자 행동 가능한 한국어 안내로 매핑한다.
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export class AimakeallApiError extends Error {
+  constructor(message, { errorCode = "", retryAfterSeconds = 0, status = 0 } = {}) {
+    super(message);
+    this.errorCode = errorCode;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.status = status;
+  }
+}
+
+function describeApiFailure(status, payload) {
+  const code = String(payload?.error || "");
+  if (code === "MACHINE_TOKEN_INVALID_TOKEN") return "PAT가 유효하지 않습니다. AIMAKEALL_PAT 값을 다시 확인하세요.";
+  if (code === "MACHINE_TOKEN_EXPIRED") return "PAT가 만료되었습니다. aimakeall.com → API 키 설정에서 새 토큰을 발급해 주세요.";
+  if (code === "MACHINE_TOKEN_REVOKED") return "회수된 PAT입니다. aimakeall.com → API 키 설정에서 새 토큰을 발급해 주세요.";
+  if (code === "MACHINE_TOKEN_TEACHER_FORBIDDEN") return "교사 계정은 MCP를 사용할 수 없습니다.";
+  if (code === "MACHINE_ROUTE_FORBIDDEN") return "이 작업은 MCP 토큰으로 호출할 수 없는 경로입니다.";
+  if (code === "MACHINE_RATE_LIMITED") return "요청 한도를 초과했습니다. 잠시 후 다시 시도하세요.";
+  if (code === "MACHINE_CONCURRENCY_LIMITED") return "동시 생성 호출 한도(2개)에 도달했습니다. 진행 중인 작업이 끝난 뒤 다시 시도하세요.";
+  if (code === "PLAN_UPGRADE_REQUIRED") return String(payload?.message || "플랜 업그레이드가 필요한 기능입니다.");
+  if (status === 413) return "요청 크기가 서버 상한을 초과했습니다. 오디오는 더 짧게/낮은 비트레이트로, 이미지는 더 작게 줄여 다시 시도하세요.";
+  if (status === 431) return "요청 헤더가 너무 큽니다. 설명(description)이나 제목을 줄여 다시 시도하세요.";
+  if (status === 426) return "MCP 설정(mcpServers.args)의 aimakeall-mcp 버전을 최신으로 올린 뒤 클라이언트를 재시작하세요.";
+  const message = String(payload?.message || payload?.error || "");
+  return message || `AImakeAll API 요청 실패 (HTTP ${status})`;
+}
+
+export function createApiClient({ apiBase, pat }) {
+  async function request(pathName, { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS, rawBody, headers = {} } = {}) {
+    const requestHeaders = {
+      Authorization: `Bearer ${pat}`,
+      "X-AImakeAll-MCP-Version": MCP_PROXY_VERSION,
+      ...headers,
+    };
+    let requestBody;
+    if (rawBody !== undefined) {
+      requestBody = rawBody;
+    } else if (body !== undefined) {
+      requestHeaders["Content-Type"] = "application/json";
+      requestBody = JSON.stringify(body);
+    }
+
+    const response = await fetch(`${apiBase}${pathName}`, {
+      body: requestBody,
+      // Node fetch 는 스트림 바디에 duplex 지정이 필요하다.
+      ...(rawBody !== undefined && typeof rawBody?.pipe !== "function" && rawBody?.[Symbol.asyncIterator] ? { duplex: "half" } : {}),
+      headers: requestHeaders,
+      method,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    const text = await response.text();
+    let payload = null;
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = null;
+    }
+
+    if (!response.ok) {
+      throw new AimakeallApiError(describeApiFailure(response.status, payload), {
+        errorCode: String(payload?.error || ""),
+        retryAfterSeconds: Number(payload?.retryAfterSeconds) || Number(response.headers.get("retry-after")) || 0,
+        status: response.status,
+      });
+    }
+    return payload;
+  }
+
+  // 바이너리 응답 라우트(TTS 합성, suno 다운로드) — 실패면 JSON 에러 파싱, 성공이면 buffer.
+  async function requestBinary(pathName, { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    const headers = {
+      Authorization: `Bearer ${pat}`,
+      "X-AImakeAll-MCP-Version": MCP_PROXY_VERSION,
+    };
+    let requestBody;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      requestBody = JSON.stringify(body);
+    }
+    const response = await fetch(`${apiBase}${pathName}`, {
+      body: requestBody,
+      headers,
+      method,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+      let payload = null;
+      try {
+        payload = JSON.parse(await response.text());
+      } catch {
+        payload = null;
+      }
+      throw new AimakeallApiError(describeApiFailure(response.status, payload), {
+        errorCode: String(payload?.error || ""),
+        status: response.status,
+      });
+    }
+    return {
+      buffer: Buffer.from(await response.arrayBuffer()),
+      contentType: response.headers.get("content-type") || "application/octet-stream",
+      headers: response.headers,
+    };
+  }
+
+  // 스트림 업로드(YouTube 퍼블리시) — 로컬 파일을 raw body 로 전송.
+  async function requestStreamUpload(pathName, { stream, contentType, contentLength, timeoutMs }) {
+    const response = await fetch(`${apiBase}${pathName}`, {
+      body: stream,
+      duplex: "half",
+      headers: {
+        Authorization: `Bearer ${pat}`,
+        "Content-Length": String(contentLength),
+        "Content-Type": contentType,
+        "X-AImakeAll-MCP-Version": MCP_PROXY_VERSION,
+      },
+      method: "POST",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await response.text();
+    let payload = null;
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = null;
+    }
+    if (!response.ok) {
+      throw new AimakeallApiError(describeApiFailure(response.status, payload), {
+        errorCode: String(payload?.error || ""),
+        status: response.status,
+      });
+    }
+    return payload;
+  }
+
+  return { request, requestBinary, requestStreamUpload };
+}