agent-planner-mcp 0.5.1 → 0.6.1

package/AGENT_GUIDE.md

@@ -17,9 +17,9 @@ This guide is optimized for AI agents using AgentPlanner MCP tools.
 
 ### Before Starting Work
 ```javascript
-get_context({ plan_id: "..." })
+get_plan_context({ plan_id: "..." })
 ```
-Returns: statistics, blocked tasks, in-progress tasks, ready tasks, knowledge
+Returns: plan overview, phase summaries, linked goals, knowledge
 
 ### Update Task Status
 ```javascript
@@ -244,7 +244,7 @@ Key rules:
 
 ## Best Practices
 
-1. **Use `get_task_context` instead of `get_context`** - progressive depth gives you exactly what you need
+1. **Use `get_task_context` for task work, `get_plan_context` for plan overview** - progressive depth gives you exactly what you need
 2. **Check dependencies before starting** - use `suggest_next_tasks` to find what's ready
 3. **Log as you work** - helps humans and future agents follow
 4. **Record important findings** - use `add_learning` after research, decisions, and discoveries

package/SKILL.md

@@ -110,7 +110,6 @@ Each suggestion includes a `reason` field explaining why it's recommended.
 | `delete_node` | Delete a node and its children |
 | `move_node` | Reparent or reorder a node |
 | `batch_update_nodes` | Update multiple nodes at once |
-| `get_node_context` | Detailed node info with children and logs |
 | `get_node_ancestry` | Path from root to node |
 
 When creating nodes:
@@ -150,12 +149,9 @@ Cycle detection is automatic — you cannot create a dependency that would form
 
 | Tool | Purpose |
 |------|---------|
-| `get_task_context` | **Preferred.** Progressive context at depth 1-4 with token budgeting |
+| `get_task_context` | **Primary.** Progressive context at depth 1-4 with token budgeting |
+| `get_plan_context` | Plan overview with phase summaries and knowledge |
 | `suggest_next_tasks` | Find ready tasks based on dependency analysis |
-| `understand_context` | Full situation overview for a plan or goal (see Orientation) |
-| `get_plan_context` | Plan overview with phase summaries |
-| `get_agent_context` | Legacy leaf-up context (use `get_task_context` instead) |
-| `get_context` | Legacy full-plan context (use `get_task_context` or `understand_context` instead) |
 
 ### Logging
 
@@ -261,11 +257,10 @@ Use `get_recent_episodes` to review what has been learned recently across all pl
 | Tool | Purpose |
 |------|---------|
 | `get_started` | Guidance on how to use AgentPlanner — call when new or unsure how to approach a task |
-| `understand_context` | Comprehensive context about a plan or goal (purpose, state, activity, blockers, knowledge) |
 
 `get_started` accepts an optional `topic`: `overview`, `planning`, `execution`, `knowledge`, or `collaboration`.
 
-`understand_context` accepts `plan_id` and/or `goal_id` — use it before starting work on an unfamiliar plan or goal to get the full picture in one call.
+To understand a plan before starting, use `get_plan_context({ plan_id })` for the overview, then `get_task_context({ node_id, depth: 4 })` for deep context on a specific task.
 
 ### Other
 
@@ -325,9 +320,10 @@ When to use RPI vs. a single task:
 ### Starting a New Session
 ```
 1. get_my_tasks({}) → see what's in progress or blocked across all plans
-2. get_recent_episodes({ max_episodes: 10 }) → review what was learned/decided recently across all plans
-3. If resuming: get_task_context({ node_id: "...", depth: 2 })
-4. If starting fresh: suggest_next_tasks({ plan_id: "..." })
+2. get_recent_episodes({ max_episodes: 10 }) → review recent knowledge across all plans
+3. If resuming a task: get_task_context({ node_id: "...", depth: 2 })
+4. If orienting on a plan: get_plan_context({ plan_id: "..." })
+5. If starting fresh: suggest_next_tasks({ plan_id: "..." })
 ```
 
 ### Breaking Down a Large Task

package/package.json

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

package/src/tools.js

@@ -182,18 +182,6 @@ function setupTools(server, apiClientOverride) {
         // CONTEXT LOADING - Get everything you need
         // Use before starting work on a plan/goal
         // ========================================
-        {
-          name: "get_context",
-          description: "Load EVERYTHING you need to work on a plan or goal: structure, status, progress, blocked tasks, recent activity, and relevant knowledge. Call this FIRST before starting work.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              plan_id: { type: "string", description: "Plan to get context for" },
-              goal_id: { type: "string", description: "Goal to get context for" },
-              include_knowledge: { type: "boolean", default: true, description: "Include relevant knowledge entries" }
-            }
-          }
-        },
         {
           name: "get_my_tasks",
           description: "Get tasks that need attention - blocked tasks, in-progress tasks, and next tasks to start. Perfect for status check-ins.",
@@ -297,14 +285,19 @@ function setupTools(server, apiClientOverride) {
         // ===== PLAN MANAGEMENT TOOLS =====
         {
           name: "list_plans",
-          description: "List all plans or filter by status",
+          description: "List plans. By default excludes completed/archived plans — set include_completed to true to see all.",
           inputSchema: {
             type: "object",
             properties: {
-              status: { 
-                type: "string", 
+              status: {
+                type: "string",
                 description: "Optional filter by plan status",
                 enum: ["draft", "active", "completed", "archived"]
+              },
+              include_completed: {
+                type: "boolean",
+                description: "If true, include completed and archived plans (default: false)",
+                default: false
               }
             }
           }
@@ -474,18 +467,6 @@ function setupTools(server, apiClientOverride) {
             required: ["plan_id", "node_id"]
           }
         },
-        {
-          name: "get_node_context",
-          description: "Get comprehensive context for a node including children and logs",
-          inputSchema: {
-            type: "object",
-            properties: {
-              plan_id: { type: "string", description: "Plan ID" },
-              node_id: { type: "string", description: "Node ID" }
-            },
-            required: ["plan_id", "node_id"]
-          }
-        },
         {
           name: "get_node_ancestry",
           description: "Get the path from root to a specific node",
@@ -742,7 +723,7 @@ function setupTools(server, apiClientOverride) {
         // ===== PLAN STRUCTURE & SUMMARY =====
         {
           name: "get_plan_structure",
-          description: "Get the hierarchical structure of a plan with minimal fields (id, parent_id, node_type, title, status, order_index). Use get_node_context for detailed information about specific nodes.",
+          description: "Get the hierarchical structure of a plan with minimal fields (id, parent_id, node_type, title, status, order_index). Use get_task_context for detailed information about specific nodes.",
           inputSchema: {
             type: "object",
             properties: {
@@ -769,33 +750,9 @@ function setupTools(server, apiClientOverride) {
         },
         
         // ===== AGENT CONTEXT TOOLS (Leaf-up context loading) =====
-        {
-          name: "get_agent_context",
-          description: "Get focused context for a specific task/node. Uses leaf-up traversal - returns only the relevant path from the node to root, not the entire plan tree. Best for agents starting work on a specific task.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              node_id: { 
-                type: "string", 
-                description: "Task or phase node ID to get context for" 
-              },
-              include_knowledge: { 
-                type: "boolean", 
-                description: "Include knowledge entries from relevant scopes (plan, goals, org)",
-                default: true
-              },
-              include_siblings: { 
-                type: "boolean", 
-                description: "Include sibling tasks in the same phase",
-                default: false
-              }
-            },
-            required: ["node_id"]
-          }
-        },
         {
           name: "get_plan_context",
-          description: "Get plan-level context overview. Returns plan details, phase summaries (not full tree), linked goals, and organization. Use get_agent_context for task-focused work.",
+          description: "Get plan-level context overview. Returns plan details, phase summaries (not full tree), linked goals, and organization. Use get_task_context for task-focused work.",
           inputSchema: {
             type: "object",
             properties: {
@@ -863,15 +820,20 @@ function setupTools(server, apiClientOverride) {
         // ===== GOAL TOOLS =====
         {
           name: "list_goals",
-          description: "List goals, optionally filtered by organization or status",
+          description: "List goals. By default returns only active goals — set include_inactive to true to see all.",
           inputSchema: {
             type: "object",
             properties: {
               organization_id: { type: "string", description: "Filter by organization ID" },
-              status: { 
-                type: "string", 
+              status: {
+                type: "string",
                 description: "Filter by status",
                 enum: ["active", "achieved", "at_risk", "abandoned"]
+              },
+              include_inactive: {
+                type: "boolean",
+                description: "If true, include achieved/paused/abandoned goals (default: false)",
+                default: false
               }
             }
           }
@@ -1147,18 +1109,6 @@ function setupTools(server, apiClientOverride) {
             }
           }
         },
-        {
-          name: "understand_context",
-          description: "Get comprehensive context about a plan or goal - its purpose, current state, recent activity, blocked tasks, and relevant knowledge. Use this BEFORE starting work to understand the full situation.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              plan_id: { type: "string", description: "Plan ID to understand" },
-              goal_id: { type: "string", description: "Goal ID to understand" },
-              include_knowledge: { type: "boolean", description: "Include relevant knowledge entries", default: true }
-            }
-          }
-        }
       ]
     };
   });
@@ -1240,7 +1190,7 @@ function setupTools(server, apiClientOverride) {
           next_steps: [
             "Use quick_status to update task progress",
             "Use quick_log to document your work",
-            "Use get_context to load full plan details"
+            "Use get_plan_context to load full plan details"
           ]
         });
       }
@@ -1376,88 +1326,7 @@ function setupTools(server, apiClientOverride) {
       // ========================================
       // CONTEXT LOADING IMPLEMENTATIONS
       // ========================================
-      
-      if (name === "get_context") {
-        // Redirect to understand_context implementation (same functionality)
-        const { plan_id, goal_id, include_knowledge = true } = args;
-        
-        if (!plan_id && !goal_id) {
-          return formatResponse({
-            error: "Provide either plan_id or goal_id to get context",
-            suggestion: "Use list_plans or list_goals to find IDs"
-          });
-        }
-        
-        const context = {
-          retrieved_at: new Date().toISOString()
-        };
-        
-        // Get goal context
-        if (goal_id) {
-          try {
-            context.goal = await apiClient.goals.get(goal_id);
-            if (include_knowledge) {
-              try {
-                const graphResult = await apiClient.graphiti.graphSearch({ query: context.goal?.title || '', max_results: 10 });
-                context.goal_knowledge = graphResult?.results?.facts || [];
-              } catch (e) {}
-            }
-          } catch (e) {
-            context.goal_error = e.message;
-          }
-        }
-        
-        // Get plan context
-        if (plan_id) {
-          try {
-            context.plan = await apiClient.plans.getPlan(plan_id);
-            context.plan_url = buildPlanUrl(plan_id);
-            
-            const nodes = await apiClient.nodes.getNodes(plan_id);
-            context.statistics = calculatePlanStatistics(nodes);
-            context.progress_percentage = context.statistics.total > 0 
-              ? ((context.statistics.status_counts.completed / context.statistics.total) * 100).toFixed(1) + '%'
-              : '0%';
-            
-            const flatNodes = flattenNodes(nodes);
-            context.needs_attention = {
-              blocked: flatNodes.filter(n => n.status === 'blocked').map(n => ({ 
-                id: n.id, title: n.title, type: n.node_type
-              })),
-              in_progress: flatNodes.filter(n => n.status === 'in_progress').map(n => ({ 
-                id: n.id, title: n.title, type: n.node_type
-              })),
-              ready_to_start: flatNodes
-                .filter(n => n.node_type === 'task' && n.status === 'not_started')
-                .slice(0, 5)
-                .map(n => ({ id: n.id, title: n.title }))
-            };
-            
-            try {
-              const activity = await apiClient.activity.getPlanActivity(plan_id);
-              context.recent_activity = (activity || []).slice(0, 5);
-            } catch (e) {}
-            
-            if (include_knowledge) {
-              try {
-                const graphResult = await apiClient.graphiti.graphSearch({ query: context.plan?.title || '', max_results: 10 });
-                context.plan_knowledge = graphResult?.results?.facts || [];
-              } catch (e) {}
-            }
-          } catch (e) {
-            context.plan_error = e.message;
-          }
-        }
-        
-        context.recommendation = context.needs_attention?.blocked?.length > 0 
-          ? "⚠️ There are blocked tasks that need attention first"
-          : context.needs_attention?.in_progress?.length > 0
-            ? "Continue working on the in-progress tasks"
-            : "Pick a task from ready_to_start to begin";
-            
-        return formatResponse(context);
-      }
-      
+
       if (name === "get_my_tasks") {
         const { plan_id, status = ["blocked", "in_progress"] } = args;
         
@@ -1711,7 +1580,7 @@ function setupTools(server, apiClientOverride) {
           phases: createdPhases,
           tasks: createdTasks,
           next_steps: [
-            "Use get_context to review the imported plan",
+            "Use get_plan_context to review the imported plan",
             "Use quick_status to update task progress"
           ]
         });
@@ -1796,9 +1665,16 @@ function setupTools(server, apiClientOverride) {
       
       // ===== PLAN MANAGEMENT =====
       if (name === "list_plans") {
-        const { status } = args;
+        const { status, include_completed } = args;
         const plans = await apiClient.plans.getPlans();
-        const filteredPlans = status ? plans.filter(p => p.status === status) : plans;
+        let filteredPlans;
+        if (status) {
+          filteredPlans = plans.filter(p => p.status === status);
+        } else if (!include_completed) {
+          filteredPlans = plans.filter(p => p.status !== 'completed' && p.status !== 'archived');
+        } else {
+          filteredPlans = plans;
+        }
         return formatResponse(filteredPlans);
       }
       
@@ -1902,17 +1778,6 @@ function setupTools(server, apiClientOverride) {
         }
       }
       
-      if (name === "get_node_context") {
-        const { plan_id, node_id } = args;
-        
-        // Get node with context
-        const response = await apiClient.axiosInstance.get(
-          `/plans/${plan_id}/nodes/${node_id}/context`
-        );
-        
-        return formatResponse(response.data);
-      }
-      
       if (name === "get_node_ancestry") {
         const { plan_id, node_id } = args;
         
@@ -2122,17 +1987,6 @@ function setupTools(server, apiClientOverride) {
       }
       
       // ===== AGENT CONTEXT TOOLS =====
-      if (name === "get_agent_context") {
-        const { node_id, include_knowledge = true, include_siblings = false } = args;
-        
-        const result = await apiClient.context.getNodeContext(node_id, {
-          include_knowledge,
-          include_siblings
-        });
-        
-        return formatResponse(result);
-      }
-      
       if (name === "get_plan_context") {
         const { plan_id, include_knowledge = true } = args;
         
@@ -2169,8 +2023,9 @@ function setupTools(server, apiClientOverride) {
       
       // ===== GOAL TOOLS =====
       if (name === "list_goals") {
-        const { organization_id, status } = args;
-        const result = await apiClient.goals.list({ organization_id, status });
+        const { organization_id, status, include_inactive } = args;
+        const effectiveStatus = status || (!include_inactive ? 'active' : undefined);
+        const result = await apiClient.goals.list({ organization_id, status: effectiveStatus });
         return formatResponse(result);
       }
       
@@ -2385,7 +2240,7 @@ function setupTools(server, apiClientOverride) {
             recommended_workflow: [
               "1. Check list_goals to understand current objectives",
               "2. Use list_plans to see existing plans",
-              "3. Before working on a plan, use understand_context to get the full picture",
+              "3. Before working on a plan, use get_plan_context to get the full picture",
               "4. Update task statuses as you work (update_node with status)",
               "5. Store important decisions and learnings using add_learning",
               "6. Check recall_knowledge before making decisions to see past context"
@@ -2486,90 +2341,6 @@ function setupTools(server, apiClientOverride) {
         return formatResponse(guides[topic] || guides.overview);
       }
 
-      if (name === "understand_context") {
-        const { plan_id, goal_id, include_knowledge = true } = args;
-        
-        if (!plan_id && !goal_id) {
-          return formatResponse({
-            error: "Provide either plan_id or goal_id to get context"
-          });
-        }
-        
-        const context = {
-          retrieved_at: new Date().toISOString()
-        };
-        
-        // Get goal context
-        if (goal_id) {
-          try {
-            context.goal = await apiClient.goals.get(goal_id);
-            
-            // Get related knowledge if available
-            if (include_knowledge) {
-              try {
-                const graphResult = await apiClient.graphiti.graphSearch({ query: context.goal?.title || '', max_results: 10 });
-                context.goal_knowledge = graphResult?.results?.facts || [];
-              } catch (e) {
-                // Knowledge fetch failed, continue without it
-              }
-            }
-          } catch (e) {
-            context.goal_error = e.message;
-          }
-        }
-        
-        // Get plan context
-        if (plan_id) {
-          try {
-            context.plan = await apiClient.plans.getPlan(plan_id);
-            
-            const nodes = await apiClient.nodes.getNodes(plan_id);
-            context.statistics = calculatePlanStatistics(nodes);
-            context.progress_percentage = context.statistics.total > 0 
-              ? ((context.statistics.status_counts.completed / context.statistics.total) * 100).toFixed(1) + '%'
-              : '0%';
-            
-            // Get blocked and in-progress tasks for attention
-            const flatNodes = flattenNodes(nodes);
-            context.needs_attention = {
-              blocked: flatNodes.filter(n => n.status === 'blocked').map(n => ({ 
-                id: n.id, 
-                title: n.title,
-                type: n.node_type
-              })),
-              in_progress: flatNodes.filter(n => n.status === 'in_progress').map(n => ({ 
-                id: n.id, 
-                title: n.title,
-                type: n.node_type
-              }))
-            };
-            
-            // Get recent activity
-            try {
-              const activity = await apiClient.activity.getPlanActivity(plan_id);
-              context.recent_activity = (activity || []).slice(0, 5);
-            } catch (e) {
-              // Activity fetch failed, continue without it
-            }
-            
-            // Get related knowledge if available
-            if (include_knowledge) {
-              try {
-                const graphResult = await apiClient.graphiti.graphSearch({ query: context.plan?.title || '', max_results: 10 });
-                context.plan_knowledge = graphResult?.results?.facts || [];
-              } catch (e) {
-                // Knowledge fetch failed, continue without it
-              }
-            }
-          } catch (e) {
-            context.plan_error = e.message;
-          }
-        }
-        
-        context.recommendation = "Review the statistics, needs_attention, and knowledge entries before starting work.";
-        return formatResponse(context);
-      }
-      
       // ===== GOALS HEALTH DASHBOARD =====
       if (name === "check_goals_health") {
         const { status_filter } = args || {};