@yinuo-ngm/mcp-server 0.1.2 → 0.1.4

package/lib/tools/project/observe-runtime.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localServerAvailability = localServerAvailability;
+exports.runtimeSummary = runtimeSummary;
+exports.taskSummary = taskSummary;
+exports.latestTimestamp = latestTimestamp;
+exports.taskStatus = taskStatus;
+exports.listProjectRows = listProjectRows;
+exports.activeTasks = activeTasks;
+exports.fitLogLines = fitLogLines;
+const observe_redaction_1 = require("./observe-redaction");
+function defaultLocalServer() {
+    return { available: false, reason: "local server client is not configured" };
+}
+async function localServerAvailability(context) {
+    return context.services.localServer ? context.services.localServer.availability() : defaultLocalServer();
+}
+function pidExists(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "ESRCH")
+            return false;
+        if (error?.code === "EPERM")
+            return true;
+        return null;
+    }
+}
+function parsePortFromUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+        return { url: (0, observe_redaction_1.redactText)(value), host: url.hostname, port, protocol: url.protocol.replace(":", "") };
+    }
+    catch {
+        return null;
+    }
+}
+function portSummary(runtime) {
+    const urls = Array.isArray(runtime?.urls) ? runtime?.urls : [];
+    return urls.map(parsePortFromUrl).filter(Boolean);
+}
+function runtimeSummary(runtime) {
+    if (!runtime)
+        return undefined;
+    return {
+        taskId: runtime.taskId,
+        runId: runtime.runId,
+        status: runtime.status,
+        pid: runtime.pid,
+        pidExists: pidExists(runtime.pid),
+        startedAt: runtime.startedAt,
+        stoppedAt: runtime.stoppedAt,
+        lastOutputAt: runtime.lastOutputAt,
+        readyAt: runtime.readyAt,
+        exitCode: runtime.exitCode,
+        signal: runtime.signal,
+        lastError: typeof runtime.lastError === "string" ? (0, observe_redaction_1.redactText)(runtime.lastError) : runtime.lastError,
+        urls: Array.isArray(runtime.urls) ? runtime.urls.map((url) => typeof url === "string" ? (0, observe_redaction_1.redactText)(url) : url) : [],
+    };
+}
+function taskSummary(rowOrRuntime) {
+    const row = rowOrRuntime;
+    const spec = row.spec;
+    const runtime = (row.runtime ?? (!row.spec ? rowOrRuntime : undefined));
+    return {
+        taskId: spec?.id ?? runtime?.taskId,
+        projectId: spec?.projectId ?? runtime?.projectId,
+        projectPath: spec?.projectRoot,
+        scriptName: spec?.name ?? runtime?.name,
+        status: runtime?.status ?? "idle",
+        pid: runtime?.pid,
+        startTime: runtime?.startedAt,
+        runtime: runtimeSummary(runtime),
+        ports: portSummary(runtime),
+    };
+}
+function latestTimestamp(runtime) {
+    const values = [runtime?.lastOutputAt, runtime?.stoppedAt, runtime?.startedAt].filter((item) => typeof item === "number");
+    return values.length ? Math.max(...values) : undefined;
+}
+async function taskStatus(context, taskId) {
+    const localServer = context.services.localServer;
+    const availability = await localServerAvailability(context);
+    if (availability.available && localServer) {
+        return { runtime: await localServer.getTaskStatus(taskId), controlPlane: "local-server", localServer: availability };
+    }
+    return { runtime: null, controlPlane: "unavailable", localServer: availability };
+}
+async function listProjectRows(context, projectId, availability) {
+    const localServer = context.services.localServer;
+    if (availability.available && localServer) {
+        return { rows: await localServer.listTaskViews(projectId), controlPlane: "local-server" };
+    }
+    return { rows: [], controlPlane: "unavailable" };
+}
+async function activeTasks(context, availability) {
+    const localServer = context.services.localServer;
+    if (availability.available && localServer) {
+        return { tasks: await localServer.listActiveTasks(), controlPlane: "local-server" };
+    }
+    return { tasks: [], controlPlane: "unavailable" };
+}
+function fitLogLines(lines, maxChars) {
+    const redacted = (0, observe_redaction_1.redactValue)(lines);
+    const selected = [];
+    let used = 0;
+    for (let i = redacted.length - 1; i >= 0; i--) {
+        let item = redacted[i];
+        const remaining = maxChars - used;
+        if (remaining <= 0)
+            break;
+        const length = JSON.stringify(item).length;
+        if (length > remaining) {
+            if (selected.length === 0) {
+                item = truncateLogItem(item, remaining);
+                selected.unshift(item);
+                used += JSON.stringify(item).length;
+            }
+            break;
+        }
+        if (selected.length > 0 && used + length > maxChars)
+            break;
+        selected.unshift(item);
+        used += length;
+    }
+    return { lines: selected, returned: selected.length, omitted: Math.max(0, redacted.length - selected.length), maxChars };
+}
+function truncateLogItem(item, maxChars) {
+    const budget = Math.max(0, maxChars - 80);
+    if (typeof item === "string")
+        return `${item.slice(0, budget)}...[truncated]`;
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+        const record = item;
+        if (typeof record.text === "string")
+            return { ...record, text: `${record.text.slice(0, budget)}...[truncated]`, truncated: true };
+    }
+    return { text: `${JSON.stringify(item).slice(0, budget)}...[truncated]`, truncated: true };
+}

package/lib/tools/project/project-control.tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolDefinition } from "../index";
+export declare function projectControlTools(): McpToolDefinition[];

package/lib/tools/project/project-control.tools.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectControlTools = projectControlTools;
+const operation_result_1 = require("../controlled/operation-result");
+const workspace_tools_1 = require("../workspace.tools");
+const operation_policy_1 = require("../controlled/operation-policy");
+const local_server_1 = require("../controlled/local-server");
+const result_1 = require("../../utils/result");
+const schemas_1 = require("../controlled/schemas");
+const runtime_config_1 = require("./runtime-config");
+const launch_status_1 = require("./launch-status");
+const project_resolver_service_1 = require("../../services/project-resolver.service");
+const error_codes_1 = require("../../errors/error-codes");
+async function findScriptTaskViaServer(context, projectId, script) {
+    const { server, availability } = await (0, local_server_1.requireLocalServer)(context);
+    if (!server) {
+        return { availability, row: undefined };
+    }
+    const rows = await server.refreshTaskProject(projectId);
+    return {
+        availability,
+        row: rows.find((row) => row?.spec?.name === script),
+    };
+}
+async function findStopCandidates(context, args) {
+    const serverCheck = await (0, local_server_1.requireLocalServer)(context);
+    if (serverCheck.server) {
+        if (args.taskId) {
+            try {
+                const runtime = await serverCheck.server.getTaskStatus(args.taskId);
+                return {
+                    candidates: (0, launch_status_1.runtimeStatus)(runtime) === "running" || (0, launch_status_1.runtimeStatus)(runtime) === "stopping"
+                        ? [{ taskId: args.taskId, runtime }]
+                        : [],
+                    controlPlane: "local-server",
+                    localServer: serverCheck.availability,
+                };
+            }
+            catch {
+                return { candidates: [], controlPlane: "local-server", localServer: serverCheck.availability };
+            }
+        }
+        if (args.projectId) {
+            const project = await projectResolver(context).resolveProject(args.projectId);
+            const rows = await serverCheck.server.listTaskViews(project.id);
+            return {
+                candidates: rows
+                    .filter((row) => (0, launch_status_1.runtimeStatus)(row?.runtime) === "running" || (0, launch_status_1.runtimeStatus)(row?.runtime) === "stopping")
+                    .filter((row) => !args.script || row?.spec?.name === args.script)
+                    .map((row) => ({ taskId: row.spec.id, spec: row.spec, runtime: row.runtime })),
+                controlPlane: "local-server",
+                localServer: serverCheck.availability,
+            };
+        }
+        return {
+            candidates: (await serverCheck.server.listActiveTasks()).map((runtime) => ({ taskId: runtime.taskId, runtime })),
+            controlPlane: "local-server",
+            localServer: serverCheck.availability,
+        };
+    }
+    return {
+        candidates: [],
+        controlPlane: "unavailable",
+        localServer: serverCheck.availability,
+    };
+}
+function hasStopLocator(args) {
+    return Boolean(args.taskId || args.projectId);
+}
+function projectResolver(context) {
+    return context.services.projectResolver ?? new project_resolver_service_1.ProjectResolverService(context.services.core.project);
+}
+function runScriptTool() {
+    return {
+        name: "ngm_project_run_script",
+        description: "Skill ngm-project. Controlled execute tool for running an existing package.json script for a registered ng-manager projectId through the local ng-manager server task runtime. Prefer this over direct shell npm/pnpm/yarn commands so UI, CLI, desktop, WebSocket logs, and audit stay in sync. Previews by default; real execution requires confirm=true and NGM_MCP_ALLOW_EXECUTE=true. It never accepts arbitrary cwd, workspaceRoot, absolute paths, or shell commands.",
+        riskLevel: "execute",
+        allowPreviewWhenBlocked: true,
+        deferPolicyToHandler: true,
+        isConfirmed: operation_result_1.isConfirmed,
+        inputSchema: schemas_1.runScriptSchema,
+        async handler(args, context) {
+            const confirmed = (0, operation_result_1.isConfirmed)(args);
+            if (confirmed) {
+                const policyBlock = (0, operation_policy_1.requireExecutePolicy)("execute", "medium", `Run package.json script "${args.script}" for registered project "${args.projectId}".`);
+                if (policyBlock)
+                    return (0, result_1.ok)("ngm_project_run_script", { ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")), ...policyBlock });
+            }
+            const project = await projectResolver(context).resolveProject(args.projectId);
+            const safetyMessage = `Run package.json script "${args.script}" for managed project "${project.name}".`;
+            const packageJson = await (0, workspace_tools_1.readWorkspacePackageJson)(project.root, project.root);
+            const scriptCommand = packageJson.scripts[args.script];
+            if (!scriptCommand) {
+                return (0, result_1.ok)("ngm_project_run_script", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "script not found in package.json", {
+                    project: { id: project.id, name: project.name, path: project.root },
+                    availableScripts: Object.keys(packageJson.scripts),
+                }));
+            }
+            const packageManager = (0, runtime_config_1.normalizePackageManager)(project.packageManager);
+            const requestedRuntime = (0, runtime_config_1.runtimeConfigForProject)(project);
+            const resolvedRuntime = await context.services.core.nodeRuntime.resolveRuntime(requestedRuntime);
+            const preview = {
+                ...(0, operation_result_1.controlledFields)("execute", confirmed, (0, operation_policy_1.requiredEnv)("execute")),
+                operation: (0, operation_result_1.operation)("preview", "execute", "medium", safetyMessage),
+                project: { id: project.id, name: project.name, path: project.root },
+                script: { name: args.script, command: scriptCommand },
+                packageManager,
+                requestedRuntime,
+                resolvedRuntime,
+                logHint: "Use ngm_log_tail with taskId or runId after execution.",
+            };
+            if (!confirmed)
+                return (0, result_1.ok)("ngm_project_run_script", preview);
+            const serverCheck = await (0, local_server_1.requireLocalServer)(context);
+            if (!serverCheck.server) {
+                return (0, result_1.ok)("ngm_project_run_script", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "local ng-manager server is unavailable; start ng-manager UI/server before executing managed project scripts", {
+                    ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")),
+                    localServer: serverCheck.availability,
+                    project: { id: project.id, name: project.name, path: project.root },
+                    script: args.script,
+                }, error_codes_1.McpErrorCodes.LOCAL_SERVER_UNAVAILABLE));
+            }
+            await serverCheck.server.refreshProjectScripts(project.id);
+            const { row } = await findScriptTaskViaServer(context, project.id, args.script);
+            if (!row?.spec?.runnable) {
+                return (0, result_1.ok)("ngm_project_run_script", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "managed task spec was not runnable", {
+                    project: { id: project.id, name: project.name, path: project.root },
+                    script: args.script,
+                }));
+            }
+            let runtime;
+            try {
+                runtime = await serverCheck.server.startTask(row.spec.id);
+            }
+            catch (error) {
+                return (0, result_1.ok)("ngm_project_run_script", {
+                    ...preview,
+                    ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")),
+                    operation: (0, operation_result_1.operation)("failed", "execute", "medium", safetyMessage),
+                    task: row.spec,
+                    taskId: row.spec.id,
+                    controlPlane: "local-server",
+                    localServer: serverCheck.availability,
+                    result: { status: "failed", reason: error instanceof Error ? error.message : String(error) },
+                });
+            }
+            const launch = await (0, launch_status_1.observeLaunch)(context, row.spec.id, runtime, args.waitMs ?? 3000);
+            const runId = (0, launch_status_1.runtimeRunId)(launch.runtime) ?? (0, launch_status_1.runtimeRunId)(runtime);
+            return (0, result_1.ok)("ngm_project_run_script", {
+                ...preview,
+                ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")),
+                operation: (0, operation_result_1.operation)("executed", "execute", "medium", safetyMessage),
+                controlPlane: "local-server",
+                localServer: serverCheck.availability,
+                task: row.spec,
+                taskId: row.spec.id,
+                runtime,
+                launch,
+                logHint: `Use ngm_log_tail with taskId=${row.spec.id}${runId ? ` or runId=${runId}` : ""}.`,
+            });
+        },
+    };
+}
+function stopProjectTool() {
+    return {
+        name: "ngm_project_stop",
+        description: "Skill ngm-project. Controlled execute tool for stopping ng-manager managed tasks by taskId or registered projectId via the local ng-manager server runtime. Prefer this over kill/taskkill so shared task state, WebSocket logs, and audit stay consistent. Previews by default; real stop requires confirm=true and NGM_MCP_ALLOW_EXECUTE=true. It never kills arbitrary PIDs or unmanaged processes.",
+        riskLevel: "execute",
+        allowPreviewWhenBlocked: true,
+        deferPolicyToHandler: true,
+        isConfirmed: operation_result_1.isConfirmed,
+        inputSchema: schemas_1.stopProjectSchema,
+        async handler(args, context) {
+            const confirmed = (0, operation_result_1.isConfirmed)(args);
+            const safetyMessage = "Stop one ng-manager managed task process.";
+            if (args.script && !args.projectId) {
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "script stop requires projectId so MCP can resolve a registered ng-manager project", {
+                    ...(0, operation_result_1.controlledFields)("execute", confirmed, (0, operation_policy_1.requiredEnv)("execute")),
+                }, error_codes_1.McpErrorCodes.TOOL_INPUT_INVALID));
+            }
+            if (confirmed && !hasStopLocator(args)) {
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "confirmed stop requires taskId or projectId; MCP will not stop the only active task by inference", {
+                    ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")),
+                }, error_codes_1.McpErrorCodes.CONFIRM_REQUIRED));
+            }
+            if (confirmed) {
+                const policyBlock = (0, operation_policy_1.requireExecutePolicy)("execute", "medium", safetyMessage);
+                if (policyBlock)
+                    return (0, result_1.ok)("ngm_project_stop", { ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")), ...policyBlock });
+            }
+            const { candidates, controlPlane, localServer } = await findStopCandidates(context, args);
+            if (controlPlane === "unavailable") {
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "ng-manager local server is unavailable; start ngm server or ngm ui before stopping managed tasks", {
+                    ...(0, operation_result_1.controlledFields)("execute", confirmed, (0, operation_policy_1.requiredEnv)("execute")),
+                    localServer,
+                }, error_codes_1.McpErrorCodes.LOCAL_SERVER_UNAVAILABLE));
+            }
+            if (candidates.length === 0)
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "no managed running task matched the request"));
+            if (candidates.length > 1)
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "multiple managed tasks matched; pass taskId or script", { candidates }));
+            const candidate = candidates[0];
+            const preview = { ...(0, operation_result_1.controlledFields)("execute", confirmed, (0, operation_policy_1.requiredEnv)("execute")), operation: (0, operation_result_1.operation)("preview", "execute", "medium", safetyMessage), controlPlane, localServer, target: candidate, taskId: candidate.taskId };
+            if (!confirmed)
+                return (0, result_1.ok)("ngm_project_stop", preview);
+            const server = context.services.localServer;
+            if (!server)
+                return (0, result_1.ok)("ngm_project_stop", (0, operation_result_1.blocked)("execute", "medium", safetyMessage, "local server client is not configured"));
+            const runtime = await server.stopTask(candidate.taskId);
+            return (0, result_1.ok)("ngm_project_stop", { ...preview, ...(0, operation_result_1.controlledFields)("execute", true, (0, operation_policy_1.requiredEnv)("execute")), operation: (0, operation_result_1.operation)("executed", "execute", "medium", safetyMessage), runtime, launch: { status: (0, launch_status_1.runtimeStatus)(runtime) } });
+        },
+    };
+}
+function projectControlTools() {
+    return [runScriptTool(), stopProjectTool()];
+}

package/lib/tools/project/project-observe.tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolDefinition } from "../index";
+export declare function projectObserveTools(): McpToolDefinition[];

package/lib/tools/project/project-observe.tools.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectObserveTools = projectObserveTools;
+const zod_1 = require("zod");
+const project_tools_1 = require("../project.tools");
+const result_1 = require("../../utils/result");
+const local_diagnostics_1 = require("./local-diagnostics");
+const observe_redaction_1 = require("./observe-redaction");
+const observe_runtime_1 = require("./observe-runtime");
+const taskListSchema = zod_1.z.object({
+    projectId: zod_1.z.string().trim().min(1).optional(),
+    activeOnly: zod_1.z.boolean().optional(),
+}).strict();
+const taskStatusSchema = zod_1.z.object({
+    taskId: zod_1.z.string().trim().min(1),
+}).strict();
+const taskLogsSchema = zod_1.z.object({
+    taskId: zod_1.z.string().trim().min(1).optional(),
+    runId: zod_1.z.string().trim().min(1).optional(),
+    tail: zod_1.z.number().int().min(1).max(200).optional(),
+    maxChars: zod_1.z.number().int().min(200).max(20000).optional(),
+}).strict();
+const portCheckSchema = zod_1.z.object({
+    host: zod_1.z.string().trim().min(1).max(253).optional(),
+    port: zod_1.z.number().int().min(1).max(65535),
+    timeoutMs: zod_1.z.number().int().min(50).max(3000).optional(),
+}).strict();
+const healthCheckSchema = zod_1.z.object({
+    projectId: zod_1.z.string().trim().min(1).optional(),
+    taskId: zod_1.z.string().trim().min(1).optional(),
+    url: zod_1.z.string().trim().min(1).optional(),
+    method: zod_1.z.enum(["GET", "HEAD"]).optional(),
+    timeoutMs: zod_1.z.number().int().min(100).max(5000).optional(),
+    headers: zod_1.z.record(zod_1.z.string()).optional(),
+    includeBodyPreview: zod_1.z.boolean().optional(),
+}).strict();
+async function deriveHealthUrl(context, args) {
+    if (args.url)
+        return { url: args.url };
+    if (args.taskId) {
+        const status = await (0, observe_runtime_1.taskStatus)(context, args.taskId);
+        const urls = Array.isArray(status.runtime?.urls) ? status.runtime?.urls.filter((item) => typeof item === "string") : [];
+        return urls[0] ? { url: urls[0], runtime: status.runtime } : { reason: "task runtime has no detected URL", runtime: status.runtime };
+    }
+    if (args.projectId) {
+        const project = await (0, project_tools_1.resolveProject)(context, args);
+        const availability = await (0, observe_runtime_1.localServerAvailability)(context);
+        const { rows } = await (0, observe_runtime_1.listProjectRows)(context, project.id, availability);
+        const row = rows.find((item) => item.runtime?.status === "running" && Array.isArray(item.runtime?.urls) && item.runtime.urls.length > 0);
+        const url = row?.runtime?.urls?.find((item) => typeof item === "string");
+        return url ? { url, runtime: row?.runtime } : { reason: "project has no running task with detected URL" };
+    }
+    return { reason: "url, taskId, or projectId is required" };
+}
+function listTasksTool() {
+    return {
+        name: "ngm_project_list_tasks",
+        description: "Skill ngm-project. Read-only diagnostic tool that lists ng-manager managed project tasks from the local server control plane when available. It does not execute scripts, stop processes, or inspect unmanaged system processes.",
+        riskLevel: "read",
+        inputSchema: taskListSchema,
+        async handler(args, context) {
+            const availability = await (0, observe_runtime_1.localServerAvailability)(context);
+            if (!availability.available) {
+                return (0, result_1.ok)("ngm_project_list_tasks", { controlPlane: "unavailable", localServer: availability, status: "unavailable", reason: "ng-manager local server is not running; start it with ngm server or ngm ui to inspect managed task state", taskGroups: [] });
+            }
+            if (args.activeOnly && !args.projectId) {
+                const { tasks, controlPlane } = await (0, observe_runtime_1.activeTasks)(context, availability);
+                return (0, result_1.ok)("ngm_project_list_tasks", { controlPlane, localServer: availability, activeOnly: true, tasks: tasks.map(observe_runtime_1.taskSummary) });
+            }
+            const projects = args.projectId ? [await (0, project_tools_1.resolveProject)(context, args)] : await context.services.core.project.list();
+            const taskGroups = [];
+            for (const project of projects) {
+                const { rows, controlPlane } = await (0, observe_runtime_1.listProjectRows)(context, project.id, availability);
+                const tasks = rows.map(observe_runtime_1.taskSummary).filter((task) => !args.activeOnly || task.status === "running" || task.status === "stopping");
+                taskGroups.push({ project: { id: project.id, name: project.name, root: project.root }, controlPlane, tasks });
+            }
+            return (0, result_1.ok)("ngm_project_list_tasks", { localServer: availability, activeOnly: args.activeOnly === true, taskGroups });
+        },
+    };
+}
+function taskStatusTool() {
+    return {
+        name: "ngm_project_task_status",
+        description: "Skill ngm-project. Read-only diagnostic tool that returns structured status for one ng-manager managed task, including runtime status, pid existence, exit code, recent update time, and error summary.",
+        riskLevel: "read",
+        inputSchema: taskStatusSchema,
+        async handler(args, context) {
+            const status = await (0, observe_runtime_1.taskStatus)(context, args.taskId);
+            const runtime = status.runtime;
+            if (!runtime) {
+                return (0, result_1.ok)("ngm_project_task_status", { controlPlane: status.controlPlane, localServer: status.localServer, taskId: args.taskId, status: "unavailable", running: false, pidExists: null, reason: "ng-manager local server is not running or the task is not available from the shared server runtime" });
+            }
+            return (0, result_1.ok)("ngm_project_task_status", {
+                controlPlane: status.controlPlane,
+                localServer: status.localServer,
+                taskId: args.taskId,
+                running: runtime?.status === "running",
+                pidExists: (0, observe_runtime_1.runtimeSummary)(runtime)?.pidExists ?? null,
+                status: runtime?.status ?? "unknown",
+                exitCode: runtime?.exitCode,
+                signal: runtime?.signal,
+                updatedAt: (0, observe_runtime_1.latestTimestamp)(runtime ?? undefined),
+                errorSummary: typeof runtime?.lastError === "string" ? (0, observe_redaction_1.redactText)(runtime.lastError) : undefined,
+                runtime: (0, observe_runtime_1.runtimeSummary)(runtime ?? undefined),
+            });
+        },
+    };
+}
+function taskLogsTool() {
+    return {
+        name: "ngm_project_task_logs",
+        description: "Skill ngm-project. Read-only diagnostic tool that reads a limited tail of logs for one ng-manager managed task/run. It enforces line and character limits and redacts token/password/secret/authorization-like values.",
+        riskLevel: "read",
+        inputSchema: taskLogsSchema,
+        async handler(args, context) {
+            const tail = args.tail ?? 50;
+            const maxChars = args.maxChars ?? 8000;
+            const availability = await (0, observe_runtime_1.localServerAvailability)(context);
+            let runId = args.runId;
+            if (!runId && args.taskId) {
+                const status = await (0, observe_runtime_1.taskStatus)(context, args.taskId);
+                if (!status.runtime)
+                    return (0, result_1.ok)("ngm_project_task_logs", { controlPlane: status.controlPlane, localServer: status.localServer, status: "unavailable", reason: "ng-manager local server is not running or the task has no shared runtime state", taskId: args.taskId, tail, maxChars, lines: [] });
+                runId = status.runtime?.runId;
+            }
+            if (!runId)
+                return (0, result_1.ok)("ngm_project_task_logs", { controlPlane: availability.available ? "local-server" : "unavailable", localServer: availability, status: "unavailable", reason: "runId could not be resolved from the provided taskId", taskId: args.taskId, tail, maxChars, lines: [] });
+            const localServer = context.services.localServer;
+            if (!availability.available || !localServer)
+                return (0, result_1.ok)("ngm_project_task_logs", { controlPlane: "unavailable", localServer: availability, status: "unavailable", reason: "ng-manager local server is not running; start it with ngm server or ngm ui to read shared task logs", taskId: args.taskId, runId, tail, maxChars, lines: [] });
+            const fitted = (0, observe_runtime_1.fitLogLines)(await localServer.getTaskLogTail(runId, tail), maxChars);
+            return (0, result_1.ok)("ngm_project_task_logs", { controlPlane: "local-server", localServer: availability, status: fitted.lines.length > 0 ? "ok" : "empty", reason: fitted.lines.length > 0 ? undefined : "no task log lines were found for this run", taskId: args.taskId, runId, tail, ...fitted });
+        },
+    };
+}
+function portCheckTool() {
+    return {
+        name: "ngm_project_port_check",
+        description: "Skill ngm-project. Read-only diagnostic tool that checks one local host/port for TCP listening state without running shell commands, killing processes, occupying the port, or scanning ranges.",
+        riskLevel: "read",
+        inputSchema: portCheckSchema,
+        async handler(args) {
+            const host = args.host ?? "127.0.0.1";
+            const timeoutMs = args.timeoutMs ?? 800;
+            const normalized = (0, local_diagnostics_1.normalizeLocalHost)(host);
+            if (!normalized.allowed)
+                return (0, result_1.ok)("ngm_project_port_check", { host, port: args.port, timeoutMs, status: "blocked", reason: normalized.reason });
+            return (0, result_1.ok)("ngm_project_port_check", { host, checkedHost: normalized.connectHost, port: args.port, timeoutMs, ...(await (0, local_diagnostics_1.portCheck)(normalized.connectHost, args.port, timeoutMs)) });
+        },
+    };
+}
+function healthCheckTool() {
+    return {
+        name: "ngm_project_health_check",
+        description: "Skill ngm-project. Read-only diagnostic tool that performs a short local HTTP health check by URL or by URL detected from a managed project/task runtime. It uses GET by default, does not send request bodies, redacts sensitive headers, and returns only a small optional body preview.",
+        riskLevel: "read",
+        inputSchema: healthCheckSchema,
+        async handler(args, context) {
+            const timeoutMs = args.timeoutMs ?? 1500;
+            const method = args.method ?? "GET";
+            const derived = await deriveHealthUrl(context, args);
+            if (!derived.url)
+                return (0, result_1.ok)("ngm_project_health_check", { status: "unavailable", reachable: false, reason: derived.reason, runtime: (0, observe_runtime_1.runtimeSummary)(derived.runtime ?? undefined) });
+            let url;
+            try {
+                url = new URL(derived.url);
+            }
+            catch {
+                return (0, result_1.ok)("ngm_project_health_check", { status: "unavailable", reachable: false, reason: "invalid URL", url: (0, observe_redaction_1.redactText)(derived.url) });
+            }
+            const normalizedUrl = (0, local_diagnostics_1.normalizeLocalUrl)(url);
+            if ((url.protocol !== "http:" && url.protocol !== "https:") || !normalizedUrl.allowed) {
+                return (0, result_1.ok)("ngm_project_health_check", { status: "blocked", reachable: false, reason: "health_check only supports local http/https URLs", url: (0, observe_redaction_1.redactText)(derived.url) });
+            }
+            const startedAt = Date.now();
+            const requestHeaders = (0, local_diagnostics_1.redactHeaders)(args.headers);
+            try {
+                const response = await (0, local_diagnostics_1.fetchWithTimeout)(normalizedUrl.url.toString(), { method, headers: args.headers }, timeoutMs);
+                const responseTimeMs = Date.now() - startedAt;
+                const bodyPreview = args.includeBodyPreview ? await (0, local_diagnostics_1.readBodyPreview)(response, 500) : undefined;
+                return (0, result_1.ok)("ngm_project_health_check", { status: "ok", reachable: true, url: (0, observe_redaction_1.redactText)(url.toString()), checkedUrl: (0, observe_redaction_1.redactText)(normalizedUrl.url.toString()), method, timeoutMs, statusCode: response.status, responseTimeMs, requestHeaders, responseHeaders: (0, local_diagnostics_1.headersObject)(response.headers), bodyPreview, runtime: (0, observe_runtime_1.runtimeSummary)(derived.runtime ?? undefined) });
+            }
+            catch (error) {
+                return (0, result_1.ok)("ngm_project_health_check", { status: "unavailable", reachable: false, url: (0, observe_redaction_1.redactText)(url.toString()), checkedUrl: (0, observe_redaction_1.redactText)(normalizedUrl.url.toString()), method, timeoutMs, responseTimeMs: Date.now() - startedAt, requestHeaders, error: error?.name === "AbortError" ? "timeout" : (0, observe_redaction_1.redactText)(error?.message ?? String(error)), runtime: (0, observe_runtime_1.runtimeSummary)(derived.runtime ?? undefined) });
+            }
+        },
+    };
+}
+function projectObserveTools() {
+    return [listTasksTool(), taskStatusTool(), taskLogsTool(), portCheckTool(), healthCheckTool()];
+}

package/lib/tools/project/runtime-config.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectNodeRuntimeConfig } from "@yinuo-ngm/project";
+import type { RuntimeConfigArgs } from "../controlled/schemas";
+import type { resolveProject } from "../project.tools";
+export declare function normalizePackageManager(value: unknown): "npm" | "pnpm" | "yarn";
+export declare function toRuntimeConfig(input: RuntimeConfigArgs): ProjectNodeRuntimeConfig;
+export declare function runtimeConfigForProject(project: Awaited<ReturnType<typeof resolveProject>>): ProjectNodeRuntimeConfig;
+export declare function validateTargetRuntime(runtime: ProjectNodeRuntimeConfig): void;

package/lib/tools/project/runtime-config.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePackageManager = normalizePackageManager;
+exports.toRuntimeConfig = toRuntimeConfig;
+exports.runtimeConfigForProject = runtimeConfigForProject;
+exports.validateTargetRuntime = validateTargetRuntime;
+function normalizePackageManager(value) {
+    return value === "pnpm" || value === "yarn" ? value : "npm";
+}
+function toRuntimeConfig(input) {
+    const config = {
+        type: input.type,
+    };
+    if (input.name !== undefined)
+        config.name = input.name;
+    if (input.version !== undefined)
+        config.version = input.version;
+    if (input.nodePath !== undefined)
+        config.nodePath = input.nodePath;
+    if (input.packageManager !== undefined)
+        config.packageManager = input.packageManager;
+    return config;
+}
+function runtimeConfigForProject(project) {
+    if (project.runtime) {
+        return {
+            ...project.runtime,
+            packageManager: normalizePackageManager(project.runtime.packageManager ?? project.packageManager),
+        };
+    }
+    if (project.nodeVersion) {
+        return {
+            type: "managed",
+            version: project.nodeVersion,
+            packageManager: normalizePackageManager(project.packageManager),
+        };
+    }
+    return {
+        type: "system",
+        packageManager: normalizePackageManager(project.packageManager),
+    };
+}
+function validateTargetRuntime(runtime) {
+    if (runtime.type === "managed" && !runtime.name && !runtime.version) {
+        throw new Error("managed runtime requires name or version");
+    }
+    if (runtime.type === "custom" && !runtime.nodePath) {
+        throw new Error("custom runtime requires nodePath");
+    }
+}

package/lib/tools/project-observe.tools.d.ts

@@ -0,0 +1 @@
+export { projectObserveTools } from "./project/project-observe.tools";

package/lib/tools/project-observe.tools.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectObserveTools = void 0;
+var project_observe_tools_1 = require("./project/project-observe.tools");
+Object.defineProperty(exports, "projectObserveTools", { enumerable: true, get: function () { return project_observe_tools_1.projectObserveTools; } });

package/lib/tools/project.tools.d.ts

@@ -13,6 +13,14 @@ export declare const projectLocatorSchema: z.ZodObject<{
     projectPath?: string | undefined;
 }>;
 type ProjectLocator = z.infer<typeof projectLocatorSchema>;
+export interface McpProjectItem {
+    id: string;
+    name: string;
+    path: string;
+    framework?: string;
+    favorite?: boolean;
+    scripts: string[];
+}
 export declare function resolveProject(context: ToolContext, locator: ProjectLocator): Promise<Project>;
 export declare function projectTools(): McpToolDefinition[];
 export {};