@yinuo-ngm/mcp-server 0.1.1 → 0.1.3

package/README.md

@@ -1,188 +1,225 @@
-# @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.
+# @yinuo-ngm/mcp-server
+
+Local MCP Server for ng-manager.
+
+Provides MCP tools that expose ng-manager capabilities to AI Agents such as Codex, OpenCode, Claude Code, Cursor, and other MCP-compatible clients.
+
+The MCP server is an adapter layer only. Business logic belongs in `packages/core`.
+
+---
+
+## Architecture
+
+```text
+AI Agent
+    ↓
+MCP Client
+    ↓
+packages/mcp-server
+    ↓
+ToolContext.services
+    ↓
+packages/core
+    ↓
+Local Services
+```
+
+Principles:
+
+- MCP tools are thin adapters
+- No duplicated business logic
+- No Fastify dependency
+- No Electron dependency
+- Reuse the same core services as CLI, UI, and Local Server
+
+---
+
+## Quick Start
+
+Repository root:
+
+```bash
+npm run mcp:dev
+npm run mcp:build
+npm run mcp:start
+```
+
+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
+```
+
+CLI:
+
+```bash
+ngm mcp
+```
+
+Diagnostics:
+
+```bash
+ngm mcp doctor
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|-----------|-------------|
+| NGM_DATA_DIR | ng-manager data directory |
+| NGM_MCP_ALLOW_WRITE | Enable write tools |
+| NGM_MCP_ALLOW_EXECUTE | Enable execute tools |
+| NGM_MCP_ALLOW_DANGEROUS | Enable dangerous tools |
+| NGM_MCP_ALLOW_HUB | Enable Hub V2 write operations |
+| NGM_MCP_MAX_RESULT_CHARS | MCP response size limit |
+
+---
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "ng-manager": {
+      "command": "node",
+      "args": [
+        "packages/mcp-server/lib/index.js"
+      ],
+      "env": {
+        "NGM_DATA_DIR": "~/.ng-manager"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool Categories
+
+### Workspace
+
+- Workspace discovery
+- Package metadata
+- Capability routing
+- Context generation
+
+### Project
+
+- Project metadata
+- Package.json access
+- Script discovery
+- Task status and logs
+
+### Runtime
+
+- Node runtime discovery
+- Runtime resolution
+- Project runtime configuration
+
+### Nginx
+
+- Status inspection
+- Configuration validation
+- Proxy management
+
+### Git
+
+- Status and diff
+- Commit message generation
+- Review assistance
+
+### Frontend Workflow
+
+- Standards validation
+- Review scanning
+- Task planning
+- Delivery reports
+
+### Hub V2
+
+- Documents
+- Issues
+- RD workflows
+- File uploads
+
+---
+
+## Safety Model
+
+Risk levels:
+
+```text
+read
+write
+execute
+dangerous
+```
+
+Default policy:
+
+```text
+read      allowed
+write     blocked
+execute   blocked
+dangerous blocked
+```
+
+Write and execute operations require:
+
+- `confirm=true`
+- Matching environment flag enabled
+- Policy validation passed
+
+The MCP server does not provide:
+
+- Arbitrary shell execution
+- Arbitrary file system access
+- System environment mutation
+- Remote client command execution
+
+---
+
+## Documentation
+
+Detailed documentation is maintained under:
+
+```text
+packages/mcp-server/docs/
+```
+
+Recommended structure:
+
+```text
+docs/
+├─ architecture.md
+├─ security.md
+├─ configuration.md
+└─ tools/
+   ├─ ngm-workspace.md
+   ├─ ngm-project.md
+   ├─ ngm-runtime.md
+   ├─ ngm-nginx.md
+   ├─ ngm-git.md
+   └─ hub-v2.md
+```
+
+---
+
+## Design Goal
+
+ng-manager MCP Server is the unified AI integration layer for local-first engineering workflows.
+
+```text
+AI Agent
+    ↓
+MCP
+    ↓
+ng-manager Core
+    ↓
+Local Control Plane
+```

package/lib/audit/audit-event.d.ts

@@ -0,0 +1,14 @@
+import type { ToolRiskLevel } from "../policy/tool-policy";
+import type { ToolResult } from "../utils/result";
+export type AuditToolEvent = {
+    tool: string;
+    riskLevel: ToolRiskLevel;
+    args?: unknown;
+    result?: ToolResult;
+    error?: unknown;
+    durationMs: number;
+};
+export type AuditWarning = {
+    code: "AUDIT_LOG_WRITE_FAILED";
+    message: string;
+};

package/lib/audit/audit-event.js

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

package/lib/audit/audit-log.service.d.ts

@@ -0,0 +1,7 @@
+import type { ToolRiskLevel } from "../policy/tool-policy";
+import type { ToolContext } from "../context/tool-context";
+import type { AuditToolEvent, AuditWarning } from "./audit-event";
+export declare function summarizeAuditArgs(args: unknown): Record<string, unknown>;
+export declare function writeAuditLog(context: ToolContext, event: AuditToolEvent): Promise<void>;
+export declare function shouldAuditTool(toolName: string, riskLevel: ToolRiskLevel): boolean;
+export declare function auditWarning(error: unknown): AuditWarning;

package/lib/audit/audit-log.service.js

@@ -0,0 +1,187 @@
+"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.summarizeAuditArgs = summarizeAuditArgs;
+exports.writeAuditLog = writeAuditLog;
+exports.shouldAuditTool = shouldAuditTool;
+exports.auditWarning = auditWarning;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const project_files_1 = require("../filesystem/project-files");
+const redact_1 = require("./redact");
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getString(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : undefined;
+}
+function normalizePath(value) {
+    const resolved = path.resolve(value);
+    return process.platform === "win32" ? resolved.replace(/\\/g, "/").toLowerCase() : resolved;
+}
+async function registeredProjectByPath(context, projectPath) {
+    const list = context.services.core?.project?.list;
+    if (typeof list !== "function")
+        return null;
+    let projects;
+    try {
+        projects = await list.call(context.services.core.project);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(projects))
+        return null;
+    const requested = normalizePath(projectPath);
+    const matched = projects.find((project) => typeof project?.root === "string" && normalizePath(project.root) === requested);
+    return matched ? {
+        projectId: typeof matched.id === "string" ? matched.id : undefined,
+        projectName: typeof matched.name === "string" ? matched.name : undefined,
+        projectRoot: path.resolve(matched.root),
+    } : null;
+}
+async function resolveAuditProjectRoot(context, args) {
+    const projectId = getString(args, "projectId");
+    if (projectId) {
+        const project = await context.services.core.project.get(projectId);
+        return {
+            projectId: project.id,
+            projectName: project.name,
+            projectRoot: path.resolve(project.root),
+        };
+    }
+    const projectPath = getString(args, "projectPath");
+    if (projectPath) {
+        const requestedRoot = path.resolve(projectPath);
+        const registered = await registeredProjectByPath(context, requestedRoot);
+        if (registered)
+            return registered;
+        throw new Error("Audit projectPath must match a registered project root");
+    }
+    return {
+        projectRoot: path.resolve(context.workspaceRoot),
+    };
+}
+function byteLength(value) {
+    return typeof value === "string" ? Buffer.byteLength(value, "utf-8") : undefined;
+}
+function shortText(value, maxChars = 200) {
+    if (typeof value !== "string")
+        return undefined;
+    const redacted = (0, redact_1.redactText)(value);
+    return redacted.length > maxChars ? `${redacted.slice(0, maxChars)}...` : redacted;
+}
+function summarizeAuditArgs(args) {
+    const source = isRecord(args) ? args : {};
+    const out = {};
+    for (const key of ["projectId", "projectPath", "taskId"]) {
+        const value = getString(source, key);
+        if (value)
+            out[key] = value;
+    }
+    for (const key of ["confirm", "dryRun", "overwrite"]) {
+        if (typeof source[key] === "boolean")
+            out[key] = source[key];
+    }
+    const title = shortText(source.title);
+    if (title)
+        out.title = title;
+    const patchBytes = byteLength(source.patch);
+    if (patchBytes !== undefined)
+        out.patchBytes = patchBytes;
+    const contextBytes = byteLength(source.context);
+    if (contextBytes !== undefined)
+        out.contextBytes = contextBytes;
+    const markdownBytes = byteLength(source.markdown);
+    if (markdownBytes !== undefined)
+        out.markdownBytes = markdownBytes;
+    const summaryBytes = byteLength(source.summary);
+    if (summaryBytes !== undefined)
+        out.summaryBytes = summaryBytes;
+    return out;
+}
+function resultStatus(result, error) {
+    if (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.includes("blocked by policy") ? "blocked" : "failed";
+    }
+    if (!result)
+        return "unknown";
+    if (!result.ok)
+        return "failed";
+    const data = isRecord(result.data) ? result.data : {};
+    const operation = isRecord(data.operation) ? data.operation : undefined;
+    return typeof operation?.status === "string" ? operation.status : "ok";
+}
+function changedFilesFromResult(result) {
+    if (!result?.ok || !isRecord(result.data))
+        return [];
+    const value = result.data.changedFiles;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string").slice(0, 100);
+}
+function todayFileName(now = new Date()) {
+    return `mcp-${now.toISOString().slice(0, 10)}.jsonl`;
+}
+async function writeAuditLog(context, event) {
+    const args = isRecord(event.args) ? event.args : {};
+    const project = await resolveAuditProjectRoot(context, args);
+    const auditPath = (0, project_files_1.resolveNgManagerPath)(project.projectRoot, "audit", todayFileName());
+    const entry = {
+        time: new Date().toISOString(),
+        tool: event.tool,
+        riskLevel: event.riskLevel,
+        projectId: getString(args, "projectId") ?? project.projectId,
+        projectRoot: project.projectRoot,
+        taskId: getString(args, "taskId"),
+        status: resultStatus(event.result, event.error),
+        changedFiles: changedFilesFromResult(event.result),
+        durationMs: event.durationMs,
+        error: event.error ? (0, redact_1.redactValue)(event.error instanceof Error ? event.error.message : String(event.error)) : undefined,
+        argsSummary: summarizeAuditArgs(event.args),
+    };
+    await fs.mkdir(path.dirname(auditPath), { recursive: true });
+    await fs.appendFile(auditPath, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+function shouldAuditTool(toolName, riskLevel) {
+    return riskLevel !== "read" || toolName.startsWith("ngm_workflow_");
+}
+function auditWarning(error) {
+    return {
+        code: "AUDIT_LOG_WRITE_FAILED",
+        message: error instanceof Error ? error.message : String(error),
+    };
+}

package/lib/audit/redact.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/audit/redact.js

@@ -0,0 +1,28 @@
+"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|cookie|token|password|passwd|secret|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|env)/i;
+function redactText(value) {
+    return value
+        .replace(/(^|\n)([A-Z0-9_]*(?:TOKEN|PASSWORD|PASSWD|SECRET|API_KEY|ACCESS_TOKEN|REFRESH_TOKEN|AUTHORIZATION|COOKIE)[A-Z0-9_]*\s*=\s*)[^\r\n]+/gi, "$1$2[REDACTED]")
+        .replace(/(^|\n)(\s*[A-Za-z0-9_.-]*\.env\s*[:=]\s*)[^\r\n]+/gi, "$1$2[REDACTED]")
+        .replace(/(authorization\s*[:=]\s*)(bearer\s+)?[^\s,;]+/gi, "$1[REDACTED]")
+        .replace(/(cookie\s*[:=]\s*)[^\r\n]+/gi, "$1[REDACTED]")
+        .replace(/((?:token|password|passwd|secret|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key)\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 (typeof value !== "object" || value === null)
+        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/catalog/capabilities/blocked-local-actions.d.ts

@@ -0,0 +1 @@
+export declare const blockedLocalActions: string[];