agent-planner-mcp 0.6.1 → 0.7.0

package/AGENT_GUIDE.md

@@ -5,6 +5,8 @@ This guide is optimized for AI agents using AgentPlanner MCP tools.
 ## Core Workflow
 
 ```
+0. check_coherence_pending() → See if plans/goals need alignment review
+   → If stale items: run_coherence_check(plan_id) on each
 1. suggest_next_tasks(plan_id) → Find ready tasks (dependency-aware)
 2. get_task_context(node_id, depth=2) → Load progressive context
 3. Work on tasks (quick_status to track)
@@ -15,6 +17,16 @@ This guide is optimized for AI agents using AgentPlanner MCP tools.
 
 ## Essential Tools
 
+### Preflight: Alignment Check
+```javascript
+check_coherence_pending()
+// → Returns stale plans/goals that changed since last review
+
+run_coherence_check({ plan_id: "..." })
+// → Evaluates quality (coverage, specificity, ordering, knowledge)
+// → Stamps plan as reviewed, returns score breakdown
+```
+
 ### Before Starting Work
 ```javascript
 get_plan_context({ plan_id: "..." })

package/README.md

@@ -149,6 +149,10 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 - `claim_task` / `release_task` - Task locking
 - `share_plan` - Collaboration management
 
+### Alignment & Review
+- `check_coherence_pending` - See which plans/goals need alignment review (staleness check)
+- `run_coherence_check` - Evaluate plan quality and stamp as reviewed
+
 ## LLM Skill Reference
 
 See **[SKILL.md](./SKILL.md)** for a complete reference designed to be consumed by LLMs. Include it in system prompts or agent configurations to give any LLM full knowledge of how to use AgentPlanner tools effectively.

package/SKILL.md

@@ -31,12 +31,43 @@ You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative p
 - You need to coordinate with humans on multi-step projects
 - You want to persist findings, decisions, or progress across sessions
 - You are asked to plan, research, or implement something as part of a tracked workflow
+- A user wants help defining or refining a goal
+
+## Goal Coaching
+
+When a user expresses an intent, objective, or want — help them turn it into a well-structured goal. Don't just create a goal from their words. Coach them through it:
+
+```
+1. Listen to the user's intent (however vague)
+2. recall_knowledge()         → Search for related context in the knowledge graph
+3. list_goals()               → Check for overlap with existing goals
+4. list_plans()               → Find related work that might link to this goal
+5. Propose a structured goal:
+   - Clear title
+   - Description explaining why this matters
+   - Success criteria with specific metrics + targets
+   - Linked plans (existing or suggest new ones)
+6. create_goal() + link plans
+7. assess_goal_quality()      → Check quality and get improvement suggestions
+8. Iterate with the user until quality is high
+```
+
+**What makes a good goal:**
+- **Clear** — has a title and description that explain what and why
+- **Measurable** — has success criteria with specific metrics and targets (e.g., "API latency < 100ms p99")
+- **Actionable** — has at least one linked plan with concrete tasks
+- **Knowledge-grounded** — related facts exist in the knowledge graph (if not, suggest researching first)
+- **Committed** — promoted from desire to intention when ready, with a time reference
+
+Use `assess_goal_quality(goal_id)` after creation to check quality and surface suggestions. Share the results with the user and help them address gaps.
 
 ## Workflow
 
 Follow this sequence when working on a plan:
 
 ```
+0. PREFLIGHT → check_coherence_pending to see if anything needs alignment review
+               ↳ If stale plans found, run_coherence_check on each before starting task work
 1. ORIENT    → suggest_next_tasks or get_task_context to understand what needs doing
 2. CLAIM     → quick_status to mark the task in_progress
 3. WORK      → Do the actual work (code, research, analysis, etc.)
@@ -46,6 +77,22 @@ Follow this sequence when working on a plan:
 6. NEXT      → suggest_next_tasks to find the next ready task
 ```
 
+### Preflight: Alignment Check
+
+Before diving into tasks, check if goals, plans, and knowledge are aligned:
+
+```
+check_coherence_pending()
+→ Returns stale plans/goals that changed since last review
+→ If stale items found:
+    run_coherence_check({ plan_id: "<plan_id>" })
+    → Evaluates quality (coverage, specificity, ordering, knowledge)
+    → Stamps the plan as reviewed
+    → Returns quality breakdown + coherence issues
+```
+
+This is a lightweight check (seconds, not minutes). Do it at the start of each work session. Skip if you already checked recently.
+
 ## Loading Context
 
 Always load context before starting work. Use `get_task_context` — it gives you exactly the right amount of information based on depth level.
@@ -205,6 +252,16 @@ Cross-plan dependencies work the same as regular dependencies (`blocks`, `requir
 | `claim_task` | Claim exclusive ownership of a task (prevents agent collisions) |
 | `release_task` | Release a previously claimed task |
 
+### Alignment & Review
+
+Check if goals, plans, and knowledge are aligned. Run as a preflight check before starting work.
+
+| Tool | Purpose |
+|------|---------|
+| `check_coherence_pending` | See what needs review — returns stale plans/goals that changed since last check |
+| `run_coherence_check` | Evaluate a plan's quality (coverage, specificity, ordering, knowledge) and stamp as reviewed |
+| `assess_goal_quality` | Check how well-defined a goal is (clarity, measurability, actionability, knowledge, commitment) |
+
 ### Knowledge (Temporal Knowledge Graph)
 
 All knowledge is stored in the Graphiti temporal knowledge graph, which automatically extracts entities and relationships and enables cross-plan knowledge retrieval. The temporal graph is **cross-plan** and **persists across sessions** — anything recorded is available to all future agents and conversations within the organization.

package/package.json

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

package/src/api-client.js

@@ -552,45 +552,47 @@ const goals = {
     return response.data;
   },
   
-  updateMetrics: async (goalId, metrics) => {
-    const response = await apiClient.put(`/goals/${goalId}/metrics`, { metrics });
-    return response.data;
-  },
-  
   delete: async (goalId) => {
     const response = await apiClient.delete(`/goals/${goalId}`);
     return response.data;
   },
-  
+
   linkPlan: async (goalId, planId) => {
-    const response = await apiClient.post(`/goals/${goalId}/plans/${planId}`);
+    const response = await apiClient.post(`/goals/${goalId}/links`, {
+      linkedType: 'plan', linkedId: planId
+    });
     return response.data;
   },
-  
+
   unlinkPlan: async (goalId, planId) => {
-    const response = await apiClient.delete(`/goals/${goalId}/plans/${planId}`);
+    const goal = await apiClient.get(`/goals/${goalId}`);
+    const link = (goal.data.links || []).find(
+      l => l.linkedType === 'plan' && l.linkedId === planId
+    );
+    if (!link) return { success: false, message: 'Link not found' };
+    const response = await apiClient.delete(`/goals/${goalId}/links/${link.id}`);
     return response.data;
   },
 
   // v2 goal-dependency endpoints
   getPath: async (goalId, maxDepth) => {
     const params = maxDepth ? `?max_depth=${maxDepth}` : '';
-    const response = await apiClient.get(`/goals/v2/${goalId}/path${params}`);
+    const response = await apiClient.get(`/goals/${goalId}/path${params}`);
     return response.data;
   },
 
   getProgress: async (goalId) => {
-    const response = await apiClient.get(`/goals/v2/${goalId}/progress`);
+    const response = await apiClient.get(`/goals/${goalId}/progress`);
     return response.data;
   },
 
   listAchievers: async (goalId) => {
-    const response = await apiClient.get(`/goals/v2/${goalId}/achievers`);
+    const response = await apiClient.get(`/goals/${goalId}/achievers`);
     return response.data;
   },
 
   addAchiever: async (goalId, sourceNodeId, weight) => {
-    const response = await apiClient.post(`/goals/v2/${goalId}/achievers`, {
+    const response = await apiClient.post(`/goals/${goalId}/achievers`, {
       source_node_id: sourceNodeId,
       weight: weight ?? 1,
     });
@@ -598,17 +600,22 @@ const goals = {
   },
 
   removeAchiever: async (goalId, depId) => {
-    const response = await apiClient.delete(`/goals/v2/${goalId}/achievers/${depId}`);
+    const response = await apiClient.delete(`/goals/${goalId}/achievers/${depId}`);
     return response.data;
   },
 
   getKnowledgeGaps: async (goalId) => {
-    const response = await apiClient.get(`/goals/v2/${goalId}/knowledge-gaps`);
+    const response = await apiClient.get(`/goals/${goalId}/knowledge-gaps`);
     return response.data;
   },
 
   getDashboard: async () => {
-    const response = await apiClient.get('/goals/v2/dashboard');
+    const response = await apiClient.get('/goals/dashboard');
+    return response.data;
+  },
+
+  getQuality: async (goalId) => {
+    const response = await apiClient.get(`/goals/${goalId}/quality`);
     return response.data;
   },
 };
@@ -866,17 +873,21 @@ function createApiClient(token) {
       get: async (goalId) => (await client.get(`/goals/${goalId}`)).data,
       create: async (data) => (await client.post('/goals', data)).data,
       update: async (goalId, data) => (await client.put(`/goals/${goalId}`, data)).data,
-      updateMetrics: async (goalId, metrics) => (await client.put(`/goals/${goalId}/metrics`, { metrics })).data,
       delete: async (goalId) => (await client.delete(`/goals/${goalId}`)).data,
-      linkPlan: async (goalId, planId) => (await client.post(`/goals/${goalId}/plans/${planId}`)).data,
-      unlinkPlan: async (goalId, planId) => (await client.delete(`/goals/${goalId}/plans/${planId}`)).data,
-      getPath: async (goalId, maxDepth) => { const p = maxDepth ? `?max_depth=${maxDepth}` : ''; return (await client.get(`/goals/v2/${goalId}/path${p}`)).data; },
-      getProgress: async (goalId) => (await client.get(`/goals/v2/${goalId}/progress`)).data,
-      listAchievers: async (goalId) => (await client.get(`/goals/v2/${goalId}/achievers`)).data,
-      addAchiever: async (goalId, sourceNodeId, weight) => (await client.post(`/goals/v2/${goalId}/achievers`, { source_node_id: sourceNodeId, weight: weight ?? 1 })).data,
-      removeAchiever: async (goalId, depId) => (await client.delete(`/goals/v2/${goalId}/achievers/${depId}`)).data,
-      getKnowledgeGaps: async (goalId) => (await client.get(`/goals/v2/${goalId}/knowledge-gaps`)).data,
-      getDashboard: async () => (await client.get('/goals/v2/dashboard')).data,
+      linkPlan: async (goalId, planId) => (await client.post(`/goals/${goalId}/links`, { linkedType: 'plan', linkedId: planId })).data,
+      unlinkPlan: async (goalId, planId) => {
+        const goal = await client.get(`/goals/${goalId}`);
+        const link = (goal.data.links || []).find(l => l.linkedType === 'plan' && l.linkedId === planId);
+        if (!link) return { success: false, message: 'Link not found' };
+        return (await client.delete(`/goals/${goalId}/links/${link.id}`)).data;
+      },
+      getPath: async (goalId, maxDepth) => { const p = maxDepth ? `?max_depth=${maxDepth}` : ''; return (await client.get(`/goals/${goalId}/path${p}`)).data; },
+      getProgress: async (goalId) => (await client.get(`/goals/${goalId}/progress`)).data,
+      listAchievers: async (goalId) => (await client.get(`/goals/${goalId}/achievers`)).data,
+      addAchiever: async (goalId, sourceNodeId, weight) => (await client.post(`/goals/${goalId}/achievers`, { source_node_id: sourceNodeId, weight: weight ?? 1 })).data,
+      removeAchiever: async (goalId, depId) => (await client.delete(`/goals/${goalId}/achievers/${depId}`)).data,
+      getKnowledgeGaps: async (goalId) => (await client.get(`/goals/${goalId}/knowledge-gaps`)).data,
+      getDashboard: async () => (await client.get('/goals/dashboard')).data,
     },
     context: {
       getNodeContext: async (nodeId, options = {}) => {
@@ -913,6 +924,13 @@ function createApiClient(token) {
 // Export the axios instance for direct use
 const axiosInstance = apiClient;
 
+// ─── Coherence ────────────────────────────────────────────────
+const coherence = {
+  getPending: () => apiClient.get('/coherence/pending').then(r => r.data),
+  runCheck: (planId, goalId) => apiClient.post(`/plans/${planId}/coherence/check`, goalId ? { goal_id: goalId } : {}).then(r => r.data),
+  getPlanCoherence: (planId) => apiClient.get(`/plans/${planId}/coherence`).then(r => r.data),
+};
+
 module.exports = {
   plans,
   nodes,
@@ -926,6 +944,7 @@ module.exports = {
   context,
   graphiti,
   dependencies,
+  coherence,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/index.js

@@ -42,12 +42,9 @@ async function main() {
     console.error(`MCP Server Name: ${process.env.MCP_SERVER_NAME || 'planning-system-mcp'}`);
     console.error(`MCP Server Version: ${process.env.MCP_SERVER_VERSION || version}`);
 
-    // Validate required environment variables
-    if (!userApiToken) {
-      throw new Error('USER_API_TOKEN environment variable is required. Please generate one from the Agent Planner UI and set it in .env file.');
-    }
-
     if (transport === 'http') {
+      // HTTP mode: tokens come from the Authorization header on each request
+      // No USER_API_TOKEN needed — per-session clients are created in server-http.js
       // HTTP/SSE transport mode
       const httpServer = new MCPHTTPServer({
         port: process.env.PORT || 3100,
@@ -69,7 +66,11 @@ async function main() {
         process.exit(0);
       });
     } else {
-      // Stdio transport mode (default)
+      // Stdio transport mode (default) — requires USER_API_TOKEN since there's no HTTP request
+      if (!userApiToken) {
+        throw new Error('USER_API_TOKEN environment variable is required for stdio mode. Please generate one from the Agent Planner UI and set it in .env file.');
+      }
+
       const server = new Server({
         name: process.env.MCP_SERVER_NAME || "planning-system-mcp",
         version: process.env.MCP_SERVER_VERSION || version

package/src/tools.js

@@ -178,6 +178,41 @@ function setupTools(server, apiClientOverride) {
           }
         },
 
+        // ========================================
+        // COHERENCE - Check alignment across goals/plans/knowledge
+        // ========================================
+        {
+          name: "check_coherence_pending",
+          description: "Check what needs coherence review. Returns stale plans and goals that have changed since their last coherence check. Call this at the start of a maintenance cycle to discover what needs attention. Uses timestamp comparison (updated_at vs coherence_checked_at) — no expensive processing.",
+          inputSchema: {
+            type: "object",
+            properties: {}
+          }
+        },
+        {
+          name: "run_coherence_check",
+          description: "Run a coherence check on a specific plan. Evaluates quality (coverage, specificity, ordering, knowledge completeness), flags contradictions, and stamps the plan as checked. Returns quality breakdown with sub-scores and rationale.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              plan_id: { type: "string", description: "Plan ID to check" },
+              goal_id: { type: "string", description: "Optional goal ID to evaluate coverage against" }
+            },
+            required: ["plan_id"]
+          }
+        },
+        {
+          name: "assess_goal_quality",
+          description: "Assess how well-defined a goal is. Evaluates 5 dimensions: clarity (title+description), measurability (success criteria), actionability (linked plans), knowledge grounding (related facts), and commitment (desire vs intention, deadline). Returns score, dimension breakdown, and specific improvement suggestions. Use this when helping users define or refine goals.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              goal_id: { type: "string", description: "Goal ID to assess" }
+            },
+            required: ["goal_id"]
+          }
+        },
+
         // ========================================
         // CONTEXT LOADING - Get everything you need
         // Use before starting work on a plan/goal
@@ -858,21 +893,10 @@ function setupTools(server, apiClientOverride) {
               organization_id: { type: "string", description: "Organization ID" },
               title: { type: "string", description: "Goal title" },
               description: { type: "string", description: "Goal description" },
-              success_metrics: { 
-                type: "array", 
-                description: "Success metrics array [{metric, target, current, unit}]",
-                items: {
-                  type: "object",
-                  properties: {
-                    metric: { type: "string" },
-                    target: { type: "number" },
-                    current: { type: "number" },
-                    unit: { type: "string" }
-                  }
-                }
-              },
-              time_horizon: { type: "string", description: "Target date (ISO format)" },
-              github_repo_url: { type: "string", description: "Related GitHub repo URL" }
+              type: { type: "string", enum: ["outcome", "constraint", "metric", "principle"], description: "Goal type (default: outcome)" },
+              success_criteria: { type: "object", description: "Success criteria as JSON" },
+              priority: { type: "number", description: "Priority (higher = more important, default: 0)" },
+              parent_goal_id: { type: "string", description: "Parent goal ID for hierarchy" }
             },
             required: ["organization_id", "title"]
           }
@@ -886,13 +910,15 @@ function setupTools(server, apiClientOverride) {
               goal_id: { type: "string", description: "Goal ID" },
               title: { type: "string", description: "New title" },
               description: { type: "string", description: "New description" },
-              status: { 
-                type: "string", 
+              type: { type: "string", enum: ["outcome", "constraint", "metric", "principle"], description: "Goal type" },
+              status: {
+                type: "string",
                 description: "New status",
-                enum: ["active", "achieved", "at_risk", "abandoned"]
+                enum: ["active", "achieved", "paused", "abandoned"]
               },
-              success_metrics: { type: "array", description: "Updated metrics" },
-              time_horizon: { type: "string", description: "New target date" }
+              success_criteria: { type: "object", description: "Success criteria as JSON" },
+              priority: { type: "number", description: "Priority (higher = more important)" },
+              parent_goal_id: { type: "string", description: "Parent goal ID for hierarchy" }
             },
             required: ["goal_id"]
           }
@@ -2036,20 +2062,24 @@ function setupTools(server, apiClientOverride) {
       }
       
       if (name === "create_goal") {
-        const { organization_id, title, description, success_metrics, time_horizon, github_repo_url } = args;
+        const { organization_id, title, description, type, success_criteria, priority, parent_goal_id } = args;
         const result = await apiClient.goals.create({
           organization_id,
           title,
           description,
-          success_metrics,
-          time_horizon,
-          github_repo_url
+          type: type || 'outcome',
+          successCriteria: success_criteria || null,
+          priority: priority || 0,
+          parentGoalId: parent_goal_id || null,
         });
         return formatResponse(result);
       }
       
       if (name === "update_goal") {
-        const { goal_id, ...updateData } = args;
+        const { goal_id, parent_goal_id, success_criteria, ...rest } = args;
+        const updateData = { ...rest };
+        if (parent_goal_id !== undefined) updateData.parentGoalId = parent_goal_id;
+        if (success_criteria !== undefined) updateData.successCriteria = success_criteria;
         const result = await apiClient.goals.update(goal_id, updateData);
         return formatResponse(result);
       }
@@ -2238,12 +2268,14 @@ function setupTools(server, apiClientOverride) {
               "Knowledge - Persistent storage for decisions, context, constraints, and learnings"
             ],
             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 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"
+              "1. PREFLIGHT: check_coherence_pending to see if any plans/goals need alignment review",
+              "   → If stale items found, run_coherence_check on each before starting task work",
+              "2. Check list_goals to understand current objectives",
+              "3. Use list_plans to see existing plans",
+              "4. Before working on a plan, use get_plan_context to get the full picture",
+              "5. Update task statuses as you work (update_node with status)",
+              "6. Store important decisions and learnings using add_learning",
+              "7. Check recall_knowledge before making decisions to see past context"
             ],
             quick_tips: [
               "Always capture WHY decisions were made, not just WHAT",
@@ -2380,6 +2412,43 @@ function setupTools(server, apiClientOverride) {
         });
       }
 
+      // ===== COHERENCE =====
+      if (name === "check_coherence_pending") {
+        const result = await apiClient.coherence.getPending();
+        const totalStale = (result.stale_plans?.length || 0) + (result.stale_goals?.length || 0);
+        return formatResponse({
+          ...result,
+          tip: totalStale > 0
+            ? "Review stale items. For each stale plan, call run_coherence_check to evaluate quality and stamp as checked."
+            : "Everything is up to date. No coherence review needed."
+        });
+      }
+
+      if (name === "assess_goal_quality") {
+        const { goal_id } = args;
+        const result = await apiClient.goals.getQuality(goal_id);
+        const lowDims = Object.entries(result.dimensions || {})
+          .filter(([, v]) => v.score < 0.5)
+          .map(([k]) => k);
+        return formatResponse({
+          ...result,
+          tip: result.suggestions?.length > 0
+            ? `Goal needs improvement in: ${lowDims.join(', ') || 'minor areas'}. Follow the suggestions to strengthen it.`
+            : 'Goal is well-defined. Ready for agent execution.'
+        });
+      }
+
+      if (name === "run_coherence_check") {
+        const { plan_id, goal_id } = args;
+        const result = await apiClient.coherence.runCheck(plan_id, goal_id);
+        return formatResponse({
+          ...result,
+          tip: result.coherence_issues_count > 0
+            ? `${result.coherence_issues_count} coherence issues found. Review tasks with stale_beliefs or contradiction_detected status.`
+            : "Plan is coherent. Quality score and checked_at timestamp updated."
+        });
+      }
+
       // Tool not found
       throw new Error(`Unknown tool: ${name}`);
     } catch (error) {