@yinuo-ngm/mcp-server 0.1.1 → 0.1.2

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

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rdUpdateProgressSchema = exports.rdStageTaskCreateSchema = exports.rdStageTasksListSchema = exports.rdAdvanceStageSchema = exports.rdCreateSchema = exports.rdGetSchema = exports.rdListSchema = exports.markdownImageUploadSchema = exports.issueUpdateSchema = exports.issueCommentSchema = exports.issueCreateSchema = exports.issueGetSchema = exports.issuesListSchema = exports.docsGetBySlugSchema = exports.docsGetSchema = exports.docsListSchema = exports.pagingSchema = exports.projectSelectorSchema = void 0;
+const zod_1 = require("zod");
+exports.projectSelectorSchema = zod_1.z.object({
+    project: zod_1.z.string().trim().min(1).optional(),
+    projectKey: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+exports.pagingSchema = zod_1.z.object({
+    page: zod_1.z.number().int().min(1).optional(),
+    pageSize: zod_1.z.number().int().min(1).max(200).optional(),
+}).strict();
+exports.docsListSchema = exports.projectSelectorSchema.extend({
+    page: zod_1.z.number().int().min(1).optional(),
+    pageSize: zod_1.z.number().int().min(1).max(200).optional(),
+    status: zod_1.z.enum(["draft", "published", "archived"]).optional(),
+    keyword: zod_1.z.string().trim().min(1).optional(),
+    category: zod_1.z.string().trim().min(1).optional(),
+    categoryId: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+exports.docsGetSchema = exports.projectSelectorSchema.extend({
+    docId: zod_1.z.string().trim().min(1),
+}).strict();
+exports.docsGetBySlugSchema = exports.projectSelectorSchema.extend({
+    slug: zod_1.z.string().trim().min(1),
+    contentOnly: zod_1.z.boolean().optional(),
+}).strict();
+exports.issuesListSchema = exports.projectSelectorSchema.extend({
+    page: zod_1.z.number().int().min(1).optional(),
+    pageSize: zod_1.z.number().int().min(1).max(200).optional(),
+    keyword: zod_1.z.string().trim().min(1).optional(),
+    status: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    priority: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    assigneeId: zod_1.z.string().trim().min(1).optional(),
+    verifierId: zod_1.z.string().trim().min(1).optional(),
+    rdItemId: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+exports.issueGetSchema = exports.projectSelectorSchema.extend({
+    issueId: zod_1.z.string().trim().min(1),
+}).strict();
+const issueTypeSchema = zod_1.z.enum(["bug", "feature", "change", "improvement", "task", "test"]);
+const issuePrioritySchema = zod_1.z.enum(["low", "medium", "high", "critical"]);
+exports.issueCreateSchema = exports.projectSelectorSchema.extend({
+    title: zod_1.z.string().trim().min(1),
+    description: zod_1.z.string().optional(),
+    type: issueTypeSchema.optional(),
+    priority: issuePrioritySchema.optional(),
+    assigneeId: zod_1.z.string().trim().nullable().optional(),
+    verifierId: zod_1.z.string().trim().nullable().optional(),
+    rdItemId: zod_1.z.string().trim().nullable().optional(),
+    moduleCode: zod_1.z.string().trim().optional(),
+    versionCode: zod_1.z.string().trim().optional(),
+    environmentCode: zod_1.z.string().trim().optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.issueCommentSchema = exports.projectSelectorSchema.extend({
+    issueId: zod_1.z.string().trim().min(1),
+    content: zod_1.z.string().min(1),
+    mentions: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.issueUpdateSchema = exports.projectSelectorSchema.extend({
+    issueId: zod_1.z.string().trim().min(1),
+    title: zod_1.z.string().trim().optional(),
+    description: zod_1.z.string().nullable().optional(),
+    type: issueTypeSchema.optional(),
+    priority: issuePrioritySchema.optional(),
+    rdItemId: zod_1.z.string().trim().nullable().optional(),
+    moduleCode: zod_1.z.string().trim().nullable().optional(),
+    versionCode: zod_1.z.string().trim().nullable().optional(),
+    environmentCode: zod_1.z.string().trim().nullable().optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.markdownImageUploadSchema = exports.projectSelectorSchema.extend({
+    filePath: zod_1.z.string().trim().min(1).optional(),
+    contentBase64: zod_1.z.string().trim().min(1).optional(),
+    fileName: zod_1.z.string().trim().min(1).optional(),
+    mimeType: zod_1.z.string().trim().min(1).optional(),
+    alt: zod_1.z.string().trim().min(1).optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.rdListSchema = exports.projectSelectorSchema.extend({
+    page: zod_1.z.number().int().min(1).optional(),
+    pageSize: zod_1.z.number().int().min(1).max(200).optional(),
+    keyword: zod_1.z.string().trim().min(1).optional(),
+    stageId: zod_1.z.string().trim().min(1).optional(),
+    status: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    type: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    priority: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    assigneeId: zod_1.z.string().trim().min(1).optional(),
+}).strict();
+exports.rdGetSchema = exports.projectSelectorSchema.extend({
+    itemId: zod_1.z.string().trim().min(1),
+}).strict();
+const rdTypeSchema = zod_1.z.enum([
+    "feature_dev",
+    "tech_refactor",
+    "integration",
+    "env_setup",
+    "bug_fix",
+    "requirement_confirmation",
+    "solution_design",
+    "testing_validation",
+    "delivery_launch",
+    "project_closure",
+]);
+const rdPrioritySchema = zod_1.z.enum(["low", "medium", "high", "critical"]);
+const rdInitialStageTaskSchema = zod_1.z.object({
+    templateId: zod_1.z.string().trim().min(1).nullable().optional(),
+    title: zod_1.z.string().trim().min(1),
+    description: zod_1.z.string().trim().nullable().optional(),
+    ownerId: zod_1.z.string().trim().nullable().optional(),
+    plannedStartAt: zod_1.z.string().trim().nullable().optional(),
+    plannedEndAt: zod_1.z.string().trim().nullable().optional(),
+}).strict();
+const rdStageTaskTemplateSelectionSchema = zod_1.z.object({
+    templateId: zod_1.z.string().trim().min(1),
+    ownerId: zod_1.z.string().trim().nullable().optional(),
+}).strict();
+exports.rdCreateSchema = exports.projectSelectorSchema.extend({
+    title: zod_1.z.string().trim().min(1),
+    description: zod_1.z.string().optional(),
+    stageId: zod_1.z.string().trim().nullable().optional(),
+    type: rdTypeSchema.optional(),
+    priority: rdPrioritySchema.optional(),
+    memberIds: zod_1.z.array(zod_1.z.string().trim().min(1)).min(1),
+    verifierId: zod_1.z.string().trim().nullable().optional(),
+    planStartAt: zod_1.z.string().trim().optional(),
+    planEndAt: zod_1.z.string().trim().optional(),
+    stageTasks: zod_1.z.array(rdInitialStageTaskSchema).optional(),
+    stageTaskTemplates: zod_1.z.array(rdStageTaskTemplateSelectionSchema).optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.rdAdvanceStageSchema = exports.projectSelectorSchema.extend({
+    itemId: zod_1.z.string().trim().min(1),
+    stageId: zod_1.z.string().trim().min(1),
+    memberIds: zod_1.z.array(zod_1.z.string().trim().min(1)).optional(),
+    description: zod_1.z.string().trim().min(1).optional(),
+    planStartAt: zod_1.z.string().trim().min(1).optional(),
+    planEndAt: zod_1.z.string().trim().min(1).optional(),
+    stageTasks: zod_1.z.array(rdInitialStageTaskSchema).optional(),
+    stageTaskTemplates: zod_1.z.array(rdStageTaskTemplateSelectionSchema).optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.rdStageTasksListSchema = exports.projectSelectorSchema.extend({
+    itemId: zod_1.z.string().trim().min(1),
+}).strict();
+exports.rdStageTaskCreateSchema = exports.projectSelectorSchema.extend({
+    itemId: zod_1.z.string().trim().min(1),
+    title: zod_1.z.string().trim().min(1).max(200),
+    description: zod_1.z.string().trim().max(2000).nullable().optional(),
+    ownerIds: zod_1.z.array(zod_1.z.string().trim().min(1)).min(1),
+    plannedStartAt: zod_1.z.string().trim().nullable().optional(),
+    plannedEndAt: zod_1.z.string().trim().nullable().optional(),
+    sortOrder: zod_1.z.number().int().optional(),
+    remark: zod_1.z.string().trim().max(1000).nullable().optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();
+exports.rdUpdateProgressSchema = exports.projectSelectorSchema.extend({
+    itemId: zod_1.z.string().trim().min(1),
+    progress: zod_1.z.number().int().min(0).max(100),
+    note: zod_1.z.string().trim().optional(),
+    blockReason: zod_1.z.string().trim().min(1).max(500).optional(),
+    resolveBlockId: zod_1.z.string().trim().min(1).optional(),
+    stageTaskId: zod_1.z.string().trim().min(1).optional(),
+    confirm: zod_1.z.boolean().optional(),
+}).strict();

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

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

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

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubV2UploadTools = hubV2UploadTools;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const client_1 = require("./client");
+const config_1 = require("./config");
+const schemas_1 = require("./schemas");
+const result_1 = require("../../utils/result");
+function hubV2UploadTools() {
+    return [
+        {
+            name: "hub_v2_upload_markdown_image",
+            description: "Upload a local or base64 image with Personal Token and return Markdown for Hub V2 content.",
+            riskLevel: "write",
+            inputSchema: schemas_1.markdownImageUploadSchema,
+            allowPreviewWhenBlocked: true,
+            isConfirmed: (args) => args.confirm === true,
+            async handler(args) {
+                const path = "/uploads/markdown";
+                if (!args.confirm) {
+                    return (0, result_1.ok)("hub_v2_upload_markdown_image", {
+                        code: "PREVIEW",
+                        message: "set confirm=true to upload this image",
+                        data: {
+                            method: "POST",
+                            path,
+                            requiredScope: "issue:create:write or issue:update:write or issue:comment:write or rd:create:write or rd:stage-task:write or rd:transition:write or rd:edit:write",
+                            maxBytes: maxUploadBytes(),
+                            input: {
+                                mode: args.filePath ? "filePath" : "contentBase64",
+                                fileName: args.fileName,
+                                mimeType: args.mimeType,
+                                alt: args.alt,
+                                hasFilePath: Boolean(args.filePath),
+                                hasContentBase64: Boolean(args.contentBase64),
+                            },
+                        },
+                    });
+                }
+                const ctx = (0, config_1.resolveHubV2Context)(args, "personal");
+                const client = new client_1.HubV2Client(ctx);
+                const file = resolveUploadFile(args);
+                const form = new FormData();
+                const bytes = new Uint8Array(file.content.byteLength);
+                bytes.set(file.content);
+                form.append("file", new Blob([bytes], { type: file.mimeType }), file.fileName);
+                if (args.alt) {
+                    form.append("alt", args.alt);
+                }
+                const data = await client.multipart("POST", client.personalUrl("/uploads/markdown"), form);
+                return (0, result_1.ok)("hub_v2_upload_markdown_image", data);
+            },
+        },
+    ];
+}
+function resolveUploadFile(args) {
+    if (Boolean(args.filePath) === Boolean(args.contentBase64)) {
+        throw new Error("provide exactly one of filePath or contentBase64");
+    }
+    if (args.filePath) {
+        const resolvedPath = node_path_1.default.resolve(args.filePath);
+        assertAllowedFilePath(resolvedPath);
+        if (!(0, node_fs_1.existsSync)(resolvedPath) || !(0, node_fs_1.statSync)(resolvedPath).isFile()) {
+            throw new Error(`upload file not found: ${resolvedPath}`);
+        }
+        const fileSize = (0, node_fs_1.statSync)(resolvedPath).size;
+        assertUploadSize(fileSize);
+        return {
+            content: (0, node_fs_1.readFileSync)(resolvedPath),
+            fileName: node_path_1.default.basename(resolvedPath),
+            mimeType: args.mimeType ?? inferMimeType(resolvedPath),
+        };
+    }
+    const fileName = args.fileName?.trim();
+    if (!args.contentBase64 || !fileName) {
+        throw new Error("contentBase64 and fileName are required");
+    }
+    const content = decodeBase64Content(args.contentBase64);
+    return {
+        content,
+        fileName,
+        mimeType: args.mimeType ?? inferMimeType(fileName),
+    };
+}
+function maxUploadBytes() {
+    const value = Number.parseInt(String(process.env.NGM_MCP_MAX_UPLOAD_BYTES ?? ""), 10);
+    return Number.isFinite(value) && value > 0 ? value : 5 * 1024 * 1024;
+}
+function assertUploadSize(fileSize) {
+    const maxBytes = maxUploadBytes();
+    if (fileSize > maxBytes) {
+        throw new Error(`upload image is too large: ${fileSize} bytes exceeds NGM_MCP_MAX_UPLOAD_BYTES=${maxBytes}`);
+    }
+}
+function decodeBase64Content(value) {
+    const normalized = value.trim().replace(/^data:[^,]+,/, "").replace(/\s+/g, "");
+    if (!normalized) {
+        throw new Error("contentBase64 is empty");
+    }
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(normalized) || normalized.length % 4 !== 0) {
+        throw new Error("contentBase64 is not a valid base64 string");
+    }
+    const firstPaddingIndex = normalized.indexOf("=");
+    if (firstPaddingIndex !== -1 && !/^={1,2}$/.test(normalized.slice(firstPaddingIndex))) {
+        throw new Error("contentBase64 is not a valid base64 string");
+    }
+    const content = Buffer.from(normalized, "base64");
+    if (content.byteLength === 0) {
+        throw new Error("contentBase64 is empty");
+    }
+    assertUploadSize(content.byteLength);
+    return content;
+}
+function assertAllowedFilePath(filePath) {
+    const roots = [
+        process.env.NGM_WORKSPACE_ROOT,
+        process.env.NGM_MCP_UPLOAD_ROOT,
+        process.cwd(),
+    ]
+        .map((item) => item?.trim())
+        .filter((item) => Boolean(item))
+        .map((item) => node_path_1.default.resolve(item));
+    const allowed = roots.some((root) => filePath === root || filePath.startsWith(`${root}${node_path_1.default.sep}`));
+    if (!allowed) {
+        throw new Error("filePath must be under NGM_WORKSPACE_ROOT, NGM_MCP_UPLOAD_ROOT, or the current workspace");
+    }
+}
+function inferMimeType(fileName) {
+    switch (node_path_1.default.extname(fileName).toLowerCase()) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        case ".bmp":
+            return "image/bmp";
+        case ".svg":
+            return "image/svg+xml";
+        default:
+            return "application/octet-stream";
+    }
+}

package/lib/tools/index.d.ts

@@ -7,6 +7,8 @@ export type McpToolDefinition<TSchema extends z.AnyZodObject = z.AnyZodObject> =
     description: string;
     riskLevel: ToolRiskLevel;
     inputSchema: TSchema;
+    allowPreviewWhenBlocked?: boolean;
+    isConfirmed?: (args: z.infer<TSchema>) => boolean;
     handler(args: z.infer<TSchema>, context: ToolContext): Promise<ToolResult> | ToolResult;
 };
 export declare function allTools(): McpToolDefinition[];

package/lib/tools/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allTools = allTools;
 const git_tools_1 = require("./git.tools");
+const hub_v2_1 = require("./hub-v2");
 const log_tools_1 = require("./log.tools");
 const project_tools_1 = require("./project.tools");
 const proxy_tools_1 = require("./proxy.tools");
@@ -15,5 +16,6 @@ function allTools() {
         ...(0, git_tools_1.gitTools)(),
         ...(0, runtime_tools_1.runtimeTools)(),
         ...(0, proxy_tools_1.proxyTools)(),
+        ...(0, hub_v2_1.hubV2Tools)(),
     ];
 }

package/lib/utils/errors.d.ts

@@ -1 +1,6 @@
 export declare function errorMessage(error: unknown): string;
+export declare function errorMetadata(error: unknown): {
+    code?: string;
+    status?: number;
+    detail?: unknown;
+};

package/lib/utils/errors.js

@@ -1,9 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.errorMessage = errorMessage;
+exports.errorMetadata = errorMetadata;
 function errorMessage(error) {
     if (error instanceof Error && error.message) {
         return error.message;
     }
     return String(error ?? "Unknown error");
 }
+function errorMetadata(error) {
+    if (!error || typeof error !== "object") {
+        return {};
+    }
+    const record = error;
+    return {
+        code: typeof record.code === "string" ? record.code : undefined,
+        status: typeof record.status === "number" ? record.status : undefined,
+        detail: record.detail,
+    };
+}

package/lib/utils/result.d.ts

@@ -7,10 +7,19 @@ export type ToolErrorResult = {
     ok: false;
     tool: string;
     error: string;
+    code?: string;
+    status?: number;
+    detail?: unknown;
+};
+export type ToolResult<T = unknown> = (ToolSuccessResult<T> | ToolErrorResult) & {
+    truncated?: true;
 };
-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 fail(tool: string, error: string, metadata?: {
+    code?: string;
+    status?: number;
+    detail?: unknown;
+}): ToolErrorResult;
 export declare function toMcpTextResult(result: ToolResult): {
     content: Array<{
         type: "text";

package/lib/utils/result.js

@@ -6,16 +6,112 @@ exports.toMcpTextResult = toMcpTextResult;
 function ok(tool, data) {
     return { ok: true, tool, data };
 }
-function fail(tool, error) {
-    return { ok: false, tool, error };
+function fail(tool, error, metadata = {}) {
+    return {
+        ok: false,
+        tool,
+        error,
+        ...(metadata.code ? { code: metadata.code } : {}),
+        ...(metadata.status ? { status: metadata.status } : {}),
+        ...(metadata.detail !== undefined ? { detail: metadata.detail } : {}),
+    };
 }
 function toMcpTextResult(result) {
+    const maxChars = maxResultChars();
+    const text = JSON.stringify(result, null, 2);
+    if (text.length <= maxChars) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+        };
+    }
+    const truncatedText = stringifyWithinLimit((preview) => buildTruncatedResult(result, text.length, preview), text, maxChars);
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify(result, null, 2),
+                text: truncatedText,
             },
         ],
     };
 }
+function maxResultChars() {
+    const value = Number.parseInt(String(process.env.NGM_MCP_MAX_RESULT_CHARS ?? ""), 10);
+    return Number.isFinite(value) && value > 0 ? value : 120000;
+}
+function buildTruncatedResult(result, originalLength, preview) {
+    if (result.ok) {
+        return {
+            ok: true,
+            tool: result.tool,
+            truncated: true,
+            data: {
+                originalLength,
+                preview,
+            },
+        };
+    }
+    return {
+        ok: false,
+        tool: result.tool,
+        error: result.error,
+        code: result.code,
+        status: result.status,
+        truncated: true,
+        detail: {
+            originalLength,
+            preview,
+        },
+    };
+}
+function stringifyWithinLimit(build, sourceText, maxChars) {
+    let previewLength = Math.min(sourceText.length, Math.max(0, maxChars - 1000));
+    while (previewLength >= 0) {
+        const text = JSON.stringify(build(sourceText.slice(0, previewLength)), null, 2);
+        if (text.length <= maxChars) {
+            return text;
+        }
+        if (previewLength === 0) {
+            break;
+        }
+        previewLength = Math.max(0, Math.floor(previewLength / 2));
+    }
+    return minimalTruncatedJson(maxChars);
+}
+function minimalTruncatedJson(maxChars) {
+    const buildWithDetail = (error) => JSON.stringify({
+        ok: false,
+        tool: "mcp",
+        error,
+        truncated: true,
+        detail: {
+            originalLength: null,
+        },
+    });
+    let error = "MCP result exceeded NGM_MCP_MAX_RESULT_CHARS";
+    let text = buildWithDetail(error);
+    while (text.length > maxChars && error.length > 0) {
+        error = error.slice(0, -1);
+        text = buildWithDetail(error);
+    }
+    if (text.length <= maxChars) {
+        return text;
+    }
+    const buildMinimal = (minimalError) => JSON.stringify({
+        ok: false,
+        tool: "mcp",
+        error: minimalError,
+        truncated: true,
+    });
+    error = "MCP result truncated";
+    text = buildMinimal(error);
+    while (text.length > maxChars && error.length > 0) {
+        error = error.slice(0, -1);
+        text = buildMinimal(error);
+    }
+    return text.length <= maxChars ? text : "{}";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yinuo-ngm/mcp-server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local MCP stdio server for ng-manager core capabilities.",
   "author": "ZhangJing <892295834@qq.com>",
   "license": "ISC",
@@ -22,20 +22,24 @@
     "node": ">=18"
   },
   "scripts": {
+    "inspect": "npm run build && mcp-inspector node lib/index.js",
+    "inspect:dev": "mcp-inspector tsx src/index.ts",
     "dev": "tsx watch src/index.ts",
     "build": "tsc -b tsconfig.json",
+    "test": "npm run build && node --test test",
     "start": "node lib/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@yinuo-ngm/core": "^0.1.14",
+    "@yinuo-ngm/core": "^0.1.15",
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.15.0",
     "tsx": "^4.21.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f64135f6db80de6928bc0b83c29c26e408e9fcfb"
+  "gitHead": "9c45bd57798a539e3b6cf40dd56f7cdffdc02589"
 }