aimakeall-mcp 0.14.0 → 0.14.1

package/README.md

@@ -42,6 +42,29 @@ npx -y aimakeall-mcp@0.14.0 --version
 npx -y aimakeall-mcp@0.14.0 --update-status
 ```
 
+### 연결된 세션의 버전 조회 (런타임 0.14.1부터)
+
+클라이언트의 `/mcp` 메뉴가 버전 필드를 표시하지 않아도 AI에게 **“mcp_status로 지금 연결된 MCP 버전과 업데이트 상태를 확인해 줘”**라고 요청할 수 있습니다. 이 도구는 PAT·로그인·유료 API·렌더 컴패니언 없이 동작합니다.
+
+- `mcp_status({})`: 현재 실행 버전과 공식 승인 최신 버전을 비교합니다. 승인 API만 최대 2.5초 조회하며 다운로드·설치·캐시 쓰기·프로세스 종료/재연결은 하지 않습니다.
+- `mcp_status({checkForUpdates:false})`: 외부 네트워크 없이 로컬 상태만 읽습니다.
+- 리소스 `aimakeall://mcp/status`: 위 로컬 전용 상태를 JSON으로 제공합니다. 리소스 검색에도 표시되며, 최신 승인 버전 확인에는 `mcp_status`를 사용합니다.
+- `runtimeVersion`: **이 연결에서 이미 실행 중인 버전**입니다. 디스크 패키지가 갱신돼도 실행 중인 버전은 바뀌지 않습니다.
+- `runtimePackageVersionOnDisk`: 실행된 런타임 위치의 현재 패키지 버전입니다. 자동 업데이트 캐시에서 실행 중이라면 캐시 패키지를 뜻하며, 전역 설치된 부트스트랩 버전과는 다릅니다.
+- `latestApprovedVersion` / `updateAvailable` / `reconnectRequired`: 승인된 새 버전과 재연결 필요성을 구분합니다. 조회 실패나 생략은 `null`로 표시하므로 이를 “최신”으로 해석하지 마세요. `ahead-of-approved`도 공식 최신이라는 뜻이 아닙니다.
+- `autoUpdateEnabled`: MCP 시작 시 자동 업데이트 설정입니다. 꺼져 있어도 상태 조회는 가능하지만 재연결만으로 새 버전을 설치하지 않습니다.
+
+CLI의 `--version`은 **그 명령으로 실행한 실행기**의 버전이며 기존 세션의 버전을 증명하지 않습니다. `--update-status`도 기존 연결을 갱신하지 않습니다. 현재 연결에 `mcp_status`가 없으면 구버전이므로, 새 버전 게시와 운영 승인 후 진행 중인 작업이 끝난 유휴 상태에서 MCP를 다시 연결하세요. 기존 `@0.14.0` 부트스트랩 설정은 유지합니다.
+
+### 새 버전 재연결 안내
+
+일반 MCP 도구를 호출할 때 공식 승인 버전을 확인하고, 새 버전이나 런타임 디스크 변경이 감지되면 도구 응답에 **MCP 업데이트 안내**를 덧붙입니다. 원래 성공/오류/이미지/구조화 결과는 그대로 보존합니다. 클라이언트 AI에는 이 안내를 사용자에게 전달하도록 초기화 지침을 제공합니다. 특정 클라이언트의 `/mcp` 화면이나 토스트 UI를 강제로 변경하는 기능은 아닙니다.
+
+- 첫 도구 호출 이후 최대 5분에 한 번, 다음 도구 호출 때만 조회합니다. 작업 없이 백그라운드 타이머를 돌리거나 호출할 때마다 서버에 요청하지 않습니다.
+- 같은 대상 버전은 연결당 한 번만 안내하며, 동시 호출도 중복 조회/안내하지 않습니다. 조회 실패나 확인되지 않은 버전은 업데이트 안내를 만들지 않습니다.
+- 안내를 받으면 **진행 중인 제작·렌더를 마친 뒤** `/mcp` → `aimakeall` → `Reconnect`로 재연결합니다. 다른 클라이언트에서는 해당 MCP 서버를 재연결합니다. 자동 업데이트를 껐다면 설정도 다시 활성화해야 합니다.
+- 구버전 프로세스에는 새 알림 기능이 소급 적용되지 않습니다. 이 기능이 포함된 런타임 0.14.1을 최초 한 번 받은 이후의 업데이트부터 자동 안내가 가능합니다. 알림 전달과 실제 업데이트는 별개이며, 설치는 여전히 다음 시작/재연결 시에만 수행합니다.
+
 ## 환경변수
 
 | 변수 | 기본값 | 설명 |

package/lib/config.mjs

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 
 // 프록시 버전 — 서버가 X-AImakeAll-MCP-Version 으로 하한을 강제(426)할 수 있다.
-export const MCP_PROXY_VERSION = "0.14.0";
+export const MCP_PROXY_VERSION = "0.14.1";
 
 export const DEFAULT_API_BASE = "https://aimakeall.com";
 export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";

package/lib/mcp-status.mjs

@@ -0,0 +1,127 @@
+// Read-only diagnostics. Never select/install a runtime or read application credentials.
+import { readFile } from "node:fs/promises";
+
+import { compareVersions, RELEASE_URL, requestBytes, validateManifest } from "./auto-update.mjs";
+
+const MAX_MANIFEST_BYTES = 16 * 1024;
+const MANIFEST_TIMEOUT_MS = 2_500;
+
+function validVersion(value) {
+  if (typeof value !== "string") return null;
+  try {
+    compareVersions(value, value);
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function readRuntimePackageVersion() {
+  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  return pkg?.name === "aimakeall-mcp" ? validVersion(pkg.version) : null;
+}
+
+function timestamp(now) {
+  try {
+    const value = now();
+    return typeof value === "number" && Number.isFinite(value) ? new Date(value).toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+function guidanceFor(status, diskChanged, autoUpdateEnabled) {
+  const messages = {
+    "up-to-date": "실행 중인 MCP 버전이 공식 승인 버전과 같습니다.",
+    "update-available": "공식 승인된 더 높은 MCP 버전이 있습니다.",
+    "ahead-of-approved": "실행 중인 MCP 버전이 공식 승인 버전보다 높습니다. 최신 승인 버전이라고 단정할 수 없으며, 재연결 시 승인 버전으로 돌아갈 수 있습니다.",
+    unavailable: "공식 승인 버전을 확인하지 못했습니다. 현재 실행 버전만 확인할 수 있으며 최신 여부는 알 수 없습니다.",
+    "not-checked": "공식 승인 버전은 조회하지 않았습니다. 현재 실행 버전만 확인할 수 있으며 최신 여부는 알 수 없습니다.",
+  };
+  const parts = [messages[status]];
+  if (diskChanged) {
+    parts.push("실행 중인 버전과 런타임 패키지의 디스크 버전이 다릅니다.");
+  }
+  if (!autoUpdateEnabled) {
+    parts.push("자동 업데이트가 꺼져 있습니다. 업데이트가 필요하면 AIMAKEALL_MCP_AUTO_UPDATE=0 설정을 해제한 뒤 작업 종료 후 재연결하거나, 승인 버전을 별도로 설치하세요.");
+  }
+  if (status === "update-available" || diskChanged) {
+    parts.push("진행 중인 작업을 끝낸 뒤 유휴 상태에서 /mcp → aimakeall → Reconnect를 선택하세요(다른 클라이언트는 MCP 재연결).");
+  }
+  parts.push("이 상태 조회는 설치, 실행 버전 변경 또는 재시작을 하지 않습니다.");
+  return parts.join(" ");
+}
+
+/**
+ * Capture the running process identity once. The adjacent package can change
+ * after startup, but its on-disk version must never replace runtimeVersion.
+ * readInstalledVersion returns a version string (or null), not a global npm path.
+ * checkedAt is the completed manifest-check time, or null when not requested.
+ */
+export function createMcpStatusReader({
+  runtimeVersion,
+  readInstalledVersion = readRuntimePackageVersion,
+  download = requestBytes,
+  now = Date.now,
+  env = process.env,
+  nodeVersion = process.versions.node,
+  pid = process.pid,
+  platform = process.platform,
+} = {}) {
+  const version = validVersion(runtimeVersion);
+  if (!version) throw new Error("Invalid MCP runtime version");
+  const startedAt = timestamp(now);
+  const autoUpdateEnabled = env.AIMAKEALL_MCP_AUTO_UPDATE !== "0";
+  const processIdentity = Object.freeze({ pid, startedAt, nodeVersion, platform });
+  const nodeMajor = Number(nodeVersion.split(".")[0]);
+
+  return async function readMcpStatus({ checkForUpdates = true } = {}) {
+    let runtimePackageVersionOnDisk = null;
+    try {
+      runtimePackageVersionOnDisk = validVersion(await readInstalledVersion());
+    } catch {
+      // The path, credentials, or arbitrary exception text must never reach MCP output.
+    }
+    const diskChanged = runtimePackageVersionOnDisk !== null && runtimePackageVersionOnDisk !== version;
+    let latestApprovedVersion = null;
+    let updateStatus = "not-checked";
+    let updateAvailable = null;
+    let reconnectRequired = diskChanged ? true : null;
+    let checkedAt = null;
+
+    if (checkForUpdates) {
+      try {
+        const bytes = await download(RELEASE_URL, {
+          maxBytes: MAX_MANIFEST_BYTES,
+          timeoutMs: MANIFEST_TIMEOUT_MS,
+        });
+        if (!Buffer.isBuffer(bytes) || bytes.length > MAX_MANIFEST_BYTES) throw new Error("Invalid MCP release metadata");
+        const approved = validateManifest(JSON.parse(bytes.toString("utf8")), nodeMajor);
+        latestApprovedVersion = approved.version;
+        const comparison = compareVersions(approved.version, version);
+        updateStatus = comparison > 0 ? "update-available" : comparison < 0 ? "ahead-of-approved" : "up-to-date";
+        updateAvailable = comparison > 0;
+        // A higher running version may be rolled back on reconnect; do not
+        // promise that reconnect is unnecessary in that case.
+        reconnectRequired = diskChanged || updateAvailable ? true : comparison < 0 ? null : false;
+      } catch {
+        updateStatus = "unavailable";
+      }
+      checkedAt = timestamp(now);
+    }
+
+    return {
+      schemaVersion: 1,
+      runtimeVersion: version,
+      runtimePackageVersionOnDisk,
+      latestApprovedVersion,
+      updateStatus,
+      updateAvailable,
+      reconnectRequired,
+      autoUpdateEnabled,
+      checkedAt,
+      process: { ...processIdentity },
+      guidance: guidanceFor(updateStatus, diskChanged, autoUpdateEnabled),
+    };
+  };
+}

package/lib/status-tools.mjs

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { createMcpStatusReader } from "./mcp-status.mjs";
+
+export const MCP_STATUS_RESOURCE_URI = "aimakeall://mcp/status";
+export const MCP_STATUS_INSTRUCTIONS = "MCP 버전이나 업데이트 상태를 물으면 mcp_status를 호출하세요. runtimeVersion은 이 연결에서 실제 실행 중인 버전입니다. 설치 파일 버전, npm 태그, MoviePy 버전으로 대신 답하지 마세요. 이 도구는 읽기 전용이며 업데이트나 재연결을 실행하지 않습니다. 도구 결과에 MCP 업데이트 안내가 포함되면 사용자에게 전달하세요. 진행 중인 제작·렌더는 그대로 마치고, 유휴 상태에서만 사용자의 요청에 따라 재연결하세요.";
+
+export function registerMcpStatusTools(server, config, {
+  readStatus = createMcpStatusReader({ runtimeVersion: config.version }),
+} = {}) {
+  server.registerTool("mcp_status", {
+    title: "AImakeAll MCP 버전 및 업데이트 상태",
+    description: "현재 연결된 MCP 프로세스의 실제 버전, 디스크의 런타임 패키지 버전, 공식 승인 최신 버전, 자동 업데이트 설정, 업데이트·재연결 필요 여부를 확인합니다. 버전 질문에는 이 도구를 사용하세요. PAT/유료 API/컴패니언 없이 동작하며 설치·재시작·파일 변경을 하지 않습니다. 확인 실패는 최신으로 단정하지 않고 unknown(null)으로 반환합니다.",
+    inputSchema: {
+      checkForUpdates: z.boolean().default(true).describe("공식 승인 버전 조회 여부. false이면 외부 네트워크 없이 현재 실행 버전만 확인합니다."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, async ({ checkForUpdates }) => {
+    const status = await readStatus({ checkForUpdates });
+    return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }], structuredContent: status };
+  });
+
+  server.registerResource("aimakeall-mcp-status", MCP_STATUS_RESOURCE_URI, {
+    title: "AImakeAll MCP 실행 버전",
+    description: "이 연결의 실행 버전과 로컬 상태를 네트워크 없이 읽습니다. 공식 승인 최신 버전과 비교하려면 mcp_status 도구를 호출하세요.",
+    mimeType: "application/json",
+  }, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await readStatus({ checkForUpdates: false }), null, 2) }],
+  }));
+}

package/lib/update-notice.mjs

@@ -0,0 +1,100 @@
+// Opportunistic read-only notices: no polling timer, installer, or tool replay.
+import { compareVersions } from "./auto-update.mjs";
+
+const DEFAULT_INTERVAL_MS = 5 * 60_000;
+
+function validVersion(value) {
+  if (typeof value !== "string") return null;
+  try { compareVersions(value, value); return value; }
+  catch { return null; }
+}
+
+function updateTarget(status) {
+  const runtimeVersion = validVersion(status?.runtimeVersion);
+  if (!runtimeVersion) return null;
+  const approvedVersion = validVersion(status.latestApprovedVersion);
+  if (status.updateAvailable === true && approvedVersion && compareVersions(approvedVersion, runtimeVersion) > 0) {
+    return { runtimeVersion, targetVersion: approvedVersion, kind: "approved", autoUpdateEnabled: status.autoUpdateEnabled };
+  }
+  const diskVersion = validVersion(status.runtimePackageVersionOnDisk);
+  if (status.reconnectRequired === true && diskVersion && diskVersion !== runtimeVersion) {
+    return { runtimeVersion, targetVersion: diskVersion, kind: "disk", autoUpdateEnabled: status.autoUpdateEnabled };
+  }
+  return null;
+}
+
+function noticeText(target) {
+  const lines = [target.kind === "approved"
+    ? `[AImakeAll MCP 업데이트 안내] 현재 실행 ${target.runtimeVersion} → 공식 승인 ${target.targetVersion}.`
+    : `[AImakeAll MCP 재연결 안내] 현재 실행 ${target.runtimeVersion}, 디스크 런타임 패키지 ${target.targetVersion}: 실행 중인 버전은 아직 바뀌지 않았습니다.`];
+  if (target.autoUpdateEnabled === false) {
+    lines.push("자동 업데이트가 꺼져 있습니다. 승인 버전을 자동 적용하려면 AIMAKEALL_MCP_AUTO_UPDATE 설정을 켠 뒤 재연결하세요.");
+  }
+  lines.push("현재 작업이 모두 끝난 유휴 상태에서 /mcp → aimakeall → Reconnect를 선택하세요. 다른 MCP 클라이언트에서는 AImakeAll MCP 연결을 재연결하세요.");
+  lines.push("진행 중인 작업이나 MCP 프로세스를 강제 종료하지 마세요. 이 안내는 업데이트 설치·재시작·도구 재실행을 하지 않습니다.");
+  return lines.join("\n");
+}
+
+/**
+ * Register ordinary tools through this facade; registration/listing does no work.
+ * A real invocation checks release status alongside the handler, at most once per
+ * interval. Only the first returned result for a target version gets a notice.
+ */
+export function createUpdateNoticeTools(server, { readStatus, now = Date.now, intervalMs = DEFAULT_INTERVAL_MS } = {}) {
+  const interval = Number.isFinite(intervalMs) && intervalMs >= 0 ? intervalMs : DEFAULT_INTERVAL_MS;
+  const announcedTargets = new Set();
+  let cachedStatus = null;
+  let checkedAt = null;
+  let flight = null;
+
+  const currentTime = () => {
+    try { const value = now(); return typeof value === "number" && Number.isFinite(value) ? value : null; }
+    catch { return null; }
+  };
+
+  function checkStatus() {
+    if (flight) return flight;
+    const instant = currentTime();
+    if (checkedAt !== null && instant !== null && instant >= checkedAt && instant - checkedAt < interval) {
+      return Promise.resolve(cachedStatus);
+    }
+    const pending = Promise.resolve()
+      .then(() => typeof readStatus === "function" ? readStatus({ checkForUpdates: true }) : null)
+      .then((status) => { cachedStatus = status; return status; }, () => { cachedStatus = null; return null; })
+      .finally(() => {
+        checkedAt = currentTime();
+        if (flight === pending) flight = null;
+      });
+    flight = pending;
+    return pending;
+  }
+
+  function wrapHandler(handler) {
+    return async function (...args) {
+      const statusPromise = checkStatus();
+      // Run exactly once; a thrown/rejected original error is never intercepted.
+      const result = await Reflect.apply(handler, this, args);
+      try {
+        await statusPromise;
+        // A long-running tool may finish after a newer check. Do not announce an
+        // older cached release if a later check has replaced it (even with unknown).
+        const target = updateTarget(cachedStatus);
+        if (!target || announcedTargets.has(target.targetVersion)
+          || !result || typeof result !== "object" || Array.isArray(result)
+          || (result.content !== undefined && !Array.isArray(result.content))) return result;
+        const output = { ...result, content: [...(result.content || []), { type: "text", text: noticeText(target) }] };
+        announcedTargets.add(target.targetVersion);
+        return output;
+      } catch {
+        // Status/formatting failures cannot change the original tool result.
+        return result;
+      }
+    };
+  }
+
+  return Object.fromEntries(["tool", "registerTool"].map((method) => [method, (...args) => {
+    const handler = args.at(-1);
+    const registration = typeof handler === "function" ? [...args.slice(0, -1), wrapHandler(handler)] : args;
+    return Reflect.apply(server[method], server, registration);
+  }]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimakeall-mcp",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "AImakeAll MCP 서버 — Claude Code/Codex에서 자연어로 영상 기획·생성·렌더·퍼블리시 (렌더는 로컬 컴패니언)",
   "type": "module",
   "bin": {

package/runtime.mjs

@@ -5,6 +5,9 @@ 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 { registerMcpStatusTools, MCP_STATUS_INSTRUCTIONS } from "./lib/status-tools.mjs";
+import { createMcpStatusReader } from "./lib/mcp-status.mjs";
+import { createUpdateNoticeTools } from "./lib/update-notice.mjs";
 import { MCP_PROXY_VERSION, resolveConfig } from "./lib/config.mjs";
 import { pruneOldMedia } from "./lib/media-store.mjs";
 
@@ -15,10 +18,13 @@ const config = selfCheck ? {
   apiBase: "https://aimakeall.com", companionUrl: "http://127.0.0.1:9876",
   pat: "", patLooksValid: false, outputDir: "", stateDir: "", version: MCP_PROXY_VERSION,
 } : resolveConfig();
-const server = new McpServer({ name: "aimakeall", version: MCP_PROXY_VERSION });
+const server = new McpServer({ name: "aimakeall", version: MCP_PROXY_VERSION }, { instructions: MCP_STATUS_INSTRUCTIONS });
 const api = createApiClient({ apiBase: config.apiBase, pat: config.pat });
-registerCloudTools(server, config, api);
-registerCompanionTools(server, config);
+const readStatus = createMcpStatusReader({ runtimeVersion: MCP_PROXY_VERSION });
+registerMcpStatusTools(server, config, { readStatus });
+const toolServer = createUpdateNoticeTools(server, { readStatus });
+registerCloudTools(toolServer, config, api);
+registerCompanionTools(toolServer, config);
 
 if (selfCheck) {
   console.log(JSON.stringify({ ok: true, version: MCP_PROXY_VERSION }));