devglow-mcp 1.0.4 → 1.1.0

package/build/deeplink.js

@@ -1,4 +1,6 @@
 import { execFile } from "child_process";
+import { randomUUID } from "node:crypto";
+import { getPortInfo } from "./portInfo.js";
 function openDeepLink(url) {
     return new Promise((resolve, reject) => {
         execFile("open", ["-g", url], (error) => {
@@ -12,27 +14,51 @@ function openDeepLink(url) {
     });
 }
 function buildUrl(action, params) {
+    // Note: empty-string values are intentionally preserved (used to clear fields like description/tags)
     const query = Object.entries(params)
-        .filter(([, v]) => v !== undefined && v !== "")
+        .filter(([, v]) => v !== undefined && v !== null)
         .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
         .join("&");
     return `devglow://${action}${query ? "?" + query : ""}`;
 }
+function genId(prefix) {
+    return `${prefix}-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
 export async function startProject(id) {
     await openDeepLink(buildUrl("start", { id }));
 }
 export async function stopProject(id) {
     await openDeepLink(buildUrl("stop", { id }));
 }
+/**
+ * Start a new AI process. Returns the id assigned by MCP — devglow uses the supplied id,
+ * which lets the caller correlate the response with the resulting AiProcess entry.
+ *
+ * If `port` is given and currently occupied, this function looks up the occupier
+ * (PID, command name, and whether it's a devglow-managed project) and forwards
+ * that context via the deeplink so the resulting AI process card can show
+ * "occupied by todoglow" instead of an anonymous warning.
+ */
 export async function runProcess(name, path, command, port, source, description) {
-    const params = { name, path, command };
+    const id = genId("ai");
+    const params = { id, name, path, command };
     if (port !== undefined)
         params.port = String(port);
     if (source)
         params.source = source;
     if (description)
         params.description = description;
+    // Pre-flight port check: if occupied, attach occupier info so the Rust side
+    // can populate AiProcess.port_conflict with a human-readable owner.
+    if (port !== undefined) {
+        const info = await getPortInfo(port);
+        if (info.in_use && info.occupier) {
+            params.port_conflict_pid = String(info.occupier.pid);
+            params.port_conflict_name = info.owned_by_devglow?.project_name ?? info.occupier.name;
+        }
+    }
     await openDeepLink(buildUrl("run", params));
+    return id;
 }
 export async function stopProcess(name) {
     await openDeepLink(buildUrl("stop-process", { name }));
@@ -40,9 +66,42 @@ export async function stopProcess(name) {
 export async function exportLogs(id) {
     await openDeepLink(buildUrl("export-logs", { id }));
 }
-export async function updateProject(id, description) {
+export async function updateProject(id, fields) {
     const params = { id };
-    if (description !== undefined)
-        params.description = description;
+    if (fields.name !== undefined)
+        params.name = fields.name;
+    if (fields.path !== undefined)
+        params.path = fields.path;
+    if (fields.command !== undefined)
+        params.command = fields.command;
+    if (fields.port !== undefined)
+        params.port = fields.port === null ? "" : String(fields.port);
+    if (fields.description !== undefined)
+        params.description = fields.description === null ? "" : fields.description;
+    if (fields.tags !== undefined)
+        params.tags = fields.tags.join(",");
     await openDeepLink(buildUrl("update-project", params));
 }
+/**
+ * Register a permanent project without running it. Returns the id assigned by MCP.
+ */
+export async function createProject(input) {
+    const id = genId("proj");
+    const params = {
+        id,
+        name: input.name,
+        path: input.path,
+        command: input.command,
+    };
+    if (input.port !== undefined)
+        params.port = String(input.port);
+    if (input.description)
+        params.description = input.description;
+    if (input.tags && input.tags.length > 0)
+        params.tags = input.tags.join(",");
+    await openDeepLink(buildUrl("create-project", params));
+    return id;
+}
+export async function deleteProject(id) {
+    await openDeepLink(buildUrl("delete-project", { id }));
+}

package/build/index.js

@@ -11,7 +11,8 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { loadProjects, loadAiProcesses, loadStatuses, loadExportedLogs, } from "./storage.js";
-import { startProject, stopProject, runProcess, stopProcess, exportLogs, updateProject, } from "./deeplink.js";
+import { getPortInfo } from "./portInfo.js";
+import { startProject, stopProject, runProcess, stopProcess, exportLogs, updateProject, createProject, deleteProject, } from "./deeplink.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 // --- Orphan process prevention constants ---
@@ -32,6 +33,12 @@ function createMcpServer() {
             "- If found, use `start_project` (runs the user's registered command as-is).",
             "- Only use `run_process` when no matching project exists.",
             "",
+            "## Before binding a port (run_process / create_project with port)",
+            "- Call `check_port` first. If the port is in use, the response identifies the occupier — including whether it's another devglow-managed project (project_name + project_id).",
+            "- If devglow already runs the occupier: tell the user, and offer to stop it via `stop_project` or to pick a different port. Do not silently kill it.",
+            "- If an external process holds it: tell the user; let them decide. Do not pick an arbitrary 'next port' — respect the user's port conventions (e.g., 5173 → 5174 makes sense for Vite, but 25006 → 25007 may not).",
+            "- If you proceed despite a conflict, `run_process` will register the entry but mark it with `port_conflict` and skip start. The response surfaces this — relay the conflict to the user instead of pretending success.",
+            "",
             "## Reading logs",
             "- `get_logs` triggers a log export from DevGlow, waits briefly, then reads the file.",
             "- If logs are empty, DevGlow may not have finished writing. Try again after a moment.",
@@ -133,16 +140,35 @@ function createMcpServer() {
     // ── Tool: check_port ──
     server.registerTool("check_port", {
         title: "Check port availability",
-        description: "Check if a TCP port is in use on localhost.",
+        description: "Check if a TCP port is in use on localhost. When occupied, also reports who holds it — and if it's a devglow-managed project (so the user can recognize their own process). Call this BEFORE run_process / create_project to avoid silent conflicts.",
         inputSchema: {
             port: z.number().describe("Port number to check"),
         },
     }, async ({ port }) => {
-        const inUse = await checkPort(port);
-        const text = inUse
-            ? `Port ${port} is in use.`
-            : `Port ${port} is available.`;
-        return { content: [{ type: "text", text }] };
+        const info = await getPortInfo(port);
+        if (!info.in_use) {
+            return {
+                content: [{ type: "text", text: `Port ${port} is available.` }],
+                structuredContent: { ...info },
+            };
+        }
+        const lines = [];
+        if (info.owned_by_devglow) {
+            const tag = info.owned_by_devglow.is_ai_process ? "AI process" : "project";
+            lines.push(`Port ${port} is in use by "${info.owned_by_devglow.project_name}" — a devglow-managed ${tag} (PID ${info.occupier?.pid}).`);
+            lines.push(`To free it: stop_project with id "${info.owned_by_devglow.project_id}", or pick a different port.`);
+        }
+        else if (info.occupier) {
+            lines.push(`Port ${port} is in use by ${info.occupier.name} (PID ${info.occupier.pid}) — not a devglow-managed process.`);
+            lines.push(`To free it: ask the user to stop it manually, or pick a different port.`);
+        }
+        else {
+            lines.push(`Port ${port} is in use, but the occupying process could not be identified.`);
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: { ...info },
+        };
     });
     // ── Tool: start_project ──
     server.registerTool("start_project", {
@@ -214,33 +240,200 @@ function createMcpServer() {
     }, async ({ name, path, command, port, description }) => {
         // Auto-detect port from command if not explicitly provided
         const resolvedPort = port ?? detectPortFromCommand(command);
-        await runProcess(name, path, command, resolvedPort, "claude", description);
-        // Brief wait for DevGlow to register the process
-        await new Promise((resolve) => setTimeout(resolve, 300));
-        const text = `AI process "${name}" started.\nCommand: ${command}\nPath: ${path}${resolvedPort ? `\nPort: ${resolvedPort}` : ""}${description ? `\nDescription: ${description}` : ""}`;
-        return { content: [{ type: "text", text }] };
+        const id = await runProcess(name, path, command, resolvedPort, "claude", description);
+        // Poll storage for the registered AI process so we can return actionable info
+        let registered;
+        let status;
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            const aiProcs = await loadAiProcesses();
+            registered = aiProcs.find((p) => p.id === id);
+            if (registered) {
+                const statuses = await loadStatuses();
+                status = statuses.find((s) => s.id === id);
+                // If we have an exit reason or running status, stop polling
+                if (registered.last_exit_reason || status?.running)
+                    break;
+            }
+        }
+        const persisted = registered !== undefined;
+        const running = status?.running ?? false;
+        const portConflict = registered?.port_conflict;
+        const exitReason = registered?.last_exit_reason;
+        let state;
+        if (!persisted)
+            state = "unknown";
+        else if (running)
+            state = "running";
+        else if (exitReason || portConflict)
+            state = "error";
+        else
+            state = "pending";
+        const lines = [];
+        if (state === "running") {
+            lines.push(`Started "${name}" (id: ${id}, PID: ${status?.pid ?? "?"})`);
+        }
+        else if (state === "error") {
+            if (portConflict) {
+                lines.push(`Registered "${name}" (id: ${id}) but NOT started — port ${portConflict.port} is already in use.`);
+                lines.push(`The entry persists in DevGlow with port_conflict flag. Free the port and retry, or pick a different one.`);
+            }
+            else {
+                lines.push(`Registered "${name}" (id: ${id}) but exited shortly after start.${exitReason ? ` Last log line: ${exitReason}` : ""}`);
+                lines.push(`For full output (likely the real cause), call get_logs with id "${id}".`);
+            }
+        }
+        else if (state === "pending") {
+            lines.push(`Registered "${name}" (id: ${id}). Status not yet confirmed; check list_projects.`);
+        }
+        else {
+            lines.push(`Sent run request for "${name}" (id: ${id}) but registration not yet visible in DevGlow.`);
+        }
+        lines.push(`Command: ${command}`);
+        lines.push(`Path: ${path}`);
+        if (resolvedPort)
+            lines.push(`Port: ${resolvedPort}`);
+        if (description)
+            lines.push(`Description: ${description}`);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: {
+                id,
+                persisted,
+                state,
+                running,
+                port_conflict: portConflict ?? null,
+                last_exit_reason: exitReason ?? null,
+            },
+        };
     });
     // ── Tool: update_project ──
     server.registerTool("update_project", {
         title: "Update a project's metadata",
-        description: "Update an existing DevGlow project's metadata (currently only description). Use this to fill in or refresh a project's description after registering it.",
+        description: "Update a kept (permanent) DevGlow project's metadata. Pass only the fields you want to change. Does NOT apply to temporary AI processes — for those, set fields at run_process time or have the user keep the process first.",
         inputSchema: {
             id: z
                 .string()
-                .describe("Project id (call list_projects first to get the id)"),
+                .describe("Project id (call list_projects first). Must be a permanent project, not an AI process (those have ids starting with 'ai-')."),
+            name: z.string().optional().describe("New display name."),
+            path: z.string().optional().describe("New working directory (supports ~/)."),
+            command: z.string().optional().describe("New shell command."),
+            port: z
+                .number()
+                .nullable()
+                .optional()
+                .describe("New port number. Pass null to clear the existing port."),
             description: z
                 .string()
                 .max(280)
-                .describe("Short summary of what the app does (max 280 chars). Pass an empty string to clear the existing description."),
+                .nullable()
+                .optional()
+                .describe("Short summary (max 280 chars). Pass null or empty string to clear."),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Tags as a list of strings. Pass [] to clear all tags."),
         },
-    }, async ({ id, description }) => {
-        await updateProject(id, description);
+    }, async ({ id, name, path, command, port, description, tags }) => {
+        await updateProject(id, { name, path, command, port, description, tags });
         await new Promise((resolve) => setTimeout(resolve, 200));
-        const text = description
-            ? `Project ${id} description updated.`
-            : `Project ${id} description cleared.`;
+        const changed = [];
+        if (name !== undefined)
+            changed.push("name");
+        if (path !== undefined)
+            changed.push("path");
+        if (command !== undefined)
+            changed.push("command");
+        if (port !== undefined)
+            changed.push("port");
+        if (description !== undefined)
+            changed.push("description");
+        if (tags !== undefined)
+            changed.push("tags");
+        const text = changed.length === 0
+            ? `Project ${id}: no fields supplied (no-op).`
+            : `Project ${id} updated: ${changed.join(", ")}.`;
         return { content: [{ type: "text", text }] };
     });
+    // ── Tool: create_project ──
+    server.registerTool("create_project", {
+        title: "Create a permanent project (without running)",
+        description: "Register a permanent DevGlow project WITHOUT running it. Use this for bulk registration when you want to record metadata only (no port binding, no browser tab, no dependency install). To start the project later, call start_project. Use run_process instead when you need to actually launch a server for verification or one-off work.",
+        inputSchema: {
+            name: z.string().describe("Display name."),
+            path: z.string().describe("Working directory (supports ~/)."),
+            command: z.string().describe("Shell command to run when the user starts the project."),
+            port: z
+                .number()
+                .optional()
+                .describe("Port number the command listens on, if any. Used for the Open ↗ button."),
+            description: z
+                .string()
+                .max(280)
+                .optional()
+                .describe("Short summary of what the app does (max 280 chars)."),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Tags. Used as inline filters in the UI."),
+        },
+    }, async ({ name, path, command, port, description, tags }) => {
+        const id = await createProject({ name, path, command, port, description, tags });
+        // Poll for confirmation that the project landed in projects.json
+        let registered = false;
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            const projects = await loadProjects();
+            if (projects.some((p) => p.id === id)) {
+                registered = true;
+                break;
+            }
+        }
+        const lines = [];
+        if (registered) {
+            lines.push(`Created permanent project "${name}" (id: ${id}). Not running — use start_project to launch.`);
+        }
+        else {
+            lines.push(`Sent create request for "${name}" (id: ${id}) but registration not yet visible. Check list_projects.`);
+        }
+        lines.push(`Command: ${command}`);
+        lines.push(`Path: ${path}`);
+        if (port)
+            lines.push(`Port: ${port}`);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: { id, persisted: registered },
+        };
+    });
+    // ── Tool: delete_project ──
+    server.registerTool("delete_project", {
+        title: "Delete a permanent project",
+        description: "Delete a kept (permanent) DevGlow project. Stops the process if running. Does NOT apply to AI processes — those are dismissed via the UI.",
+        inputSchema: {
+            id: z
+                .string()
+                .describe("Project id (call list_projects first). Must be a permanent project, not an AI process."),
+        },
+    }, async ({ id }) => {
+        await deleteProject(id);
+        // Poll briefly to confirm removal
+        let removed = false;
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            const projects = await loadProjects();
+            if (!projects.some((p) => p.id === id)) {
+                removed = true;
+                break;
+            }
+        }
+        const text = removed
+            ? `Project ${id} deleted.`
+            : `Sent delete request for ${id} but it's still listed. The user may need to confirm in the UI.`;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { id, removed },
+        };
+    });
     // ── Tool: stop_process ──
     server.registerTool("stop_process", {
         title: "Stop an AI process",

package/build/portInfo.js

@@ -0,0 +1,54 @@
+import { execFile } from "child_process";
+import { loadProjects, loadAiProcesses, loadStatuses } from "./storage.js";
+export async function getPortOccupier(port) {
+    return new Promise((resolve) => {
+        // -i :PORT          : restrict to that port
+        // -sTCP:LISTEN      : only LISTEN sockets (avoid ephemeral connect-side matches)
+        // -Fpcn             : machine-readable: p<pid> c<command> n<name>
+        execFile("lsof", ["-i", `:${port}`, "-sTCP:LISTEN", "-Fpc"], (err, stdout) => {
+            if (err || !stdout)
+                return resolve(null);
+            let pid = null;
+            let name = null;
+            for (const line of stdout.split("\n")) {
+                if (line.startsWith("p"))
+                    pid = parseInt(line.slice(1), 10);
+                else if (line.startsWith("c"))
+                    name = line.slice(1);
+                if (pid !== null && name !== null)
+                    break;
+            }
+            if (pid !== null)
+                resolve({ pid, name: name ?? "unknown" });
+            else
+                resolve(null);
+        });
+    });
+}
+export async function findDevglowOwner(pid) {
+    const [projects, aiProcs, statuses] = await Promise.all([
+        loadProjects(),
+        loadAiProcesses(),
+        loadStatuses(),
+    ]);
+    const ownerStatus = statuses.find((s) => s.pid === pid && s.running);
+    if (!ownerStatus)
+        return null;
+    const ai = aiProcs.find((p) => p.id === ownerStatus.id);
+    if (ai) {
+        return { project_id: ai.id, project_name: ai.name, is_ai_process: true };
+    }
+    const proj = projects.find((p) => p.id === ownerStatus.id);
+    if (proj) {
+        return { project_id: proj.id, project_name: proj.name, is_ai_process: false };
+    }
+    return null;
+}
+export async function getPortInfo(port) {
+    const occupier = await getPortOccupier(port);
+    if (!occupier) {
+        return { port, in_use: false, occupier: null, owned_by_devglow: null };
+    }
+    const owned = await findDevglowOwner(occupier.pid);
+    return { port, in_use: true, occupier, owned_by_devglow: owned };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devglow-mcp",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "MCP server for DevGlow — manage local dev processes through AI agents",
   "type": "module",
   "bin": {