@yinuo-ngm/mcp-server 0.1.2 → 0.1.3

package/README.md

@@ -1,69 +1,50 @@
-# @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:
+# @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
-MCP client -> packages/mcp-server -> ToolContext.services -> packages/core
+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
 ```
 
-For ng-manager local capabilities, MCP tools should prefer `packages/core`. HTTP routes, Electron IPC, CLI commands, and MCP tools should adapt the same local core services instead of duplicating business logic or calling the local Fastify API.
-
-Hub V2 tools are the exception: they may call the Hub V2 Token HTTP API because that API is the integration contract Hub V2 exposes to AI Agents and other external clients. Those tools must keep token handling inside configuration/client layers and must not accept token values as tool arguments.
-
-The MCP server must not provide arbitrary shell execution, mutate system environment settings, or remotely execute client-side commands.
-
-## Safety
-
-Tools are assigned one risk level:
-
-```text
-read
-write
-execute
-dangerous
-```
-
-Default policy:
-
-```text
-read      allowed
-write     blocked
-execute   blocked
-dangerous blocked
-```
-
-Write tools are registered only for scoped Hub V2 Personal Token workflows that require explicit tool confirmation when implemented. The server does not implement arbitrary shell execution, task start/stop/restart, git pull/checkout/commit/reset, proxy reload, runtime install/remove, file deletion, system environment mutation, or remote client command execution.
-
-## 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_UPLOAD_ROOT          Optional extra root for Hub V2 markdown image uploads.
-NGM_MCP_MAX_UPLOAD_BYTES     Max Hub V2 markdown image upload bytes. Defaults to 5242880.
-NGM_MCP_MAX_RESULT_CHARS     Max MCP text result characters. Defaults to 120000.
-NGM_MCP_ALLOW_WRITE          Enables confirmed write tools. Defaults to false.
-NGM_MCP_ALLOW_EXECUTE        Enables execute tools. Defaults to false.
-NGM_MCP_ALLOW_DANGEROUS      Enables 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:
+Workspace commands:
 
 ```bash
 npm run dev -w @yinuo-ngm/mcp-server
@@ -71,172 +52,174 @@ npm run build -w @yinuo-ngm/mcp-server
 npm run start -w @yinuo-ngm/mcp-server
 ```
 
-CLI entrypoint:
+CLI:
 
 ```bash
 ngm mcp
 ```
 
-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"
-      }
-    }
-  }
+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"
+      }
+    }
+  }
 }
 ```
 
-## Hub V2 Config
+---
+
+## 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
 
-Hub V2 tools read token configuration from MCP server configuration only. Tool schemas do not accept token arguments.
+### Nginx
 
-Configuration priority is:
+- 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
-tool args project/projectKey
-HUB_V2_* environment variables
-HUB_V2_CONFIG explicit config path
-~/.ng-manager/agent-connections.json
+read
+write
+execute
+dangerous
 ```
 
-Use `~/.ng-manager/agent-connections.json` for persistent local configuration, and `HUB_V2_*` environment variables for temporary overrides, tests, or MCP client injection. Treat `agent-connections.json` as a local secret file: do not commit it, do not pass tokens as tool arguments, and do not print full tokens in logs or Agent replies.
-
-## 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:
+Default policy:
 
 ```text
-ngm.runtime.list
-ngm.runtime.resolveForProject
+read      allowed
+write     blocked
+execute   blocked
+dangerous blocked
 ```
 
-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.
+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
 
-Hub V2:
+---
+
+## Documentation
+
+Detailed documentation is maintained under:
+
+```text
+packages/mcp-server/docs/
+```
+
+Recommended structure:
 
 ```text
-hub_v2_projects_list
-hub_v2_projects_get
-hub_v2_docs_list
-hub_v2_docs_get
-hub_v2_docs_get_by_slug
-hub_v2_issues_list
-hub_v2_issues_get
-hub_v2_issues_create
-hub_v2_issues_comment
-hub_v2_issues_update
-hub_v2_upload_markdown_image
-hub_v2_rd_list
-hub_v2_rd_get
-hub_v2_rd_stage_tasks_list
-hub_v2_rd_create
-hub_v2_rd_advance_stage
-hub_v2_rd_stage_tasks_create
-hub_v2_rd_update_progress
+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
 ```
 
-Hub V2 reads use Project Token configuration and writes use Personal Token configuration. `hub_v2_upload_markdown_image` uploads image files for Markdown bodies and returns a snippet that can be inserted into RD descriptions, RD stage-task descriptions, Issue descriptions, or Issue comments before calling the matching create/comment tool. Prefer `HUB_V2_*` environment variables for temporary overrides and `~/.ng-manager/agent-connections.json` for persistent local configuration.
-
-
-## 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.
+---
+
+## 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[];