@harness-engineering/mcp-server 0.5.3 → 0.6.0

package/dist/src/tools/roadmap.js

@@ -0,0 +1,390 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { resultToMcpResponse } from '../utils/result-adapter.js';
+import { sanitizePath } from '../utils/sanitize-path.js';
+export const manageRoadmapDefinition = {
+    name: 'manage_roadmap',
+    description: 'Manage the project roadmap: show, add, update, remove, sync features, or query by filter. Reads and writes docs/roadmap.md.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to project root' },
+            action: {
+                type: 'string',
+                enum: ['show', 'add', 'update', 'remove', 'query', 'sync'],
+                description: 'Action to perform',
+            },
+            feature: { type: 'string', description: 'Feature name (required for add, update, remove)' },
+            milestone: {
+                type: 'string',
+                description: 'Milestone name (required for add; optional filter for show)',
+            },
+            status: {
+                type: 'string',
+                enum: ['backlog', 'planned', 'in-progress', 'done', 'blocked'],
+                description: 'Feature status (required for add; optional for update; optional filter for show)',
+            },
+            summary: {
+                type: 'string',
+                description: 'Feature summary (required for add; optional for update)',
+            },
+            spec: { type: 'string', description: 'Spec file path (optional for add/update)' },
+            plans: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Plan file paths (optional for add/update)',
+            },
+            blocked_by: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Blocking feature names (optional for add/update)',
+            },
+            filter: {
+                type: 'string',
+                description: 'Query filter: "blocked", "in-progress", "done", "planned", "backlog", or "milestone:<name>" (required for query)',
+            },
+            apply: {
+                type: 'boolean',
+                description: 'For sync action: apply proposed changes (default: false, preview only)',
+            },
+            force_sync: {
+                type: 'boolean',
+                description: 'For sync action: override human-always-wins rule',
+            },
+        },
+        required: ['path', 'action'],
+    },
+};
+function roadmapPath(projectRoot) {
+    return path.join(projectRoot, 'docs', 'roadmap.md');
+}
+function readRoadmapFile(projectRoot) {
+    const filePath = roadmapPath(projectRoot);
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function writeRoadmapFile(projectRoot, content) {
+    const filePath = roadmapPath(projectRoot);
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+export async function handleManageRoadmap(input) {
+    try {
+        const { parseRoadmap, serializeRoadmap, syncRoadmap } = await import('@harness-engineering/core');
+        const { Ok } = await import('@harness-engineering/types');
+        const projectPath = sanitizePath(input.path);
+        switch (input.action) {
+            case 'show': {
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                let roadmap = result.value;
+                // Apply milestone filter
+                if (input.milestone) {
+                    const milestoneFilter = input.milestone;
+                    roadmap = {
+                        ...roadmap,
+                        milestones: roadmap.milestones.filter((m) => m.name.toLowerCase() === milestoneFilter.toLowerCase()),
+                    };
+                }
+                // Apply status filter
+                if (input.status) {
+                    const statusFilter = input.status;
+                    roadmap = {
+                        ...roadmap,
+                        milestones: roadmap.milestones
+                            .map((m) => ({
+                            ...m,
+                            features: m.features.filter((f) => f.status === statusFilter),
+                        }))
+                            .filter((m) => m.features.length > 0),
+                    };
+                }
+                return resultToMcpResponse(Ok(roadmap));
+            }
+            case 'add': {
+                if (!input.feature) {
+                    return {
+                        content: [{ type: 'text', text: 'Error: feature is required for add action' }],
+                        isError: true,
+                    };
+                }
+                if (!input.milestone) {
+                    return {
+                        content: [
+                            { type: 'text', text: 'Error: milestone is required for add action' },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (!input.status) {
+                    return {
+                        content: [{ type: 'text', text: 'Error: status is required for add action' }],
+                        isError: true,
+                    };
+                }
+                if (!input.summary) {
+                    return {
+                        content: [{ type: 'text', text: 'Error: summary is required for add action' }],
+                        isError: true,
+                    };
+                }
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                const roadmap = result.value;
+                const milestone = roadmap.milestones.find((m) => m.name.toLowerCase() === input.milestone.toLowerCase());
+                if (!milestone) {
+                    return {
+                        content: [
+                            { type: 'text', text: `Error: milestone "${input.milestone}" not found` },
+                        ],
+                        isError: true,
+                    };
+                }
+                milestone.features.push({
+                    name: input.feature,
+                    status: input.status,
+                    spec: input.spec ?? null,
+                    plans: input.plans ?? [],
+                    blockedBy: input.blocked_by ?? [],
+                    summary: input.summary,
+                });
+                // Update last_manual_edit timestamp
+                roadmap.frontmatter.lastManualEdit = new Date().toISOString();
+                writeRoadmapFile(projectPath, serializeRoadmap(roadmap));
+                return resultToMcpResponse(Ok(roadmap));
+            }
+            case 'update': {
+                if (!input.feature) {
+                    return {
+                        content: [
+                            { type: 'text', text: 'Error: feature is required for update action' },
+                        ],
+                        isError: true,
+                    };
+                }
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                const roadmap = result.value;
+                let found = false;
+                for (const m of roadmap.milestones) {
+                    const feature = m.features.find((f) => f.name.toLowerCase() === input.feature.toLowerCase());
+                    if (feature) {
+                        if (input.status)
+                            feature.status = input.status;
+                        if (input.summary !== undefined)
+                            feature.summary = input.summary;
+                        if (input.spec !== undefined)
+                            feature.spec = input.spec || null;
+                        if (input.plans !== undefined)
+                            feature.plans = input.plans;
+                        if (input.blocked_by !== undefined)
+                            feature.blockedBy = input.blocked_by;
+                        found = true;
+                        break;
+                    }
+                }
+                if (!found) {
+                    return {
+                        content: [
+                            { type: 'text', text: `Error: feature "${input.feature}" not found` },
+                        ],
+                        isError: true,
+                    };
+                }
+                roadmap.frontmatter.lastManualEdit = new Date().toISOString();
+                writeRoadmapFile(projectPath, serializeRoadmap(roadmap));
+                return resultToMcpResponse(Ok(roadmap));
+            }
+            case 'remove': {
+                if (!input.feature) {
+                    return {
+                        content: [
+                            { type: 'text', text: 'Error: feature is required for remove action' },
+                        ],
+                        isError: true,
+                    };
+                }
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                const roadmap = result.value;
+                let found = false;
+                for (const m of roadmap.milestones) {
+                    const idx = m.features.findIndex((f) => f.name.toLowerCase() === input.feature.toLowerCase());
+                    if (idx !== -1) {
+                        m.features.splice(idx, 1);
+                        found = true;
+                        break;
+                    }
+                }
+                if (!found) {
+                    return {
+                        content: [
+                            { type: 'text', text: `Error: feature "${input.feature}" not found` },
+                        ],
+                        isError: true,
+                    };
+                }
+                roadmap.frontmatter.lastManualEdit = new Date().toISOString();
+                writeRoadmapFile(projectPath, serializeRoadmap(roadmap));
+                return resultToMcpResponse(Ok(roadmap));
+            }
+            case 'query': {
+                if (!input.filter) {
+                    return {
+                        content: [
+                            { type: 'text', text: 'Error: filter is required for query action' },
+                        ],
+                        isError: true,
+                    };
+                }
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                const roadmap = result.value;
+                const allFeatures = roadmap.milestones.flatMap((m) => m.features.map((f) => ({ ...f, milestone: m.name })));
+                const filter = input.filter.toLowerCase();
+                let filtered;
+                if (filter.startsWith('milestone:')) {
+                    const milestoneName = filter.slice('milestone:'.length).trim();
+                    filtered = allFeatures.filter((f) => f.milestone.toLowerCase().includes(milestoneName));
+                }
+                else {
+                    // Treat filter as a status value
+                    filtered = allFeatures.filter((f) => f.status === filter);
+                }
+                return resultToMcpResponse(Ok(filtered));
+            }
+            case 'sync': {
+                const raw = readRoadmapFile(projectPath);
+                if (raw === null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: docs/roadmap.md not found. Create a roadmap first.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = parseRoadmap(raw);
+                if (!result.ok)
+                    return resultToMcpResponse(result);
+                const roadmap = result.value;
+                const syncResult = syncRoadmap({
+                    projectPath,
+                    roadmap,
+                    forceSync: input.force_sync ?? false,
+                });
+                if (!syncResult.ok)
+                    return resultToMcpResponse(syncResult);
+                const changes = syncResult.value;
+                if (changes.length === 0) {
+                    return resultToMcpResponse(Ok({ changes: [], message: 'Roadmap is up to date.' }));
+                }
+                if (input.apply) {
+                    // Apply changes to roadmap
+                    for (const change of changes) {
+                        for (const m of roadmap.milestones) {
+                            const feature = m.features.find((f) => f.name.toLowerCase() === change.feature.toLowerCase());
+                            if (feature) {
+                                feature.status = change.to;
+                                break;
+                            }
+                        }
+                    }
+                    roadmap.frontmatter.lastSynced = new Date().toISOString();
+                    writeRoadmapFile(projectPath, serializeRoadmap(roadmap));
+                    return resultToMcpResponse(Ok({ changes, applied: true, roadmap }));
+                }
+                return resultToMcpResponse(Ok({ changes, applied: false }));
+            }
+            default: {
+                return {
+                    content: [{ type: 'text', text: `Error: unknown action` }],
+                    isError: true,
+                };
+            }
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/src/tools/security.js

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { sanitizePath } from '../utils/sanitize-path.js';
 // ============ run_security_scan ============
 export const runSecurityScanDefinition = {
     name: 'run_security_scan',
@@ -23,7 +24,7 @@ export const runSecurityScanDefinition = {
 export async function handleRunSecurityScan(input) {
     try {
         const core = await import('@harness-engineering/core');
-        const projectRoot = path.resolve(input.path);
+        const projectRoot = sanitizePath(input.path);
         // Load config from project
         let configData = {};
         try {

package/dist/src/tools/skill.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { Ok, Err } from '@harness-engineering/core';
 import { resultToMcpResponse } from '../utils/result-adapter.js';
 import { resolveSkillsDir } from '../utils/paths.js';
+import { sanitizePath } from '../utils/sanitize-path.js';
 export const runSkillDefinition = {
     name: 'run_skill',
     description: 'Load and return the content of a skill (SKILL.md), optionally with project state context',
@@ -41,7 +42,7 @@ export async function handleRunSkill(input) {
     let content = fs.readFileSync(skillMdPath, 'utf-8');
     // Optionally inject project state context
     if (input.path) {
-        const projectPath = path.resolve(input.path);
+        const projectPath = sanitizePath(input.path);
         const stateFile = path.join(projectPath, '.harness', 'state.json');
         if (fs.existsSync(stateFile)) {
             const stateContent = fs.readFileSync(stateFile, 'utf-8');
@@ -82,7 +83,7 @@ export async function handleCreateSkill(input) {
             name: input.name,
             description: input.description,
             cognitiveMode: input.cognitiveMode ?? 'constructive-architect',
-            outputDir: path.resolve(input.path),
+            outputDir: sanitizePath(input.path),
         });
         return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }

package/dist/src/tools/state.js

@@ -1,6 +1,6 @@
-import * as path from 'path';
 import { Ok } from '@harness-engineering/core';
 import { resultToMcpResponse } from '../utils/result-adapter.js';
+import { sanitizePath } from '../utils/sanitize-path.js';
 // ── manage_state ──────────────────────────────────────────────────────
 export const manageStateDefinition = {
     name: 'manage_state',
@@ -30,7 +30,7 @@ export const manageStateDefinition = {
 export async function handleManageState(input) {
     try {
         const { loadState, saveState, appendLearning, appendFailure, archiveFailures, runMechanicalGate, DEFAULT_STATE, } = await import('@harness-engineering/core');
-        const projectPath = path.resolve(input.path);
+        const projectPath = sanitizePath(input.path);
         switch (input.action) {
             case 'show': {
                 const result = await loadState(projectPath, input.stream);
@@ -136,7 +136,7 @@ export const manageHandoffDefinition = {
 export async function handleManageHandoff(input) {
     try {
         const { saveHandoff, loadHandoff } = await import('@harness-engineering/core');
-        const projectPath = path.resolve(input.path);
+        const projectPath = sanitizePath(input.path);
         switch (input.action) {
             case 'save': {
                 if (!input.handoff) {
@@ -189,7 +189,7 @@ export const listStreamsDefinition = {
 export async function handleListStreams(input) {
     try {
         const { listStreams, loadStreamIndex } = await import('@harness-engineering/core');
-        const projectPath = path.resolve(input.path);
+        const projectPath = sanitizePath(input.path);
         const indexResult = await loadStreamIndex(projectPath);
         const streamsResult = await listStreams(projectPath);
         if (!streamsResult.ok)

package/dist/src/tools/validate.d.ts

@@ -19,4 +19,11 @@ export declare function handleValidateProject(input: {
         type: "text";
         text: string;
     }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
 }>;

package/dist/src/tools/validate.js

@@ -1,5 +1,6 @@
 import * as path from 'path';
 import { resolveProjectConfig } from '../utils/config-resolver.js';
+import { sanitizePath } from '../utils/sanitize-path.js';
 export const validateToolDefinition = {
     name: 'validate_project',
     description: 'Run all validation checks on a harness engineering project',
@@ -12,7 +13,21 @@ export const validateToolDefinition = {
     },
 };
 export async function handleValidateProject(input) {
-    const projectPath = path.resolve(input.path);
+    let projectPath;
+    try {
+        projectPath = sanitizePath(input.path);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
     const errors = [];
     const checks = {
         config: 'fail',

package/dist/src/utils/sanitize-path.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Validates and resolves an input path, rejecting filesystem root
+ * to prevent accidental broad filesystem access via MCP tools.
+ */
+export declare function sanitizePath(inputPath: string): string;

package/dist/src/utils/sanitize-path.js

@@ -0,0 +1,12 @@
+import * as path from 'path';
+/**
+ * Validates and resolves an input path, rejecting filesystem root
+ * to prevent accidental broad filesystem access via MCP tools.
+ */
+export function sanitizePath(inputPath) {
+    const resolved = path.resolve(inputPath);
+    if (resolved === '/' || resolved === path.parse(resolved).root) {
+        throw new Error('Invalid project path: cannot use filesystem root');
+    }
+    return resolved;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-engineering/mcp-server",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "MCP server for Harness Engineering toolkit",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -23,11 +23,11 @@
     "zod": "^3.22.0",
     "yaml": "^2.3.0",
     "handlebars": "^4.7.0",
-    "@harness-engineering/core": "0.8.0",
+    "@harness-engineering/core": "0.9.0",
     "@harness-engineering/graph": "0.2.2",
-    "@harness-engineering/types": "0.1.0",
-    "@harness-engineering/cli": "1.7.0",
-    "@harness-engineering/linter-gen": "0.1.1"
+    "@harness-engineering/cli": "1.8.0",
+    "@harness-engineering/linter-gen": "0.1.1",
+    "@harness-engineering/types": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",