agent-planner-mcp 1.5.17 → 1.5.19

package/SKILL.md

@@ -337,6 +337,26 @@ recall_knowledge({
 - **v0.8.x → v0.9.0** — clean break. 63 legacy CRUD tools collapsed into 15 BDI-aligned tools. See [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping.
 - **v0.9.x → v1.0.0** — additive. v0.9 read/update tools unchanged. Adds the full mutation surface (creation, structural edits, sharing, collaboration) so humans can steer entirely through agent conversation. The previously planned `ap_admin_*` namespace is no longer needed — those operations are now first-class BDI tools, with the draft-status seam keeping autonomous agent creation reviewable. See [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
+## UI vocabulary → data model → tools
+
+The web UI (agentplanner.io) and these tools are the same system in two languages. When a human refers to something they see on a screen, map it here:
+
+| UI term | What it is | Tools |
+|---|---|---|
+| **Workspace** | Org-scoped folder that owns goals + plans | `list_workspaces`, `create_workspace` |
+| **Blueprint** | Dehydrated, reusable plan shape; forks into a workspace | `list_blueprints`, `save_as_blueprint`, `fork_blueprint`, `delete_blueprint` |
+| **Mission / Mission Control** | Home overview: goal health, decision queue, activity | `briefing` |
+| **Goal** (a *Desire*) | What you're pursuing | `create_goal`, `derive_subgoal`, `list_goals`, `goal_state`, `update_goal` |
+| **Plan** (an *Intention*) | Committed plan of action that achieves a goal | `form_intention` (create), `extend_intention` (add nodes), `update_plan`, `update_node`, `move_node` |
+| **Knowledge / episode** (a *Belief*) | Facts the agents have learned | `add_learning`, `recall_knowledge` |
+| **Health** | Per-goal `on_track` / `at_risk` / `stale` | `briefing`, `list_goals`, `goal_state` |
+| **Tension / Contradiction** | A coherence conflict — new knowledge contradicts existing facts or tasks (UI "Tensions" card) | `plan_analysis` (coherence), `recall_knowledge` (current vs superseded facts) |
+| **Decision queue / "Awaiting you"** | Human approvals pending | `queue_decision`, `resolve_decision` |
+| **Committed vs Proposed** | A goal is *committed* once promoted (`promoted_at` set), *proposed* before | `update_goal({ committed })` |
+| **Attainment vs Execution** | *Attainment* = success criteria met; *Execution* = tasks completed. Distinct numbers. | `record_criterion_progress` (attainment), `update_task` (execution) |
+| **Critical path / Bottlenecks** | Longest blocking chain / high-fan-out incomplete tasks | `plan_analysis` |
+| **RPI chain** | Research → Plan → Implement decomposition | `propose_research_chain` |
+
 ## Principles
 
 - Tools are intent-shaped, not CRUD-shaped — name what you want to accomplish, not which row to mutate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.5.17",
+  "version": "1.5.19",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -3,6 +3,7 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { MCPHTTPServer } = require('./server-http');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { version } = require('../package.json');
 require('dotenv').config();
 
@@ -77,7 +78,10 @@ async function main() {
       }, {
         capabilities: {
           tools: {}
-        }
+        },
+        // Shown to the model on connect — the no-skill safety net mapping plain
+        // intents to the BDI tool names + pointing at get_started.
+        instructions: SERVER_INSTRUCTIONS
       });
 
       console.error('MCP Server created');

package/src/server-http.js

@@ -15,6 +15,7 @@
 const express = require('express');
 const { SessionManager } = require('./session-manager');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { createApiClient } = require('./api-client');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { createOAuthMetadata, mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } = require('@modelcontextprotocol/sdk/server/auth/router.js');
@@ -522,7 +523,9 @@ class MCPHTTPServer {
     }, {
       capabilities: {
         tools: {}
-      }
+      },
+      // Shown to the model on connect — the no-skill safety net (see index.js).
+      instructions: SERVER_INSTRUCTIONS
     });
 
     // Get per-session API client (bound to user's token), or create one for initialize requests

package/src/server-instructions.js

@@ -0,0 +1,26 @@
+/**
+ * Server-level MCP instructions — surfaced to the model the moment the server
+ * connects, independent of any externally-loaded skill. This is the safety net
+ * for agents that do NOT have the AgentPlanner SKILL.md: it maps plain intents
+ * to the BDI tool names (which were renamed at v0.9, e.g. "create a plan" is
+ * `form_intention`, not `create_plan`) and points to `get_started` for the rest.
+ *
+ * Keep this short — it's read on every connect. Deeper guidance lives in
+ * `get_started` (auto-derived from the live tool set, so it can't drift).
+ */
+const SERVER_INSTRUCTIONS = [
+  'AgentPlanner uses an intent-shaped, BDI-aligned tool vocabulary (renamed at v0.9 — there is no create_plan/quick_plan/create_node/quick_status).',
+  'New here or unsure which tool? Call `get_started` first — it returns the full tool map and recommended workflows.',
+  '',
+  'Common intents → tool:',
+  '- Create a goal → `create_goal` (a sub-goal → `derive_subgoal`)',
+  '- Create a plan with its task tree → `form_intention` (add tasks later → `extend_intention`; an R→P→I chain → `propose_research_chain`)',
+  '- Find and claim the next task → `claim_next_task`',
+  '- Update status / log progress / finish a task → `update_task` (folds the old quick_status + quick_log + add_log + release)',
+  '- Read a goal (details, progress, quality, bottlenecks) → `goal_state`; all goals’ health → `briefing` / `list_goals`',
+  '- Read a task in context → `task_context`; analyze a plan (critical path, bottlenecks, impact, coherence) → `plan_analysis`',
+  '- Record / recall knowledge → `add_learning` / `recall_knowledge`',
+  '- Queue a human decision → `queue_decision`; resolve one → `resolve_decision`',
+].join('\n');
+
+module.exports = { SERVER_INSTRUCTIONS };

package/src/tools/bdi/beliefs.js

@@ -617,7 +617,8 @@ const planAnalysisDefinition = {
   name: 'plan_analysis',
   description:
     "Advanced plan reads: impact analysis (delay/block/remove), critical path, " +
-    "bottleneck list, or coherence check.",
+    "bottleneck list, or coherence check. Replaces the legacy analyze_impact / " +
+    "get_critical_path / run_coherence_check / check_coherence_pending tools.",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/bdi/intentions.js

@@ -791,7 +791,10 @@ const formIntentionDefinition = {
   name: 'form_intention',
   description:
     "Create a plan that achieves a goal, including an initial phase/task " +
-    "tree, in one call. Declare execution order inline: give nodes a `ref` and " +
+    "tree, in one call. This is the canonical way to CREATE A PLAN (replaces the " +
+    "legacy quick_plan / create_plan / import_plan_markdown; inline nodes replace " +
+    "create_node / quick_task; depends_on replaces create_dependency). " +
+    "Declare execution order inline: give nodes a `ref` and " +
     "list prerequisite refs/titles in `depends_on` to create 'blocks' edges in " +
     "the same call — don't ship a bare hierarchy. The response returns a " +
     "`structure` summary and warns (`created_without_dependencies`) when a " +
@@ -961,19 +964,22 @@ async function formIntentionHandler(args, apiClient) {
     }
   }
 
-  // 3. Link plan to goal (best-effort).
+  // 3. Create tree (top-level children parent to root via omitted parent_id).
+  const nodeResults = [];
+  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
+  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
+
+  // 4. Link plan to goal (best-effort) — AFTER the tree exists. The link
+  // endpoint cascades 'achieves' edges to all CURRENT task nodes, so linking
+  // before node creation wired zero achievers (goal_state then showed empty
+  // linked_tasks and fell back to coarse linked-plan stats). Order matters.
   try {
     await apiClient.goals.linkPlan(goal_id, plan.id);
   } catch (err) {
     // Non-fatal — plan exists, link can be retried by user.
   }
 
-  // 3. Create tree (top-level children parent to root via omitted parent_id).
-  const nodeResults = [];
-  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
-  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
-
-  // 4. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
+  // 5. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
   const resolveRef = (ref) => {
     if (ctx.refMap.has(ref)) return ctx.refMap.get(ref);
     const byTitle = ctx.titleMap.get(ref);

package/src/tools/bdi/utility.js

@@ -8,9 +8,11 @@ const { version: MCP_VERSION } = require('../../../package.json');
 const getStartedDefinition = {
   name: 'get_started',
   description:
-    "Onboarding for new agents. Returns the BDI tool surface map and recommended " +
-    "workflows: mission control loop (Cowork), single-task session (Code/CLI), " +
-    "multi-agent claiming (OpenClaw).",
+    "Call this FIRST when you are new to AgentPlanner or unsure which tool to use " +
+    "(e.g. looking for create_plan / quick_plan — the answer is form_intention). " +
+    "Returns the live BDI tool-surface map and recommended workflows: mission " +
+    "control loop (Cowork), single-task session (Code/CLI), multi-agent claiming " +
+    "(OpenClaw). The map is derived from the actual tool set, so it can't drift.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -29,6 +31,17 @@ async function getStartedHandler(args, apiClient) {
     api = { version: 'unavailable' };
   }
 
+  // Derived from the actual module definitions so this map can't drift from the
+  // real tool set (it silently did — delete_blueprint and record_criterion_progress
+  // were both missing at points). Lazy require avoids any load-order cycle.
+  const namesOf = (mod) => (mod.definitions || []).map((d) => d.name);
+  const toolsByNamespace = {
+    beliefs: namesOf(require('./beliefs')),
+    desires: namesOf(require('./desires')),
+    intentions: namesOf(require('./intentions')),
+    workspaces: namesOf(require('./workspaces')),
+  };
+
   return formatResponse({
     as_of: asOf(),
     mcp_version: MCP_VERSION,
@@ -39,12 +52,7 @@ async function getStartedHandler(args, apiClient) {
       "AgentPlanner exposes a BDI-aligned MCP surface. Tools are grouped by " +
       "Beliefs (state queries), Desires (goals), and Intentions (committed actions). " +
       "Each tool answers one whole agentic question and returns an `as_of` timestamp.",
-    tools_by_namespace: {
-      beliefs: ['briefing', 'list_plans', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
-      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal', 'record_criterion_progress'],
-      intentions: ['form_intention', 'extend_intention', 'link_intentions', 'propose_research_chain', 'claim_next_task', 'update_task', 'update_node', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
-      workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint', 'delete_blueprint'],
-    },
+    tools_by_namespace: toolsByNamespace,
     recommended_workflows: [
       {
         name: 'Set up new work a human asked for',