@agent-plan/mcp 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -1,3 +1,22 @@
 #!/usr/bin/env node
+type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+};
+/**
+ * Claude Code gives the agent only `structuredContent` when a result has
+ * one, and drops `content[].text`. Anything a tool says in text — a handoff
+ * body, a phase work map, task-start context, an advisory — would never
+ * reach the agent. So every result with a structured part also carries its
+ * text there, as `text`. `content` keeps the text for clients that read
+ * only that. Applied once, to every tool, by the registerTool wrapper below;
+ * no handler needs to know.
+ */
+export declare function foldTextIntoStructured<T extends ToolResult>(result: T): T;
 export declare function startStdioServer(): Promise<void>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA8jGA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA4BA,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA2LrI;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAUzE;AAs2FD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -5,7 +5,7 @@ import * as z from "zod/v4";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
-import { PlanStore, PlanStoreError, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, runtimeCapabilities, runtimePackagesDiagnostic, markCanonicalFullReadForSessionId, contextReadEligibilityForSession, requirementReadEligibilityForSession, hasValidSessionAttestation, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, taskStartGateState, taskStartGateStateLine, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, HANDOFF_COLD_START_INVENTORY_VERSION, HANDOFF_COLD_START_INVENTORY_CATEGORIES, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildMutationReply, longTextFieldLimitNotice, buildRecommendationReply, buildTaskOrderContext, taskOrderContextLine, taskCreatedPriorityFragment, findHigherPriorityOpenPhase, higherPriorityOpenPhaseAdvisory, listOpenPhaseWork, openPhaseWorkLines, boundedOpenPhaseWork, deleteFeatureCascade, evaluateTaskCompletionGate, taskCompletionChecklistRefusal, taskCompletionForceMotivationRequired, taskCompletionOverrideNote, taskCompletionMismatchLine, boundedPage, nowISO, resolveFeatureRefStrict, resolveAcceptedDecisionTarget, applyTaskLifecycleDates, handoffContractFailureReply, derivedStatusReadOnlyReply, acceptedDecisionMutationFailureReply, legacyContextMigrationSummary } from "@agent-plan/core";
+import { PlanStore, PlanStoreError, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, createStaleProcessCheck, runtimeCapabilities, runtimePackagesDiagnostic, markCanonicalFullReadForSessionId, contextReadEligibilityForSession, requirementReadEligibilityForSession, hasValidSessionAttestation, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, taskStartGateState, taskStartGateStateLine, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, HANDOFF_COLD_START_INVENTORY_VERSION, HANDOFF_COLD_START_INVENTORY_CATEGORIES, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, buildPlannerLoadReply, buildScopedDecisionContext, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildMutationReply, longTextFieldLimitNotice, buildRecommendationReply, buildTaskOrderContext, taskOrderContextLine, taskCreatedPriorityFragment, findHigherPriorityOpenPhase, higherPriorityOpenPhaseAdvisory, listOpenPhaseWork, openPhaseWorkLines, boundedOpenPhaseWork, deleteFeatureCascade, evaluateTaskCompletionGate, taskCompletionChecklistRefusal, taskCompletionForceMotivationRequired, taskCompletionOverrideNote, taskCompletionMismatchLine, boundedPage, nowISO, resolveFeatureRefStrict, resolveAcceptedDecisionTarget, applyTaskLifecycleDates, handoffContractFailureReply, derivedStatusReadOnlyReply, acceptedDecisionMutationFailureReply, legacyContextMigrationSummary } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createRequirementId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, formatIdeaRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
@@ -83,6 +83,7 @@ function mcpContextReadActions(eligibility, refs, projectGuidelinesReadRequired,
 }
 const MCP_PACKAGE = packageVersionFromModule(import.meta.url, "@agent-plan/mcp");
 const CORE_PACKAGE = resolvedPackageVersion("@agent-plan/core", import.meta.url);
+const staleServerNotice = createStaleProcessCheck(MCP_PACKAGE);
 function planRoot() {
     return process.env.AGENT_PLAN_ROOT || join(process.cwd(), ".planner");
 }
@@ -169,6 +170,44 @@ const server = new McpServer({
     name: "agent-plan-planner",
     version: MCP_PACKAGE.version,
 });
+/**
+ * Claude Code gives the agent only `structuredContent` when a result has
+ * one, and drops `content[].text`. Anything a tool says in text — a handoff
+ * body, a phase work map, task-start context, an advisory — would never
+ * reach the agent. So every result with a structured part also carries its
+ * text there, as `text`. `content` keeps the text for clients that read
+ * only that. Applied once, to every tool, by the registerTool wrapper below;
+ * no handler needs to know.
+ */
+export function foldTextIntoStructured(result) {
+    if (!result?.structuredContent)
+        return result;
+    const replyText = result.content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n\n");
+    // A reply that already uses `text` for something else is left as it is;
+    // the MCP tests fail on that, so it never ships.
+    if (!replyText || "text" in result.structuredContent)
+        return result;
+    return { ...result, structuredContent: { text: replyText, ...result.structuredContent } };
+}
+/** Add one line to a reply when this server is older than what is now
+ * installed (see createStaleProcessCheck). */
+function withStaleServerNotice(result) {
+    const notice = staleServerNotice();
+    if (!notice || !result?.content)
+        return result;
+    return { ...result, content: [...result.content, { type: "text", text: notice }] };
+}
+{
+    const registerToolUnwrapped = server.registerTool.bind(server);
+    server.registerTool = (...args) => {
+        const handler = args[args.length - 1];
+        const wrapped = async (...handlerArgs) => foldTextIntoStructured(withStaleServerNotice(await handler(...handlerArgs)));
+        return registerToolUnwrapped(...args.slice(0, -1), wrapped);
+    };
+}
 async function resolveRequirementPhaseRefs(st, refs) {
     if (!refs || refs.length === 0)
         return { ok: false, error: "linkedPhaseIds must contain at least one phase reference." };
@@ -235,7 +274,7 @@ server.registerTool("planner-export", {
     return text(`Project export generated. Summary results:\n\n${markdown.slice(0, 1000)}${markdown.length > 1000 ? "... (full report in .planner/EXPORT.md)" : ""}`);
 });
 server.registerTool("planner-authorize-bypass", {
-    description: "Authorize a temporary guard bypass (default 15 minutes) so edit/write tools can proceed even when no task is in-progress. Use ONLY after the user explicitly authorizes proceeding without a task. Harness-agnostic: stored in resume.json so all adapters (Pi, Claude Code, Codex, ...) respect it.",
+    description: "Authorize a temporary guard bypass (default 15 minutes) that silences the no-task warning. Edits are never blocked; this only stops the agent being warned when it changes project code with no task in-progress. Use ONLY after the user explicitly authorizes working without a task. Harness-agnostic: stored in resume.json so all adapters (Pi, Claude Code, Codex, ...) respect it.",
     inputSchema: {
         durationMinutes: z.number().optional().describe("Bypass window in minutes. Default 15."),
     },
@@ -3079,7 +3118,7 @@ server.registerTool("planner-web", {
     return text("planner-web not running. Use planner-web with action=start to start the dashboard.", { running: false, address: "", localUrl: "", lanUrl: "", host: "", port: 0, mode: "" });
 });
 server.registerTool("planner-load", {
-    description: "Load/refresh the planner on explicit user request (NOT automatic): starts the web dashboard on LAN and returns a consolidated human-facing recap, plus agent-only structuredContent carrying the complete project-level context (description, goal, scope, out-of-scope, technologies, tools, language preferences, Project Guidelines, every Requirement, and every project Accepted Decision, in structuredContent.projectContext and structuredContent.agentContext.projectContext) and bounded canonical Accepted Decision agentContext for feature/phase/task scopes. This is the MCP equivalent of Pi /planner load. Call it ONLY when the user runs /planner load or /planner recap (or asks to load the planner). Present ONLY structuredContent.recap.text (equivalently, the text content) verbatim to the user, including its final prominent Web UI line — never quote projectContext or agentContext in the human-facing recap. If structuredContent.projectContext.contextComplete is false, the project-level context was NOT delivered this turn — follow structuredContent.projectContext.nextActions and retry before relying on it. A pending handoff is read-only context: NEVER call planner-handoff-show or planner-handoff-clear as part of load/recap. Archive it only when every phase task is done/canceled, when replacing it with a new handoff, or after an explicit user handoff-clear request. Do NOT start the planner/web or show the web URL unless the user explicitly asks (load/recap/web status).",
+    description: "Load/refresh the planner on explicit user request (NOT automatic): starts the web dashboard on LAN and returns one text with, in order: a recap under '## Recap — show this to the user verbatim', then agent-only context under '## Agent-only context' (the complete project-level context — description, goal, scope, out-of-scope, technologies, tools, language preferences, Project Guidelines, every Requirement, every project Accepted Decision — then Accepted Decisions of features, phases and tasks, then where the Agent Plan operating guide lives). Call it ONLY when the user runs /planner load or /planner recap (or asks to load the planner). Show the user ONLY the recap section, verbatim, including its final Web UI line; never quote the agent-only context. If structuredContent.projectContext.contextComplete is false, the project-level context was NOT delivered — follow structuredContent.projectContext.nextActions and retry before relying on it. A pending handoff is read-only context: NEVER call planner-handoff-show or planner-handoff-clear as part of load/recap. Archive it only when every phase task is done/canceled, when replacing it with a new handoff, or after an explicit user handoff-clear request. Do NOT start the planner/web or show the web URL unless the user explicitly asks (load/recap/web status).",
     inputSchema: {
         maxChars: z.number().int().positive().optional().describe(`Single-response bound (chars) for the project-context delivery. Default ${DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS}. Raise this and retry if a prior call returned projectContext.contextComplete=false.`),
     },
@@ -3104,50 +3143,29 @@ server.registerTool("planner-load", {
     const web = await ensureWebStarted();
     const recap = await buildRecap(st, web, { harness: "mcp" });
     const plan = await st.loadAll();
-    const acceptedDecisionContext = buildBoundedAcceptedDecisionContext([
-        { scope: "project", decisions: plan.project.acceptedDecisions },
-        ...plan.features.features.map((feature) => ({ scope: `feature ${formatFeatureRef(feature.number)}`, decisions: feature.acceptedDecisions })),
-        ...plan.phases.map((phase) => ({ scope: `phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}`, decisions: phase.acceptedDecisions })),
-        ...plan.phases.flatMap((phase) => phase.tasks.map((task) => ({
-            scope: `task ${taskCompositeRef(task, phase, plan.features.features)}`,
-            decisions: task.acceptedDecisions,
-        }))),
-    ]);
     // Explicit planner load must deliver the complete project-level context
     // (P102(F005)/T404), attested through the same lossless contract used
     // everywhere else: loadProjectContextDelivery + recordProjectContextRead.
-    // buildProjectContextLoadReply is the single shared shaping for this reply
-    // (Pi's planner-load and /planner load use the identical builder).
     const boundedMaxChars = maxChars ?? DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS;
     const projectContextDelivery = await st.loadProjectContextDelivery(boundedMaxChars);
     const projectContextReply = buildProjectContextLoadReply(projectContextDelivery, boundedMaxChars);
     if (projectContextReply.structured.contextComplete) {
         await st.recordProjectContextRead({ sessionId: plannerSessionId, chunks: projectContextDelivery.chunks });
     }
-    const visibleRecap = preparation.changed ? `${preparation.legacyProjectContext.summary}\n\n${recap}` : recap;
-    return {
-        // The project-context text (like the planner skill and Accepted Decision
-        // context below) is agent-only: read and retain it, but never quote it
-        // or the Accepted Decisions it contains in the human-facing recap.
-        content: [{ type: "text", text: visibleRecap }],
-        structuredContent: {
-            loaded: true,
-            recap: { text: visibleRecap },
-            projectContext: projectContextReply.structured,
-            webUi: plannerWebMetadata(web),
-            preparation: preparation.legacyProjectContext,
-            agentContext: {
-                kind: "planner-usage-skill",
-                content: plannerSkill.content,
-                status: plannerSkill.status,
-                customized: plannerSkill.customized,
-                message: plannerSkill.message,
-                instruction: "Read and retain this project-local planner usage skill, project context, and Accepted Decision context. Do not quote it, the project context, or the Accepted Decision context in the human-facing recap.",
-                projectContext: { text: projectContextReply.text },
-                acceptedDecisions: acceptedDecisionContext,
-            },
-        },
-    };
+    // One text, each piece once (shared with Pi via buildPlannerLoadReply).
+    // The guide body is not resent: the /planner command already carries it,
+    // and a bare planner-load call is pointed at the project-local copy.
+    const reply = buildPlannerLoadReply({
+        recap: preparation.changed ? `${preparation.legacyProjectContext.summary}\n\n${recap}` : recap,
+        projectContext: projectContextReply,
+        scopedDecisions: buildScopedDecisionContext(plan),
+        plannerGuide: { mode: "pointer", path: ".planner/SKILL.md", customized: plannerSkill.customized, message: plannerSkill.message },
+    });
+    return text(reply.text, {
+        ...reply.structured,
+        webUi: plannerWebMetadata(web),
+        preparation: preparation.legacyProjectContext,
+    });
 });
 server.registerTool("planner-disable", {
     description: "MCP no-op equivalent of Pi /planner disable. Stop the MCP process from the host to disable it.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "MCP server for Agent Plan, exposing planner-* tools over stdio.",
   "license": "MIT",
@@ -43,8 +43,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.3.0",
-    "@agent-plan/server": "0.3.0"
+    "@agent-plan/core": "0.3.1",
+    "@agent-plan/server": "0.3.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",