@agent-plan/mcp 0.2.19-next.18 → 0.2.19-next.19

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA+pCA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA2rCA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import * as z from "zod/v4";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, migrateToGlobalSequence, addChecklistItem, removeChecklistItem, toggleChecklistItem } from "@agent-plan/core";
+import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, migrateToGlobalSequence, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, validateResolvedTarget } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
@@ -560,30 +560,26 @@ server.registerTool("planner-feature-delete", {
     return writeAndSummarize(st, `Feature deleted: ${feature.id}${cascade ? `; deleted ${phases.length} phases` : `; unlinked ${phases.length} phases`}`, { deleted: feature.id, affectedPhases: phases.length, cascade: Boolean(cascade) });
 });
 server.registerTool("planner-phase-add", {
-    description: "Create a phase with a rich description. REQUIRED: description must include code references (file:line), current implementation state, dependencies, specific files/systems to modify, and behaviors to preserve. The description is the primary context for future agents; one-liners cause misalignment.",
+    description: "Create a phase linked to a feature with a rich description. REQUIRED: feature ref and description. The description must include code references (file:line), current implementation state, dependencies, specific files/systems to modify, and behaviors to preserve. The description is the primary context for future agents; one-liners cause misalignment.",
     inputSchema: {
         title: z.string().min(1),
-        feature: z.string().optional().describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
+        feature: z.string().min(1).optional().describe("Feature ref (required). Accepts F00x/P00x/T00x composite, bare F00x (global), 5-char shortId, UUID, or title."),
         summary: z.string().optional().describe("One-line summary of the phase"),
         description: z.string().min(50, "Description must be at least 50 characters — include code references (file:line), current state, structs/traits involved, concrete work items, behaviors to preserve. Prefix with 'design-only' for pre-implementation design tasks.").describe("Required code references (file:line), current state, structs/traits involved, concrete work items, behaviors to preserve. Not a one-liner."),
     },
 }, async ({ title, feature: featureRef, summary, description }) => {
     const st = await requireStore();
+    if (!featureRef?.trim())
+        return text("feature is required: a phase must belong to a feature.");
     const featuresDoc = await st.loadFeatures();
-    let feature;
-    if (featureRef) {
-        const resolvedFeature = resolveFeatureRefStrict(featuresDoc.features, featureRef);
-        if (!resolvedFeature.ok)
-            return text(resolvedFeature.error);
-        const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
-        if (!featureValidation.ok)
-            return text(featureValidation.error);
-        feature = resolvedFeature.feature;
-    }
-    else {
-        feature = featuresDoc.features[0];
-    }
-    if (featureRef && !feature)
+    const resolvedFeature = resolveFeatureRefStrict(featuresDoc.features, featureRef);
+    if (!resolvedFeature.ok)
+        return text(resolvedFeature.error);
+    const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
+    if (!featureValidation.ok)
+        return text(featureValidation.error);
+    const feature = resolvedFeature.feature;
+    if (!feature)
         return text(`Resolved feature ${featureRef} no longer exists. Refusing to create phase.`);
     const lockKey = feature?.id ?? "__unscoped__";
     let phase;
@@ -753,16 +749,31 @@ server.registerTool("planner-phase-delete", {
 server.registerTool("planner-task-add", {
     description: "Create a task with a rich description. REQUIRED: description must include code references (file:line), what already exists vs what needs to be built, specific structs/traits/systems to modify, concrete implementation steps, and edge cases to handle. The description is the execution context for agents; one-liners cause misalignment.",
     inputSchema: {
+        feature: z.string().min(1).optional().describe("Feature ref the task's phase belongs to. Accepts F00x/P00x/T00x composite, bare F00x (global), 5-char shortId, UUID, or title. REQUIRED."),
         phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         title: z.string().min(1),
         description: z.string().min(50, "Description must be at least 50 characters — include code references (file:line), current state vs desired state, structs/traits to modify, concrete implementation steps, edge cases. Prefix with 'design-only' for pre-implementation design tasks.").describe("Required code references (file:line), current state vs desired state, structs/traits to modify, concrete implementation steps, edge cases. Not a one-liner."),
         checklist: z.array(z.string()).optional(),
     },
-}, async ({ phase: ref, title, description, checklist }) => {
+}, async ({ feature: featureRef, phase: ref, title, description, checklist }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
+    const features = (await st.loadFeatures()).features;
+    if (!featureRef?.trim())
+        return text("feature is required: a task must belong to a feature.");
+    const resolvedFeature = resolveFeatureRefStrict(features, featureRef);
+    if (!resolvedFeature.ok)
+        return text(resolvedFeature.error);
+    const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
+    if (!featureValidation.ok)
+        return text(featureValidation.error);
+    const feature = resolvedFeature.feature;
+    if (!feature)
+        return text(`Resolved feature ${featureRef} no longer exists. Refusing to create task.`);
+    const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
+    if (found.featureId !== feature.id)
+        return text(`Phase ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} does not belong to feature ${formatFeatureRef(feature.number)}. Refusing to create task.`);
     const phaseValidation = await validateResolvedTarget("phase", found.id, () => st.loadPhase(found.id).catch(() => undefined));
     if (!phaseValidation.ok)
         return text(phaseValidation.error);
@@ -801,8 +812,8 @@ server.registerTool("planner-task-add", {
         entry.updatedAt = timestamp;
         return entry;
     });
-    const features = (await st.loadFeatures()).features;
-    return writeAndSummarize(st, `✅ Task created: ${taskCompositeRef(task, found, features)} — ${task.title} (planned)${task.shortId ? ` · ${task.shortId}` : ""}`);
+    const finalFeatures = (await st.loadFeatures()).features;
+    return writeAndSummarize(st, `✅ Task created: ${taskCompositeRef(task, found, finalFeatures)} — ${task.title} (planned)${task.shortId ? ` · ${task.shortId}` : ""}`);
 });
 server.registerTool("planner-task-show", {
     description: "Show a task by id or name.",
@@ -1043,7 +1054,7 @@ server.registerTool("planner-task-start", {
     let handoffNotice = "";
     if ((found.phase.handoff ?? "") !== "") {
         await st.clearPhaseHandoff(found.phase.id, "task-started").catch(() => { });
-        handoffNotice = "📦 Archived handoff for this phase (task started) — recover via planner-handoff-list + .planner/handoff-archive/.\n";
+        handoffNotice = "📦 Archived handoff for this phase (task started) — recover via planner-handoff-list + .planner/.local/handoff-archive/.\n";
     }
     const _otherHandoffs = allHandoffs.filter((h) => h.phaseId !== found.phase.id);
     if (_otherHandoffs.length > 0) {
@@ -1075,7 +1086,9 @@ server.registerTool("planner-task-start", {
     await st.syncTaskStatusRollup(found.phase.id);
     const features = (await st.loadFeatures()).features;
     const t = updatedTask ?? found.task;
-    return writeAndSummarize(st, `${handoffNotice}✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}`);
+    const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
+    const phaseContext = buildPhaseContextBlock(found.phase, parentFeature);
+    return writeAndSummarize(st, `${handoffNotice}✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}${phaseContext}`);
 });
 server.registerTool("planner-task-complete", {
     description: "Set a task to done. Fails if checklist is incomplete unless force=true.",
@@ -1148,23 +1161,44 @@ server.registerTool("planner-handoff-show", {
     return text(`Handoff for ${r.compositeRef}:\n\n${content}`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-handoff-write", {
-    description: "Write/refresh the entity-scoped handoff on a phase. Pass content (markdown). phaseRef optional (default: current in-progress phase). Captures design context for a resuming agent on that phase.",
+    description: "Write/refresh the entity-scoped handoff on a phase. Pass content (markdown) AND a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring'). The title becomes the H1 / first line shown in handoff lists; generic titles like 'Handoff' or 'Canonical handoff' are REJECTED. phaseRef optional (default: current in-progress phase). Captures design context for a resuming agent on that phase.",
     inputSchema: {
         phaseRef: z.string().optional().describe("Phase ref. Default: current in-progress phase."),
+        title: z.string().min(3).optional().describe("Meaningful handoff title summarizing the work (becomes the H1 / first line in lists). REQUIRED if your markdown's first heading is generic. Example: 'P049 — featureId validation: tests + adapter wiring'."),
         content: z.string().min(1).describe("Handoff text (markdown)."),
     },
-}, async ({ phaseRef, content }) => {
+}, async ({ phaseRef, title, content }) => {
     const st = await requireStore();
+    let body = content.trim();
+    const firstLine = body.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
+    const firstHeadingText = firstLine.replace(/^#+\s*/, "").trim();
+    const isGeneric = !firstHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(firstHeadingText);
+    if (!title && isGeneric) {
+        return text("❌ Generic handoff title. Provide a meaningful `title` (or start your markdown with a descriptive H1) summarizing the work — e.g. 'P049 — featureId validation: tests + adapter wiring'. Generic titles like 'Handoff' or 'Canonical handoff' are not accepted.");
+    }
+    if (title && title.trim()) {
+        const t = title.trim();
+        const lines = body.split(/\r?\n/);
+        const firstIdx = lines.findIndex((l) => l.trim().length > 0);
+        if (firstIdx !== -1 && /^#+\s/.test(lines[firstIdx] ?? "")) {
+            lines[firstIdx] = `# ${t}`;
+            body = lines.join("\n");
+        }
+        else {
+            body = `# ${t}\n\n${body}`;
+        }
+    }
     const r = await resolvePhaseForHandoff(st, phaseRef);
     if (!r.ok)
         return text(`❌ ${r.error}`);
-    await st.setPhaseHandoff(r.phase.id, content);
+    await st.setPhaseHandoff(r.phase.id, body);
     return text(`✅ Wrote handoff on ${r.compositeRef}.`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-handoff-prepare", {
     description: "Return instructions for the agent to prepare a canonical handoff, then call planner-handoff-write (entity-scoped, phase.handoff).",
 }, async () => text([
     "Prepare the canonical session handoff and write it on the current in-progress phase with planner-handoff-write (omit phaseRef to target the in-progress phase).",
+    "Pass a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring') — it becomes the H1 / first line in handoff lists. Generic titles like 'Handoff' or 'Canonical handoff' are REJECTED.",
     "Required sections: Created at, Updated at, Reason, Current focus, What was being done, How to resume, Files touched, Blockers, Next steps, Recent decisions, Reminder.",
     "Stored on the phase.handoff field (entity-scoped). .planner/HANDOFF.md is deprecated.",
 ].join("\n")));
@@ -1177,7 +1211,7 @@ server.registerTool("planner-handoff-clear", {
     if (!r.ok)
         return text(`❌ ${r.error}`);
     await st.clearPhaseHandoff(r.phase.id, "manual");
-    return text(`✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/handoff-archive/).`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
+    return text(`✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/.local/handoff-archive/).`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-web", {
     description: "Manage the planner web dashboard (start/status/stop) from MCP stdio. Runs an in-process HTTP+WS server bound to LAN; it lives as long as this MCP process. plan-root comes from AGENT_PLAN_ROOT or cwd()/.planner.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.2.19-next.18",
+  "version": "0.2.19-next.19",
   "private": false,
   "description": "MCP server for Agent Plan, exposing planner-* tools over stdio.",
   "license": "MIT",
@@ -17,9 +17,11 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "server.json",
     "README.md",
     "LICENSE"
   ],
+  "mcpName": "io.github.ovidius72/agent-plan",
   "publishConfig": {
     "access": "public"
   },
@@ -41,8 +43,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.2.19-next.18",
-    "@agent-plan/server": "0.2.19-next.18"
+    "@agent-plan/core": "0.2.19-next.19",
+    "@agent-plan/server": "0.2.19-next.19"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/server.json

@@ -0,0 +1,15 @@
+{
+  "name": "io.github.ovidius72/agent-plan",
+  "version": "0.2.19-next.18",
+  "description": "MCP server for Agent Plan, exposing planner-* tools over stdio.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ovidius72/agent-planner.git"
+  },
+  "homepage": "https://github.com/ovidius72/agent-planner#readme",
+  "package": {
+    "type": "npm",
+    "name": "@agent-plan/mcp"
+  }
+}