@yinuo-ngm/mcp-server 0.1.1 → 0.1.2

package/README.md

@@ -6,13 +6,17 @@ This package is an AI Agent adapter layer. It is not a business core, not a Fast
 
 ## 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.
+The intended boundary is:
+
+```text
+MCP client -> packages/mcp-server -> ToolContext.services -> packages/core
+```
+
+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
 
@@ -34,16 +38,19 @@ 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.
+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_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.
+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
@@ -56,19 +63,25 @@ 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:
+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
+```
+
+CLI entrypoint:
+
+```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
 {
@@ -109,12 +122,27 @@ Development:
       }
     }
   }
-}
-```
-
-## Tools
-
-Project:
+}
+```
+
+## Hub V2 Config
+
+Hub V2 tools read token configuration from MCP server configuration only. Tool schemas do not accept token arguments.
+
+Configuration priority is:
+
+```text
+tool args project/projectKey
+HUB_V2_* environment variables
+HUB_V2_CONFIG explicit config path
+~/.ng-manager/agent-connections.json
+```
+
+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
@@ -145,23 +173,49 @@ 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:
+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
+In this package, "proxy" means ng-manager's current Nginx/proxy management domain, not the operating system global proxy.
+
+Hub V2:
+
+```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
+```
+
+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:
 

package/lib/register-tools.js

@@ -15,13 +15,17 @@ function registerTools(server, context) {
             inputSchema: tool.inputSchema,
         }, async (args) => {
             try {
-                (0, assert_tool_policy_1.assertToolPolicy)(policy, tool.name, tool.riskLevel);
                 const parsed = tool.inputSchema.parse(args);
+                const confirmed = tool.isConfirmed?.(parsed) ?? true;
+                const isAllowedPreview = tool.allowPreviewWhenBlocked === true && !confirmed;
+                if (!isAllowedPreview) {
+                    (0, assert_tool_policy_1.assertToolPolicy)(policy, tool.name, tool.riskLevel);
+                }
                 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)));
+                return (0, result_1.toMcpTextResult)((0, result_1.fail)(tool.name, (0, errors_1.errorMessage)(error), (0, errors_1.errorMetadata)(error)));
             }
         });
     }

package/lib/tools/hub-v2/client.d.ts

@@ -0,0 +1,15 @@
+import type { HubV2ResolvedContext } from "./config";
+export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+export declare class HubV2Client {
+    private readonly context;
+    constructor(context: HubV2ResolvedContext);
+    tokenUrl(suffix: string, query?: Record<string, unknown>): string;
+    personalUrl(suffix: string, query?: Record<string, unknown>): string;
+    request<T = unknown>(method: HttpMethod, url: string, body?: Record<string, unknown>, options?: {
+        preserveNull?: boolean;
+    }): Promise<T>;
+    multipart<T = unknown>(method: "POST", url: string, body: FormData): Promise<T>;
+    private queryUrl;
+}
+export declare function compact(values: Record<string, unknown>): Record<string, unknown>;
+export declare function compactUndefined(values: Record<string, unknown>): Record<string, unknown>;

package/lib/tools/hub-v2/client.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubV2Client = void 0;
+exports.compact = compact;
+exports.compactUndefined = compactUndefined;
+const errors_1 = require("./errors");
+class HubV2Client {
+    constructor(context) {
+        this.context = context;
+    }
+    tokenUrl(suffix, query) {
+        return this.queryUrl("api/token", suffix, query);
+    }
+    personalUrl(suffix, query) {
+        return this.queryUrl("api/personal", suffix, query);
+    }
+    async request(method, url, body, options = {}) {
+        const headers = { Authorization: `Bearer ${this.context.token}` };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(options.preserveNull ? compactUndefined(body) : compact(body));
+        }
+        const response = await fetch(url, init);
+        const text = await response.text();
+        const parsed = parseResponseBody(text);
+        if (!response.ok) {
+            throw (0, errors_1.toHubV2HttpError)(response.status, response.statusText, parsed);
+        }
+        return (parsed ?? { code: "OK", data: null });
+    }
+    async multipart(method, url, body) {
+        const response = await fetch(url, {
+            method,
+            headers: { Authorization: `Bearer ${this.context.token}` },
+            body,
+        });
+        const text = await response.text();
+        const parsed = parseResponseBody(text);
+        if (!response.ok) {
+            throw (0, errors_1.toHubV2HttpError)(response.status, response.statusText, parsed);
+        }
+        return (parsed ?? { code: "OK", data: null });
+    }
+    queryUrl(prefix, suffix, query) {
+        let url = `${this.context.baseUrl}/${prefix}/projects/${encodeURIComponent(this.context.projectKey)}${suffix}`;
+        const queryString = toQueryString(query ?? {});
+        if (queryString) {
+            url += `?${queryString}`;
+        }
+        return url;
+    }
+}
+exports.HubV2Client = HubV2Client;
+function compact(values) {
+    const result = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function compactUndefined(values) {
+    const result = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined && !(Array.isArray(value) && value.length === 0)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function toQueryString(values) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(compact(values))) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(key, String(item));
+            }
+        }
+        else {
+            params.set(key, String(value));
+        }
+    }
+    return params.toString();
+}
+function parseResponseBody(text) {
+    if (!text.trim()) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/lib/tools/hub-v2/config.d.ts

@@ -0,0 +1,34 @@
+export type HubV2ProjectConfig = {
+    name?: string;
+    alias?: string;
+    id?: string;
+    base_url?: string;
+    project_key?: string;
+    project_name?: string;
+    project_token?: string;
+    personal_token?: string;
+    source?: string;
+};
+export type HubV2Config = HubV2ProjectConfig & {
+    default_project?: string;
+    projects?: Record<string, HubV2ProjectConfig>;
+};
+export type HubV2ResolveOptions = {
+    project?: string;
+    projectKey?: string;
+};
+export type HubV2ResolvedContext = {
+    baseUrl: string;
+    projectKey: string;
+    token: string;
+    source: string;
+};
+type TokenKind = "project" | "personal";
+export declare function parseJsonObject(content: string): Record<string, unknown>;
+export declare function loadJsonFile(path: string): Record<string, unknown>;
+export declare function normalizeConfig(rawValue: unknown): HubV2Config;
+export declare function loadConfig(pathValue?: string): HubV2Config;
+export declare function resolveHubV2Context(options: HubV2ResolveOptions, tokenKind: TokenKind, pathValue?: string): HubV2ResolvedContext;
+export declare function listConfiguredProjects(project?: string, pathValue?: string): Record<string, unknown>;
+export declare function getConfiguredProject(options: HubV2ResolveOptions, pathValue?: string): Record<string, unknown>;
+export {};

package/lib/tools/hub-v2/config.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonObject = parseJsonObject;
+exports.loadJsonFile = loadJsonFile;
+exports.normalizeConfig = normalizeConfig;
+exports.loadConfig = loadConfig;
+exports.resolveHubV2Context = resolveHubV2Context;
+exports.listConfiguredProjects = listConfiguredProjects;
+exports.getConfiguredProject = getConfiguredProject;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function getString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return String(value).trim();
+        }
+    }
+    return undefined;
+}
+function putIfValue(target, key, value) {
+    if (value !== undefined && value !== null && String(value).trim()) {
+        target[key] = String(value).trim();
+    }
+}
+function envValue(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return String(value).trim();
+        }
+    }
+    return undefined;
+}
+function stripJsonComments(input) {
+    let output = "";
+    let inString = false;
+    let stringQuote = "";
+    let escaped = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        const next = input[index + 1];
+        if (inString) {
+            output += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === stringQuote) {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            inString = true;
+            stringQuote = char;
+            output += char;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            while (index < input.length && input[index] !== "\n") {
+                index += 1;
+            }
+            output += "\n";
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            index += 2;
+            while (index < input.length && !(input[index] === "*" && input[index + 1] === "/")) {
+                index += 1;
+            }
+            index += 1;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+function parseJsonObject(content) {
+    const parsed = JSON.parse(stripJsonComments(content));
+    return asRecord(parsed);
+}
+function loadJsonFile(path) {
+    if (!(0, fs_1.existsSync)(path)) {
+        return {};
+    }
+    return parseJsonObject((0, fs_1.readFileSync)(path, "utf8"));
+}
+function mergeHubObject(target, value) {
+    const source = asRecord(value);
+    putIfValue(target, "base_url", getString(source, "base_url", "baseUrl"));
+    putIfValue(target, "project_key", getString(source, "project_key", "projectKey"));
+    putIfValue(target, "project_name", getString(source, "project_name", "projectName"));
+    putIfValue(target, "project_token", getString(source, "project_token", "projectToken", "token"));
+    putIfValue(target, "personal_token", getString(source, "personal_token", "personalToken"));
+    putIfValue(target, "source", getString(source, "source"));
+    putIfValue(target, "default_project", getString(source, "default_project", "defaultProject", "project"));
+}
+function mergeEnvObject(target, value) {
+    const env = asRecord(value);
+    putIfValue(target, "base_url", getString(env, "HUB_V2_BASE_URL"));
+    putIfValue(target, "project_key", getString(env, "HUB_V2_PROJECT_KEY"));
+    putIfValue(target, "project_token", getString(env, "HUB_V2_PROJECT_TOKEN"));
+    putIfValue(target, "personal_token", getString(env, "HUB_V2_PERSONAL_TOKEN"));
+    putIfValue(target, "source", getString(env, "HUB_V2_SOURCE"));
+    putIfValue(target, "default_project", getString(env, "HUB_V2_PROJECT"));
+}
+function normalizeProject(raw) {
+    const config = normalizeConfig(raw);
+    const record = asRecord(raw);
+    putIfValue(config, "name", record.name);
+    putIfValue(config, "alias", record.alias);
+    putIfValue(config, "id", record.id);
+    delete config.projects;
+    delete config.default_project;
+    return config;
+}
+function normalizeProjects(raw) {
+    const value = raw.projects;
+    const projects = {};
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        for (const [name, projectValue] of Object.entries(value)) {
+            const project = normalizeProject(projectValue);
+            const projectName = project.name ?? project.alias ?? name.trim();
+            if (projectName) {
+                projects[projectName] = project;
+            }
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const projectValue of value) {
+            const project = normalizeProject(projectValue);
+            const projectName = project.name ?? project.alias ?? project.id;
+            if (projectName) {
+                projects[projectName] = project;
+            }
+        }
+    }
+    return projects;
+}
+function mergeProjects(...maps) {
+    const merged = {};
+    for (const map of maps) {
+        for (const [name, project] of Object.entries(map)) {
+            merged[name] = { ...(merged[name] ?? {}), ...project };
+        }
+    }
+    return merged;
+}
+function normalizeConfig(rawValue) {
+    const raw = asRecord(rawValue);
+    const normalized = {};
+    mergeHubObject(normalized, raw);
+    mergeHubObject(normalized, raw.hubV2);
+    mergeEnvObject(normalized, raw.env);
+    const projects = mergeProjects(normalizeProjects(raw), normalizeProjects(asRecord(raw.hubV2)));
+    if (Object.keys(projects).length) {
+        normalized.projects = projects;
+    }
+    return normalized;
+}
+function configSearchPaths() {
+    const envConfig = envValue("HUB_V2_CONFIG");
+    if (envConfig) {
+        return [(0, path_1.resolve)(envConfig)];
+    }
+    return [(0, path_1.join)((0, os_1.homedir)(), ".ng-manager", "agent-connections.json")];
+}
+function loadConfig(pathValue) {
+    const paths = pathValue ? [(0, path_1.resolve)(pathValue)] : configSearchPaths();
+    for (const path of paths) {
+        const config = normalizeConfig(loadJsonFile(path));
+        if (Object.keys(config).length) {
+            return config;
+        }
+    }
+    return {};
+}
+function selectedProjectConfig(config, options) {
+    const projects = config.projects ?? {};
+    const entries = Object.entries(projects);
+    if (!entries.length) {
+        return {};
+    }
+    const selected = options.project ?? envValue("HUB_V2_PROJECT") ?? config.default_project;
+    if (selected) {
+        const project = projects[selected];
+        if (!project) {
+            throw new Error(`project config not found: ${selected}. Available projects: ${entries.map(([name]) => name).sort().join(", ")}`);
+        }
+        return project;
+    }
+    if (entries.length === 1) {
+        return entries[0][1];
+    }
+    throw new Error(`multiple projects configured; pass project. Available projects: ${entries.map(([name]) => name).sort().join(", ")}`);
+}
+function configValue(config, projectConfig, key) {
+    return projectConfig[key] ?? config[key];
+}
+function resolveHubV2Context(options, tokenKind, pathValue) {
+    const config = loadConfig(pathValue);
+    const projectConfig = selectedProjectConfig(config, options);
+    const baseUrl = (envValue("HUB_V2_BASE_URL") ??
+        configValue(config, projectConfig, "base_url"))?.replace(/\/+$/, "");
+    const projectKey = options.projectKey ??
+        envValue("HUB_V2_PROJECT_KEY") ??
+        configValue(config, projectConfig, "project_key");
+    const projectToken = envValue("HUB_V2_PROJECT_TOKEN") ??
+        configValue(config, projectConfig, "project_token");
+    const personalToken = envValue("HUB_V2_PERSONAL_TOKEN") ??
+        configValue(config, projectConfig, "personal_token");
+    const source = envValue("HUB_V2_SOURCE") ??
+        configValue(config, projectConfig, "source") ??
+        "ngm-mcp";
+    if (!baseUrl) {
+        throw new Error("HUB_V2_BASE_URL is required");
+    }
+    if (!projectKey) {
+        throw new Error("HUB_V2_PROJECT_KEY is required");
+    }
+    const token = tokenKind === "project" ? projectToken : personalToken;
+    if (!token) {
+        throw new Error(tokenKind === "project" ? "HUB_V2_PROJECT_TOKEN is required" : "HUB_V2_PERSONAL_TOKEN is required");
+    }
+    return { baseUrl, projectKey, token, source };
+}
+function projectSummary(name, config, project) {
+    return {
+        name,
+        projectName: project.project_name,
+        projectKey: project.project_key,
+        baseUrl: project.base_url ?? config.base_url,
+        hasProjectToken: Boolean(project.project_token ?? config.project_token),
+        hasPersonalToken: Boolean(project.personal_token ?? config.personal_token),
+        isDefault: name === config.default_project,
+    };
+}
+function listConfiguredProjects(project, pathValue) {
+    const config = loadConfig(pathValue);
+    const envProjectKey = envValue("HUB_V2_PROJECT_KEY") ?? config.project_key;
+    let items;
+    if (envProjectKey) {
+        items = [
+            {
+                name: envValue("HUB_V2_PROJECT") ?? config.default_project ?? "default",
+                projectName: config.project_name,
+                projectKey: envProjectKey,
+                baseUrl: envValue("HUB_V2_BASE_URL") ?? config.base_url,
+                hasProjectToken: Boolean(envValue("HUB_V2_PROJECT_TOKEN") ?? config.project_token),
+                hasPersonalToken: Boolean(envValue("HUB_V2_PERSONAL_TOKEN") ?? config.personal_token),
+                isDefault: true,
+            },
+        ];
+    }
+    else {
+        const projects = config.projects ?? {};
+        items = Object.entries(projects).map(([name, item]) => projectSummary(name, config, item));
+    }
+    const filtered = project
+        ? items.filter((item) => item.name === project || item.projectName === project || item.projectKey === project)
+        : items;
+    return {
+        items: filtered,
+        total: filtered.length,
+    };
+}
+function getConfiguredProject(options, pathValue) {
+    const config = loadConfig(pathValue);
+    const selected = options.project ?? options.projectKey ?? envValue("HUB_V2_PROJECT") ?? config.default_project;
+    if (selected) {
+        const projects = listConfiguredProjects(selected, pathValue).items;
+        if (projects.length === 1) {
+            return projects[0];
+        }
+        if (!projects.length) {
+            throw new Error("Hub V2 project config not found");
+        }
+        throw new Error("multiple Hub V2 project configs matched");
+    }
+    const projects = listConfiguredProjects(options.project ?? options.projectKey, pathValue).items;
+    if (projects.length === 1) {
+        return projects[0];
+    }
+    if (!projects.length) {
+        throw new Error("Hub V2 project config not found");
+    }
+    throw new Error("multiple Hub V2 project configs matched");
+}

package/lib/tools/hub-v2/docs.tools.d.ts

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