@yinuo-ngm/mcp-server 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ZhangJing
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @yinuo-ngm/mcp-server
+
+Local MCP stdio server for ng-manager core capabilities.
+
+This package is an AI Agent adapter layer. It is not a business core, not a Fastify replacement, not an Electron lifecycle manager, and not a general shell execution entrypoint.
+
+## Positioning
+
+The intended boundary is:
+
+```text
+MCP client -> packages/mcp-server -> ToolContext.services -> packages/core
+```
+
+MCP tools must not call the local Fastify HTTP API. HTTP routes, Electron IPC, CLI commands, and MCP tools should all adapt the same core services.
+
+## Safety
+
+Tools are assigned one risk level:
+
+```text
+read
+write
+execute
+dangerous
+```
+
+Default policy:
+
+```text
+read      allowed
+write     blocked
+execute   blocked
+dangerous blocked
+```
+
+This MVP only registers read tools. It does not implement arbitrary shell execution, task start/stop/restart, git pull/checkout/commit/reset, proxy reload, runtime install/remove, file deletion, or system environment mutation.
+
+## Environment
+
+```text
+NGM_DATA_DIR                 ng-manager data directory. Defaults to ~/.ng-manager.
+NGM_WORKSPACE_ROOT           Optional workspace hint. Defaults to process.cwd().
+NGM_MCP_ALLOW_WRITE          Future policy flag for write tools. Defaults to false.
+NGM_MCP_ALLOW_EXECUTE        Future policy flag for execute tools. Defaults to false.
+NGM_MCP_ALLOW_DANGEROUS      Future policy flag for dangerous tools. Defaults to false.
+```
+
+## Commands
+
+From the repository root:
+
+```bash
+npm run mcp:dev
+npm run mcp:build
+npm run mcp:start
+```
+
+Direct workspace commands:
+
+```bash
+npm run dev -w @yinuo-ngm/mcp-server
+npm run build -w @yinuo-ngm/mcp-server
+npm run start -w @yinuo-ngm/mcp-server
+```
+
+The server uses stdio transport only. It does not listen on an HTTP port, and stdout is reserved for the MCP protocol.
+
+## MCP Client Configuration
+
+Built output:
+
+```json
+{
+  "mcpServers": {
+    "ng-manager": {
+      "command": "node",
+      "args": [
+        "D:/ng-manager/packages/mcp-server/lib/index.js"
+      ],
+      "env": {
+        "NGM_DATA_DIR": "C:/Users/you/.ng-manager",
+        "NGM_WORKSPACE_ROOT": "D:/ng-manager",
+        "NGM_MCP_ALLOW_WRITE": "false",
+        "NGM_MCP_ALLOW_EXECUTE": "false",
+        "NGM_MCP_ALLOW_DANGEROUS": "false"
+      }
+    }
+  }
+}
+```
+
+Development:
+
+```json
+{
+  "mcpServers": {
+    "ng-manager": {
+      "command": "npm",
+      "args": [
+        "run",
+        "dev",
+        "-w",
+        "@yinuo-ngm/mcp-server"
+      ],
+      "env": {
+        "NGM_DATA_DIR": "C:/Users/you/.ng-manager",
+        "NGM_WORKSPACE_ROOT": "D:/ng-manager"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+Project:
+
+```text
+ngm.project.list
+ngm.project.get
+ngm.project.getScripts
+```
+
+Task:
+
+```text
+ngm.task.list
+ngm.task.getStatus
+```
+
+Log:
+
+```text
+ngm.log.tail
+ngm.log.search
+```
+
+Git:
+
+```text
+ngm.git.status
+ngm.git.diff
+```
+
+The Git tools are registered in this MVP but return a clear "not implemented in core yet" error through the Git service stub. A future phase should add a read-only Git service to `packages/core` first.
+
+Runtime:
+
+```text
+ngm.runtime.list
+ngm.runtime.resolveForProject
+```
+
+Proxy:
+
+```text
+ngm.proxy.list
+ngm.proxy.validate
+```
+
+In this package, "proxy" means ng-manager's current Nginx/proxy management domain, not the operating system global proxy.
+
+## Result Shape
+
+All tools return structured JSON as text content:
+
+```json
+{
+  "ok": true,
+  "tool": "ngm.project.list",
+  "data": []
+}
+```
+
+Errors use:
+
+```json
+{
+  "ok": false,
+  "tool": "ngm.project.get",
+  "error": "projectId or projectPath is required"
+}
+```
+
+## Replacing Stubs
+
+Add missing capabilities to `packages/core` first, then replace the corresponding service inside `ToolContext.services`. MCP tools should remain thin adapters that validate input, enforce policy, call core services, and cap output size.

package/lib/context/create-tool-context.d.ts

@@ -0,0 +1,2 @@
+import type { ToolContext } from "./tool-context";
+export declare function createToolContext(): Promise<ToolContext>;

package/lib/context/create-tool-context.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolContext = createToolContext;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const core_1 = require("@yinuo-ngm/core");
+const gitStub = {
+    async status() {
+        throw new Error("Git service is not implemented in core yet");
+    },
+    async diff() {
+        throw new Error("Git service is not implemented in core yet");
+    },
+};
+async function createToolContext() {
+    const dataDir = process.env.NGM_DATA_DIR || path.join(os.homedir(), ".ng-manager");
+    const workspaceRoot = process.env.NGM_WORKSPACE_ROOT || process.cwd();
+    const core = await (0, core_1.createCoreApp)({
+        dataDir,
+        sysLogCapacity: 3000,
+    });
+    return {
+        workspaceRoot,
+        dataDir,
+        services: {
+            core,
+            git: gitStub,
+        },
+        async dispose() {
+            await core.dispose();
+        },
+    };
+}

package/lib/context/tool-context.d.ts

@@ -0,0 +1,22 @@
+import type { CoreApp } from "@yinuo-ngm/core";
+export type GitReadService = {
+    status(input: {
+        projectId?: string;
+        projectPath?: string;
+    }): Promise<unknown>;
+    diff(input: {
+        projectId?: string;
+        projectPath?: string;
+        maxBytes?: number;
+    }): Promise<unknown>;
+};
+export type ToolServices = {
+    core: CoreApp;
+    git: GitReadService;
+};
+export type ToolContext = {
+    workspaceRoot: string;
+    dataDir: string;
+    services: ToolServices;
+    dispose(): Promise<void>;
+};

package/lib/context/tool-context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/create-mcp-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./context/tool-context";
+export declare function createMcpServer(context: ToolContext): McpServer;

package/lib/create-mcp-server.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const register_tools_1 = require("./register-tools");
+function createMcpServer(context) {
+    const server = new mcp_js_1.McpServer({ name: "ng-manager", version: "0.1.0" }, { capabilities: { tools: {} } });
+    (0, register_tools_1.registerTools)(server, context);
+    return server;
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;

package/lib/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const create_tool_context_1 = require("./context/create-tool-context");
+const create_mcp_server_1 = require("./create-mcp-server");
+const errors_1 = require("./utils/errors");
+async function main() {
+    const context = await (0, create_tool_context_1.createToolContext)();
+    const server = (0, create_mcp_server_1.createMcpServer)(context);
+    const cleanup = async () => {
+        await context.dispose();
+    };
+    process.once("SIGINT", () => {
+        void cleanup().finally(() => process.exit(0));
+    });
+    process.once("SIGTERM", () => {
+        void cleanup().finally(() => process.exit(0));
+    });
+    await server.connect(new stdio_js_1.StdioServerTransport());
+}
+if (require.main === module) {
+    main().catch((error) => {
+        process.stderr.write(`${(0, errors_1.errorMessage)(error)}\n`);
+        process.exit(1);
+    });
+}

package/lib/policy/assert-tool-policy.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRiskLevel, ToolPolicy } from "./tool-policy";
+export declare function assertToolPolicy(policy: ToolPolicy, toolName: string, riskLevel: ToolRiskLevel): void;

package/lib/policy/assert-tool-policy.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertToolPolicy = assertToolPolicy;
+function assertToolPolicy(policy, toolName, riskLevel) {
+    if (!policy[riskLevel]) {
+        throw new Error(`Tool ${toolName} is blocked by policy: ${riskLevel} tools are disabled`);
+    }
+}

package/lib/policy/tool-policy.d.ts

@@ -0,0 +1,3 @@
+export type ToolRiskLevel = "read" | "write" | "execute" | "dangerous";
+export type ToolPolicy = Record<ToolRiskLevel, boolean>;
+export declare function createDefaultToolPolicy(): ToolPolicy;

package/lib/policy/tool-policy.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultToolPolicy = createDefaultToolPolicy;
+function envFlag(name) {
+    return String(process.env[name] ?? "").trim().toLowerCase() === "true";
+}
+function createDefaultToolPolicy() {
+    return {
+        read: true,
+        write: envFlag("NGM_MCP_ALLOW_WRITE"),
+        execute: envFlag("NGM_MCP_ALLOW_EXECUTE"),
+        dangerous: envFlag("NGM_MCP_ALLOW_DANGEROUS"),
+    };
+}

package/lib/register-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./context/tool-context";
+export declare function registerTools(server: McpServer, context: ToolContext): void;

package/lib/register-tools.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const assert_tool_policy_1 = require("./policy/assert-tool-policy");
+const tool_policy_1 = require("./policy/tool-policy");
+const tools_1 = require("./tools");
+const errors_1 = require("./utils/errors");
+const result_1 = require("./utils/result");
+function registerTools(server, context) {
+    const policy = (0, tool_policy_1.createDefaultToolPolicy)();
+    const registerTool = server.registerTool.bind(server);
+    for (const tool of (0, tools_1.allTools)()) {
+        registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            try {
+                (0, assert_tool_policy_1.assertToolPolicy)(policy, tool.name, tool.riskLevel);
+                const parsed = tool.inputSchema.parse(args);
+                const result = await tool.handler(parsed, context);
+                return (0, result_1.toMcpTextResult)(result);
+            }
+            catch (error) {
+                return (0, result_1.toMcpTextResult)((0, result_1.fail)(tool.name, (0, errors_1.errorMessage)(error)));
+            }
+        });
+    }
+}

package/lib/tools/git.tools.d.ts

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

package/lib/tools/git.tools.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitTools = gitTools;
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+const gitProjectSchema = zod_1.z.object({
+    projectId: zod_1.z.string().trim().min(1).optional(),
+    projectPath: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+const gitDiffSchema = gitProjectSchema.extend({
+    maxBytes: zod_1.z.number().int().min(1).max(200000).optional(),
+}).strict();
+function gitTools() {
+    return [
+        {
+            name: "ngm.git.status",
+            description: "Read Git working tree status for a project. This MVP uses a core Git service stub.",
+            riskLevel: "read",
+            inputSchema: gitProjectSchema,
+            async handler(args, context) {
+                const data = await context.services.git.status(args);
+                return (0, result_1.ok)("ngm.git.status", data);
+            },
+        },
+        {
+            name: "ngm.git.diff",
+            description: "Read Git diff for a project. This MVP uses a core Git service stub.",
+            riskLevel: "read",
+            inputSchema: gitDiffSchema,
+            async handler(args, context) {
+                const data = await context.services.git.diff(args);
+                return (0, result_1.ok)("ngm.git.diff", data);
+            },
+        },
+    ];
+}

package/lib/tools/index.d.ts

@@ -0,0 +1,12 @@
+import type { z } from "zod";
+import type { ToolContext } from "../context/tool-context";
+import type { ToolRiskLevel } from "../policy/tool-policy";
+import type { ToolResult } from "../utils/result";
+export type McpToolDefinition<TSchema extends z.AnyZodObject = z.AnyZodObject> = {
+    name: string;
+    description: string;
+    riskLevel: ToolRiskLevel;
+    inputSchema: TSchema;
+    handler(args: z.infer<TSchema>, context: ToolContext): Promise<ToolResult> | ToolResult;
+};
+export declare function allTools(): McpToolDefinition[];

package/lib/tools/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allTools = allTools;
+const git_tools_1 = require("./git.tools");
+const log_tools_1 = require("./log.tools");
+const project_tools_1 = require("./project.tools");
+const proxy_tools_1 = require("./proxy.tools");
+const runtime_tools_1 = require("./runtime.tools");
+const task_tools_1 = require("./task.tools");
+function allTools() {
+    return [
+        ...(0, project_tools_1.projectTools)(),
+        ...(0, task_tools_1.taskTools)(),
+        ...(0, log_tools_1.logTools)(),
+        ...(0, git_tools_1.gitTools)(),
+        ...(0, runtime_tools_1.runtimeTools)(),
+        ...(0, proxy_tools_1.proxyTools)(),
+    ];
+}

package/lib/tools/log.tools.d.ts

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

package/lib/tools/log.tools.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logTools = logTools;
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+const logTailSchema = zod_1.z.object({
+    runId: zod_1.z.string().trim().min(1).optional(),
+    taskId: zod_1.z.string().trim().min(1).optional(),
+    tail: zod_1.z.number().int().min(1).max(500).optional(),
+}).strict();
+const logSearchSchema = zod_1.z.object({
+    query: zod_1.z.string().trim().min(1),
+    limit: zod_1.z.number().int().min(1).max(200).optional(),
+    source: zod_1.z.string().trim().min(1).optional(),
+    scope: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+function clampTail(value) {
+    return Math.min(Math.max(value ?? 100, 1), 500);
+}
+function clampSearchLimit(value) {
+    return Math.min(Math.max(value ?? 50, 1), 200);
+}
+function logTools() {
+    return [
+        {
+            name: "ngm.log.tail",
+            description: "Read recent task logs by runId or taskId.",
+            riskLevel: "read",
+            inputSchema: logTailSchema,
+            async handler(args, context) {
+                const tail = clampTail(args.tail);
+                let runId = args.runId;
+                if (!runId && args.taskId) {
+                    const snapshot = await context.services.core.task.getSnapshotByTaskId(args.taskId);
+                    runId = snapshot?.runId;
+                }
+                if (!runId) {
+                    throw new Error("runId or taskId is required");
+                }
+                const lines = await context.services.core.task.getTailLogsByRun(runId, tail);
+                return (0, result_1.ok)("ngm.log.tail", {
+                    runId,
+                    tail,
+                    lines,
+                });
+            },
+        },
+        {
+            name: "ngm.log.search",
+            description: "Search recent ng-manager system logs by keyword.",
+            riskLevel: "read",
+            inputSchema: logSearchSchema,
+            async handler(args, context) {
+                const limit = clampSearchLimit(args.limit);
+                const filter = {
+                    ...(args.source ? { source: args.source } : {}),
+                    ...(args.scope ? { scope: args.scope } : {}),
+                };
+                const needle = args.query.toLowerCase();
+                const entries = context.services.core.sysLog
+                    .query(filter, { limit: 10000 })
+                    .filter((entry) => {
+                    const text = `${entry.text} ${JSON.stringify(entry.data ?? {})}`.toLowerCase();
+                    return text.includes(needle);
+                })
+                    .slice(0, limit);
+                return (0, result_1.ok)("ngm.log.search", {
+                    query: args.query,
+                    limit,
+                    entries,
+                });
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,18 @@
+import type { Project } from "@yinuo-ngm/project";
+import { z } from "zod";
+import type { ToolContext } from "../context/tool-context";
+import type { McpToolDefinition } from "./index";
+export declare const projectLocatorSchema: z.ZodObject<{
+    projectId: z.ZodOptional<z.ZodString>;
+    projectPath: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    projectId?: string | undefined;
+    projectPath?: string | undefined;
+}, {
+    projectId?: string | undefined;
+    projectPath?: string | undefined;
+}>;
+type ProjectLocator = z.infer<typeof projectLocatorSchema>;
+export declare function resolveProject(context: ToolContext, locator: ProjectLocator): Promise<Project>;
+export declare function projectTools(): McpToolDefinition[];
+export {};

package/lib/tools/project.tools.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectLocatorSchema = void 0;
+exports.resolveProject = resolveProject;
+exports.projectTools = projectTools;
+const path = __importStar(require("path"));
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+exports.projectLocatorSchema = zod_1.z.object({
+    projectId: zod_1.z.string().trim().min(1).optional(),
+    projectPath: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+async function resolveProject(context, locator) {
+    if (locator.projectId) {
+        return context.services.core.project.get(locator.projectId);
+    }
+    if (locator.projectPath) {
+        const projects = await context.services.core.project.list();
+        const requestedPath = normalizeFsPath(locator.projectPath);
+        const project = projects.find((item) => normalizeFsPath(item.root) === requestedPath);
+        if (project) {
+            return project;
+        }
+        throw new Error(`Project not found for path: ${locator.projectPath}`);
+    }
+    throw new Error("projectId or projectPath is required");
+}
+function normalizeFsPath(value) {
+    const resolved = path.resolve(value);
+    return process.platform === "win32" ? resolved.replace(/\\/g, "/").toLowerCase() : resolved;
+}
+function toProjectSummary(project) {
+    return {
+        id: project.id,
+        name: project.name,
+        root: project.root,
+        createdAt: project.createdAt,
+        updatedAt: project.updatedAt,
+        scripts: project.scripts,
+        packageManager: project.packageManager,
+        runtime: project.runtime,
+        nodeVersion: project.nodeVersion,
+        framework: project.framework,
+        env: project.env,
+        isFavorite: project.isFavorite,
+        lastOpened: project.lastOpened,
+        repoUrl: project.repoUrl,
+        repoPageUrl: project.repoPageUrl,
+        assets: project.assets,
+    };
+}
+function toProjectScripts(project) {
+    return {
+        id: project.id,
+        name: project.name,
+        root: project.root,
+        scripts: project.scripts ?? {},
+        packageManager: project.packageManager,
+        nodeVersion: project.nodeVersion,
+        runtime: project.runtime,
+    };
+}
+function projectTools() {
+    return [
+        {
+            name: "ngm.project.list",
+            description: "List projects managed by ng-manager.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const projects = await context.services.core.project.list();
+                return (0, result_1.ok)("ngm.project.list", projects.map(toProjectSummary));
+            },
+        },
+        {
+            name: "ngm.project.get",
+            description: "Get one ng-manager project by projectId or projectPath.",
+            riskLevel: "read",
+            inputSchema: exports.projectLocatorSchema,
+            async handler(args, context) {
+                const project = await resolveProject(context, args);
+                return (0, result_1.ok)("ngm.project.get", toProjectSummary(project));
+            },
+        },
+        {
+            name: "ngm.project.getScripts",
+            description: "Get package scripts and runtime hints for one ng-manager project.",
+            riskLevel: "read",
+            inputSchema: exports.projectLocatorSchema,
+            async handler(args, context) {
+                const project = await resolveProject(context, args);
+                return (0, result_1.ok)("ngm.project.getScripts", toProjectScripts(project));
+            },
+        },
+    ];
+}

package/lib/tools/proxy.tools.d.ts

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

package/lib/tools/proxy.tools.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proxyTools = proxyTools;
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+const proxyValidateSchema = zod_1.z.object({
+    configText: zod_1.z.string().optional(),
+}).strict();
+function proxyTools() {
+    return [
+        {
+            name: "ngm.proxy.list",
+            description: "List current ng-manager Nginx/proxy binding, status, servers, and upstreams.",
+            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, servers, upstreams] = await Promise.all([
+                    nginx.service.getStatus().catch((error) => ({
+                        isRunning: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    })),
+                    nginx.server.getAllServers().catch(() => []),
+                    nginx.module.getUpstreams().catch(() => []),
+                ]);
+                return (0, result_1.ok)("ngm.proxy.list", {
+                    instance,
+                    status,
+                    servers,
+                    upstreams,
+                });
+            },
+        },
+        {
+            name: "ngm.proxy.validate",
+            description: "Validate the current or supplied ng-manager Nginx/proxy config without reload.",
+            riskLevel: "read",
+            inputSchema: proxyValidateSchema,
+            async handler(args, context) {
+                const validation = await context.services.core.nginx.config.validateConfig(args.configText);
+                return (0, result_1.ok)("ngm.proxy.validate", validation);
+            },
+        },
+    ];
+}

package/lib/tools/runtime.tools.d.ts

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

package/lib/tools/runtime.tools.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeTools = runtimeTools;
+const zod_1 = require("zod");
+const project_tools_1 = require("./project.tools");
+const result_1 = require("../utils/result");
+function normalizePackageManager(value) {
+    return value === "pnpm" || value === "yarn" ? value : "npm";
+}
+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 runtimeTools() {
+    return [
+        {
+            name: "ngm.runtime.list",
+            description: "List Node runtimes known to ng-manager.",
+            riskLevel: "read",
+            inputSchema: zod_1.z.object({}).strict(),
+            async handler(_args, context) {
+                const runtimes = await context.services.core.nodeRuntime.listRuntimes();
+                return (0, result_1.ok)("ngm.runtime.list", runtimes);
+            },
+        },
+        {
+            name: "ngm.runtime.resolveForProject",
+            description: "Resolve the Node runtime ng-manager would use for a project.",
+            riskLevel: "read",
+            inputSchema: project_tools_1.projectLocatorSchema,
+            async handler(args, context) {
+                const project = await (0, project_tools_1.resolveProject)(context, args);
+                const requestedRuntime = runtimeConfigForProject(project);
+                const resolvedRuntime = await context.services.core.nodeRuntime.resolveRuntime(requestedRuntime);
+                return (0, result_1.ok)("ngm.runtime.resolveForProject", {
+                    project: {
+                        id: project.id,
+                        name: project.name,
+                        root: project.root,
+                        packageManager: project.packageManager,
+                        nodeVersion: project.nodeVersion,
+                        runtime: project.runtime,
+                    },
+                    requestedRuntime,
+                    resolvedRuntime,
+                });
+            },
+        },
+    ];
+}

package/lib/tools/task.tools.d.ts

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

package/lib/tools/task.tools.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskTools = taskTools;
+const zod_1 = require("zod");
+const result_1 = require("../utils/result");
+const taskListSchema = zod_1.z.object({
+    projectId: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+const taskStatusSchema = zod_1.z.object({
+    taskId: zod_1.z.string().trim().min(1),
+}).strict();
+function taskTools() {
+    return [
+        {
+            name: "ngm.task.list",
+            description: "List registered task views for a project, or active tasks when projectId is omitted.",
+            riskLevel: "read",
+            inputSchema: taskListSchema,
+            async handler(args, context) {
+                if (args.projectId) {
+                    const rows = await context.services.core.task.listViewsByProject(args.projectId);
+                    return (0, result_1.ok)("ngm.task.list", rows);
+                }
+                const activeTasks = await context.services.core.task.listActive();
+                return (0, result_1.ok)("ngm.task.list", activeTasks);
+            },
+        },
+        {
+            name: "ngm.task.getStatus",
+            description: "Get the runtime status for a registered task.",
+            riskLevel: "read",
+            inputSchema: taskStatusSchema,
+            async handler(args, context) {
+                const runtime = await context.services.core.task.status(args.taskId);
+                return (0, result_1.ok)("ngm.task.getStatus", runtime);
+            },
+        },
+    ];
+}

package/lib/utils/errors.d.ts

@@ -0,0 +1 @@
+export declare function errorMessage(error: unknown): string;

package/lib/utils/errors.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorMessage = errorMessage;
+function errorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error ?? "Unknown error");
+}

package/lib/utils/result.d.ts

@@ -0,0 +1,19 @@
+export type ToolSuccessResult<T = unknown> = {
+    ok: true;
+    tool: string;
+    data: T;
+};
+export type ToolErrorResult = {
+    ok: false;
+    tool: string;
+    error: string;
+};
+export type ToolResult<T = unknown> = ToolSuccessResult<T> | ToolErrorResult;
+export declare function ok<T>(tool: string, data: T): ToolSuccessResult<T>;
+export declare function fail(tool: string, error: string): ToolErrorResult;
+export declare function toMcpTextResult(result: ToolResult): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};

package/lib/utils/result.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.fail = fail;
+exports.toMcpTextResult = toMcpTextResult;
+function ok(tool, data) {
+    return { ok: true, tool, data };
+}
+function fail(tool, error) {
+    return { ok: false, tool, error };
+}
+function toMcpTextResult(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@yinuo-ngm/mcp-server",
+  "version": "0.1.1",
+  "description": "Local MCP stdio server for ng-manager core capabilities.",
+  "author": "ZhangJing <892295834@qq.com>",
+  "license": "ISC",
+  "bin": {
+    "ngm-mcp-server": "lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -b tsconfig.json",
+    "start": "node lib/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@yinuo-ngm/core": "^0.1.14",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "f64135f6db80de6928bc0b83c29c26e408e9fcfb"
+}