@yinuo-ngm/mcp-server 0.1.2 → 0.1.4

package/lib/tools/nginx/nginx-proxy.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeProxyRequest = normalizeProxyRequest;
+exports.sanitizeNginxServerForAgent = sanitizeNginxServerForAgent;
+exports.sanitizeNginxProxyRequestForAgent = sanitizeNginxProxyRequestForAgent;
+exports.rollbackNginxProxySave = rollbackNginxProxySave;
+function validateProxyTarget(target) {
+    if (/[\r\n;{}]/.test(target) || target.includes("`") || target.includes("$(")) {
+        throw new Error("target contains unsafe characters");
+    }
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new Error("target must be a valid URL");
+    }
+    const allowed = new Set(["http:", "https:", "ws:", "wss:"]);
+    if (!allowed.has(url.protocol))
+        throw new Error("target protocol must be http, https, ws, or wss");
+    if (!url.hostname)
+        throw new Error("target hostname is required");
+    return url;
+}
+function assertSafeNginxToken(label, value) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${label} cannot be empty`);
+    if (normalized !== value || /[\r\n;{}]/.test(normalized) || normalized.includes("`") || normalized.includes("$(") || normalized.includes("${")) {
+        throw new Error(`${label} contains unsafe Nginx control characters`);
+    }
+    return normalized;
+}
+function validatePortText(label, value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${label} must use a port between 1 and 65535`);
+    }
+}
+function validateListenValue(value) {
+    const listen = assertSafeNginxToken("listen", value);
+    if (/\s/.test(listen))
+        throw new Error("listen must be a port or host:port without whitespace");
+    if (/^\d{1,5}$/.test(listen)) {
+        validatePortText("listen", listen);
+        return listen;
+    }
+    const hostPort = listen.match(/^(localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[[0-9a-fA-F:.]+\]|[A-Za-z0-9.-]+):(\d{1,5})$/);
+    if (!hostPort)
+        throw new Error("listen must be a port or host:port");
+    validatePortText("listen", hostPort[2]);
+    return listen;
+}
+function validateDomainValue(value) {
+    const domain = assertSafeNginxToken("domain", value);
+    if (/[\s/\\]/.test(domain))
+        throw new Error("domain must not contain whitespace or path separators");
+    return domain;
+}
+function validateLocationPath(value) {
+    const locationPath = assertSafeNginxToken("locationPath", value);
+    if (!locationPath.startsWith("/"))
+        throw new Error("locationPath must start with /");
+    if (/\s/.test(locationPath))
+        throw new Error("locationPath must not contain whitespace");
+    return locationPath;
+}
+function normalizeProxyRequest(args, existing) {
+    const target = validateProxyTarget(args.target).toString();
+    const domains = args.domains ?? existing?.domains;
+    const listen = args.listen ?? existing?.listen;
+    const name = args.name ?? existing?.name ?? domains?.[0];
+    if (!name)
+        throw new Error("name is required when creating a new proxy server");
+    if (!domains?.length)
+        throw new Error("domains is required when creating a new proxy server");
+    if (!listen?.length)
+        throw new Error("listen is required when creating a new proxy server");
+    return {
+        name,
+        listen: listen.map((item) => validateListenValue(item)),
+        domains: domains.map((item) => validateDomainValue(item)),
+        enabled: args.enabled ?? existing?.enabled ?? true,
+        protocol: existing?.ssl ? "https" : "http",
+        ssl: existing?.ssl ?? false,
+        sslCert: existing?.sslCert,
+        sslKey: existing?.sslKey,
+        root: existing?.root,
+        index: existing?.index,
+        extraConfig: existing?.extraConfig,
+        locations: [{ path: validateLocationPath(args.locationPath ?? "/"), proxyPass: target }],
+        createdBy: existing?.createdBy ?? "ngm-mcp",
+    };
+}
+function sanitizeNginxServerForAgent(server) {
+    if (!server)
+        return server;
+    return {
+        id: server.id,
+        name: server.name,
+        listen: server.listen,
+        domains: server.domains,
+        enabled: server.enabled,
+        ssl: Boolean(server.ssl),
+        locations: Array.isArray(server.locations)
+            ? server.locations.map((item) => ({
+                path: item?.path,
+                proxyPass: item?.proxyPass,
+            }))
+            : undefined,
+        sslCert: server.sslCert ? "[REDACTED_PATH]" : undefined,
+        sslKey: server.sslKey ? "[REDACTED_PATH]" : undefined,
+        extraConfig: server.extraConfig ? "[REDACTED]" : undefined,
+    };
+}
+function sanitizeNginxProxyRequestForAgent(request) {
+    return sanitizeNginxServerForAgent({
+        ...request,
+        id: undefined,
+    });
+}
+async function rollbackNginxProxySave(context, mode, serverId, saved, existing) {
+    const nginx = context.services.core.nginx;
+    try {
+        if (mode === "create") {
+            const savedId = typeof saved?.id === "string" ? saved.id : undefined;
+            if (!savedId)
+                return { status: "not_possible", reason: "created server id was not returned" };
+            const result = await nginx.server.deleteServer(savedId);
+            const validation = await nginx.config.validateConfig();
+            return {
+                status: validation.valid ? "rolled_back" : "failed",
+                action: "delete-created-server",
+                result,
+                validation,
+                ...(validation.valid ? {} : { reason: "Nginx config is still invalid after rollback" }),
+            };
+        }
+        if (!serverId || !existing)
+            return { status: "not_possible", reason: "original server snapshot is unavailable" };
+        const restored = await nginx.server.updateServer(serverId, existing);
+        const validation = await nginx.config.validateConfig();
+        return {
+            status: validation.valid ? "rolled_back" : "failed",
+            action: "restore-previous-server",
+            server: sanitizeNginxServerForAgent(restored),
+            validation,
+            ...(validation.valid ? {} : { reason: "Nginx config is still invalid after rollback" }),
+        };
+    }
+    catch (error) {
+        return { status: "failed", reason: error instanceof Error ? error.message : String(error) };
+    }
+}

package/lib/tools/nginx.tools.d.ts

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

package/lib/tools/nginx.tools.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nginxTools = nginxTools;
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+const nginxServerGetSchema = zod_1.z.object({
+    id: zod_1.z.string().trim().min(1),
+}).strict();
+const nginxValidateSchema = zod_1.z.object({
+    configText: zod_1.z.string().optional(),
+}).strict();
+const nginxLogsTailSchema = zod_1.z.object({
+    type: zod_1.z.enum(["access", "error"]).optional(),
+    tail: zod_1.z.number().int().min(1).max(1000).optional(),
+}).strict();
+function clampTail(value) {
+    return Math.min(Math.max(value ?? 100, 1), 1000);
+}
+function nginxTools() {
+    return [
+        {
+            name: "ngm_nginx_status",
+            description: "Read local ng-manager Nginx binding and process status without starting, stopping, or reloading it.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const nginx = context.services.core.nginx;
+                const instance = nginx.service.getInstance();
+                const status = await nginx.service.getStatus().catch((error) => ({
+                    isRunning: false,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+                return (0, result_1.ok)("ngm_nginx_status", {
+                    instance,
+                    status,
+                    lastConfigAppliedAt: nginx.service.getLastConfigAppliedAt(),
+                });
+            },
+        },
+        {
+            name: "ngm_nginx_servers_list",
+            description: "List local ng-manager Nginx server blocks without changing Nginx config.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const servers = await context.services.core.nginx.server.getAllServers();
+                return (0, result_1.ok)("ngm_nginx_servers_list", servers);
+            },
+        },
+        {
+            name: "ngm_nginx_server_get",
+            description: "Get one local ng-manager Nginx server block by id.",
+            riskLevel: "read",
+            inputSchema: nginxServerGetSchema,
+            async handler(args, context) {
+                const server = await context.services.core.nginx.server.getServer(args.id);
+                if (!server) {
+                    throw new Error(`Nginx server not found: ${args.id}`);
+                }
+                return (0, result_1.ok)("ngm_nginx_server_get", server);
+            },
+        },
+        {
+            name: "ngm_nginx_upstreams_list",
+            description: "List local ng-manager Nginx upstream definitions without saving changes.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const upstreams = await context.services.core.nginx.module.getUpstreams();
+                return (0, result_1.ok)("ngm_nginx_upstreams_list", upstreams);
+            },
+        },
+        {
+            name: "ngm_nginx_config_validate",
+            description: "Validate the current or supplied local ng-manager Nginx config without reload.",
+            riskLevel: "read",
+            inputSchema: nginxValidateSchema,
+            async handler(args, context) {
+                const validation = await context.services.core.nginx.config.validateConfig(args.configText);
+                return (0, result_1.ok)("ngm_nginx_config_validate", validation);
+            },
+        },
+        {
+            name: "ngm_nginx_config_get_main",
+            description: "Read local ng-manager Nginx main config metadata and content without writing it.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const config = await context.services.core.nginx.config.readMainConfig();
+                return (0, result_1.ok)("ngm_nginx_config_get_main", config);
+            },
+        },
+        {
+            name: "ngm_nginx_logs_tail",
+            description: "Read recent local ng-manager Nginx access or error log lines.",
+            riskLevel: "read",
+            inputSchema: nginxLogsTailSchema,
+            async handler(args, context) {
+                const type = args.type ?? "error";
+                const tail = clampTail(args.tail);
+                const lines = await context.services.core.nginx.log.readLogTail(type, tail);
+                return (0, result_1.ok)("ngm_nginx_logs_tail", {
+                    type,
+                    tail,
+                    logPath: context.services.core.nginx.log.getLogFilePath(type),
+                    lines,
+                });
+            },
+        },
+    ];
+}

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

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

package/lib/tools/project/index.js

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

package/lib/tools/project/launch-status.d.ts

@@ -0,0 +1,10 @@
+import type { ToolContext } from "../../context/tool-context";
+export type LaunchStatus = "ready" | "running" | "failed" | "success" | "stopped" | "unknown";
+export declare function runtimeStatus(runtime: unknown): string | undefined;
+export declare function runtimeRunId(runtime: unknown): string | undefined;
+export declare function observeLaunch(context: ToolContext, taskId: string, initialRuntime: unknown, waitMs: number): Promise<{
+    status: LaunchStatus;
+    observedForMs: number;
+    message: string;
+    runtime: unknown;
+}>;

package/lib/tools/project/launch-status.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeStatus = runtimeStatus;
+exports.runtimeRunId = runtimeRunId;
+exports.observeLaunch = observeLaunch;
+const local_server_1 = require("../controlled/local-server");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function runtimeStatus(runtime) {
+    return typeof runtime?.status === "string"
+        ? (runtime.status)
+        : undefined;
+}
+function runtimeRunId(runtime) {
+    return typeof runtime?.runId === "string"
+        ? (runtime.runId)
+        : undefined;
+}
+function launchStatusFromRuntime(runtime) {
+    const status = runtimeStatus(runtime);
+    if (status === "failed")
+        return "failed";
+    if (status === "success")
+        return "success";
+    if (status === "stopped")
+        return "stopped";
+    if (status === "running") {
+        return runtime?.readyAt ? "ready" : "running";
+    }
+    return "unknown";
+}
+function launchMessage(status, observedForMs) {
+    switch (status) {
+        case "ready":
+            return "Task is running and emitted a readiness signal.";
+        case "running":
+            return `Task is still running after ${observedForMs}ms; no failure was observed yet.`;
+        case "failed":
+            return "Task failed during the observation window.";
+        case "success":
+            return "Task exited successfully during the observation window.";
+        case "stopped":
+            return "Task stopped during the observation window.";
+        default:
+            return "Task status could not be confirmed.";
+    }
+}
+async function getTaskStatus(context, taskId) {
+    const { server } = await (0, local_server_1.requireLocalServer)(context);
+    if (server)
+        return server.getTaskStatus(taskId);
+    throw new Error("ng-manager local server is unavailable");
+}
+async function observeLaunch(context, taskId, initialRuntime, waitMs) {
+    const start = Date.now();
+    let runtime = initialRuntime;
+    let status = launchStatusFromRuntime(runtime);
+    while (Date.now() - start < waitMs) {
+        if (status !== "running")
+            break;
+        await sleep(Math.min(250, Math.max(waitMs - (Date.now() - start), 0)));
+        try {
+            runtime = await getTaskStatus(context, taskId);
+            status = launchStatusFromRuntime(runtime);
+        }
+        catch {
+            break;
+        }
+    }
+    const observedForMs = Date.now() - start;
+    return {
+        status,
+        observedForMs,
+        message: launchMessage(status, observedForMs),
+        runtime,
+    };
+}

package/lib/tools/project/local-diagnostics.d.ts

@@ -0,0 +1,19 @@
+export declare function portCheck(host: string, port: number, timeoutMs: number): Promise<{
+    status: "listening" | "unavailable" | "unknown";
+    responseTimeMs: number;
+    error?: string;
+}>;
+export declare function normalizeLocalHost(hostname: string): {
+    allowed: boolean;
+    connectHost: string;
+    reason?: string;
+};
+export declare function normalizeLocalUrl(input: URL): {
+    allowed: boolean;
+    url: URL;
+    reason?: string;
+};
+export declare function headersObject(headers: Headers): Record<string, string>;
+export declare function readBodyPreview(response: Response, maxChars: number): Promise<string | undefined>;
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response>;
+export declare function redactHeaders(headers: Record<string, string> | undefined): Record<string, string>;

package/lib/tools/project/local-diagnostics.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.portCheck = portCheck;
+exports.normalizeLocalHost = normalizeLocalHost;
+exports.normalizeLocalUrl = normalizeLocalUrl;
+exports.headersObject = headersObject;
+exports.readBodyPreview = readBodyPreview;
+exports.fetchWithTimeout = fetchWithTimeout;
+exports.redactHeaders = redactHeaders;
+const net_1 = __importDefault(require("net"));
+const observe_redaction_1 = require("./observe-redaction");
+function portCheck(host, port, timeoutMs) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        const socket = new net_1.default.Socket();
+        let settled = false;
+        function finish(status, error) {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve({ status, responseTimeMs: Date.now() - startedAt, ...(error ? { error } : {}) });
+        }
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish("listening"));
+        socket.once("timeout", () => finish("unknown", "timeout"));
+        socket.once("error", (error) => {
+            const code = typeof error?.code === "string" ? error.code : "";
+            finish(code === "ECONNREFUSED" ? "unavailable" : "unknown", code || error?.message || "connect error");
+        });
+        socket.connect(port, host);
+    });
+}
+function normalizeLocalHost(hostname) {
+    const value = hostname.trim().toLowerCase();
+    if (value === "localhost" || value === "127.0.0.1" || value === "::ffff:127.0.0.1")
+        return { allowed: true, connectHost: "127.0.0.1" };
+    if (value === "::1" || value === "[::1]")
+        return { allowed: true, connectHost: "::1" };
+    if (value === "0.0.0.0")
+        return { allowed: true, connectHost: "127.0.0.1" };
+    if (value === "::" || value === "[::]")
+        return { allowed: true, connectHost: "::1" };
+    return { allowed: false, connectHost: hostname, reason: "only localhost, loopback, or wildcard local addresses are allowed" };
+}
+function normalizeLocalUrl(input) {
+    const normalized = normalizeLocalHost(input.hostname);
+    if (!normalized.allowed)
+        return { allowed: false, url: input, reason: normalized.reason };
+    const url = new URL(input.toString());
+    url.hostname = normalized.connectHost;
+    return { allowed: true, url };
+}
+function headersObject(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = observe_redaction_1.SENSITIVE_KEY_RE.test(key) ? "[REDACTED]" : (0, observe_redaction_1.redactText)(value);
+    });
+    return out;
+}
+async function readBodyPreview(response, maxChars) {
+    if (!response.body)
+        return undefined;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    try {
+        while (text.length < maxChars) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            text += decoder.decode(value, { stream: true });
+            if (text.length >= maxChars)
+                break;
+        }
+    }
+    finally {
+        reader.cancel().catch(() => undefined);
+    }
+    return (0, observe_redaction_1.redactText)(text.slice(0, maxChars));
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function redactHeaders(headers) {
+    return (0, observe_redaction_1.redactValue)(headers ?? {});
+}

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

@@ -0,0 +1,3 @@
+export declare const SENSITIVE_KEY_RE: RegExp;
+export declare function redactText(value: string): string;
+export declare function redactValue(value: unknown): unknown;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENSITIVE_KEY_RE = void 0;
+exports.redactText = redactText;
+exports.redactValue = redactValue;
+exports.SENSITIVE_KEY_RE = /(authorization|token|password|passwd|secret|api[-_]?key|access[-_]?token|refresh[-_]?token)/i;
+function redactText(value) {
+    return value
+        .replace(/(authorization\s*[:=]\s*)(bearer\s+)?[^\s,;]+/gi, "$1[REDACTED]")
+        .replace(/((?:token|password|passwd|secret|api[-_]?key|access[-_]?token|refresh[-_]?token)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi, "$1[REDACTED]")
+        .replace(/([?&](?:token|password|passwd|secret|api[-_]?key|access[-_]?token|refresh[-_]?token)=)[^&\s]+/gi, "$1[REDACTED]");
+}
+function redactValue(value) {
+    if (typeof value === "string")
+        return redactText(value);
+    if (Array.isArray(value))
+        return value.map(redactValue);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = exports.SENSITIVE_KEY_RE.test(key) ? "[REDACTED]" : redactValue(item);
+    }
+    return out;
+}

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

@@ -0,0 +1,72 @@
+import type { LocalServerAvailability, ToolContext } from "../../context/tool-context";
+export type TaskRowLike = {
+    spec?: Record<string, any>;
+    runtime?: Record<string, any>;
+};
+export type RuntimeLike = Record<string, any>;
+export declare function localServerAvailability(context: ToolContext): Promise<LocalServerAvailability>;
+export declare function runtimeSummary(runtime?: RuntimeLike): {
+    taskId: any;
+    runId: any;
+    status: any;
+    pid: any;
+    pidExists: boolean | null;
+    startedAt: any;
+    stoppedAt: any;
+    lastOutputAt: any;
+    readyAt: any;
+    exitCode: any;
+    signal: any;
+    lastError: any;
+    urls: any[];
+} | undefined;
+export declare function taskSummary(rowOrRuntime: TaskRowLike | RuntimeLike): {
+    taskId: any;
+    projectId: any;
+    projectPath: any;
+    scriptName: any;
+    status: any;
+    pid: any;
+    startTime: any;
+    runtime: {
+        taskId: any;
+        runId: any;
+        status: any;
+        pid: any;
+        pidExists: boolean | null;
+        startedAt: any;
+        stoppedAt: any;
+        lastOutputAt: any;
+        readyAt: any;
+        exitCode: any;
+        signal: any;
+        lastError: any;
+        urls: any[];
+    } | undefined;
+    ports: ({
+        url: string;
+        host: string;
+        port: number;
+        protocol: string;
+    } | null)[];
+};
+export declare function latestTimestamp(runtime?: RuntimeLike): number | undefined;
+export declare function taskStatus(context: ToolContext, taskId: string): Promise<{
+    runtime: RuntimeLike | null;
+    controlPlane: string;
+    localServer: LocalServerAvailability;
+}>;
+export declare function listProjectRows(context: ToolContext, projectId: string, availability: LocalServerAvailability): Promise<{
+    rows: TaskRowLike[];
+    controlPlane: string;
+}>;
+export declare function activeTasks(context: ToolContext, availability: LocalServerAvailability): Promise<{
+    tasks: RuntimeLike[];
+    controlPlane: string;
+}>;
+export declare function fitLogLines(lines: unknown[], maxChars: number): {
+    lines: unknown[];
+    returned: number;
+    omitted: number;
+    maxChars: number;
+};