agent-planner-mcp 1.0.0 → 1.1.0

package/README.md

@@ -123,6 +123,28 @@ Beyond title, description, agent_instructions, and acceptance criteria, the gene
 
 The CLI is intentionally thin: it covers the read context + writeback loop and nothing else. For decomposition, dependency creation, knowledge graph queries, RPI chains, coherence runs, and goal management, use the MCP server (or the API directly).
 
+## Agent Loop Facade
+
+AgentPlanner API now exposes a narrow `/agent/*` facade for the main autonomous loop. MCP uses this facade when available and falls back to older domain endpoints for self-hosted older APIs.
+
+Primary mappings:
+
+| MCP tool | Preferred API endpoint |
+|---|---|
+| `briefing` | `GET /agent/briefing` |
+| `claim_next_task` | `POST /agent/work-sessions` |
+| `update_task` with `session_id` + `completed` | `POST /agent/work-sessions/:id/complete` |
+| `update_task` with `session_id` + `blocked` | `POST /agent/work-sessions/:id/block` |
+| `form_intention` | `POST /agent/intentions` when available, with domain-endpoint fallback |
+
+Validation:
+
+```bash
+npm run validate:mcp-loop
+```
+
+This checks that the MCP tools route through the facade for briefing, task claim/start, and session completion/blocking.
+
 
 ### Claude Desktop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {
@@ -12,6 +12,7 @@
     "dev": "nodemon src/index.js",
     "dev:http": "MCP_TRANSPORT=http nodemon src/index.js",
     "test": "jest",
+    "validate:mcp-loop": "jest __tests__/agent-loop-facade.test.js --runInBand",
     "test:tools": "node test-tools.js",
     "setup": "node src/setup.js",
     "setup-claude-code": "node src/setup-claude-code.js",

package/src/api-client.js

@@ -17,12 +17,29 @@ const getAuthScheme = (token) => {
 
 const authScheme = getAuthScheme(userApiToken);
 
+// Identify this caller in the API server's tool_calls telemetry.
+// Setup wizards (per client) should set MCP_CLIENT_LABEL to one of
+// "Claude Desktop" | "Claude Code" | "Cursor" | "ChatGPT" | "OpenClaw"
+// so the Settings → Integrations dashboard can group calls per client.
+let pkgVersion;
+try { pkgVersion = require('../package.json').version; } catch { pkgVersion = '0.0.0'; }
+const clientLabel = process.env.MCP_CLIENT_LABEL || null;
+const userAgent = clientLabel
+  ? `agent-planner-mcp/${pkgVersion} (${clientLabel})`
+  : `agent-planner-mcp/${pkgVersion}`;
+
 // Create API client instance
 const apiClient = axios.create({
   baseURL: process.env.API_URL || 'http://localhost:3000',
   headers: {
     'Content-Type': 'application/json',
-    'Authorization': userApiToken ? `${authScheme} ${userApiToken}` : undefined
+    'Authorization': userApiToken ? `${authScheme} ${userApiToken}` : undefined,
+    'User-Agent': userAgent,
+    // X-Client-Label takes precedence on the API side (see
+    // toolCallTelemetry.middleware) so MCP setup wizards can label
+    // calls precisely without polluting the User-Agent string.
+    ...(clientLabel ? { 'X-Client-Label': clientLabel } : {}),
+    'X-MCP-Client': clientLabel || 'unknown',
   }
 });
 
@@ -738,6 +755,15 @@ const users = {
   },
 };
 
+// ─── Agent Loop facade ────────────────────────────────────────
+const agentLoop = {
+  briefing: async (params = {}) => (await apiClient.get('/agent/briefing', { params })).data,
+  startWorkSession: async (data = {}) => (await apiClient.post('/agent/work-sessions', data)).data,
+  completeWorkSession: async (sessionId, data = {}) => (await apiClient.post(`/agent/work-sessions/${sessionId}/complete`, data)).data,
+  blockWorkSession: async (sessionId, data = {}) => (await apiClient.post(`/agent/work-sessions/${sessionId}/block`, data)).data,
+  createIntention: async (data = {}) => (await apiClient.post('/agent/intentions', data)).data,
+};
+
 // ─── Dependencies (cross-plan & external) ─────────────────────
 const dependencies = {
   /**
@@ -778,11 +804,21 @@ const dependencies = {
  */
 function createApiClient(token, options = {}) {
   const scheme = getAuthScheme(token);
+  // Telemetry headers — same shape as the default client. options.clientLabel
+  // wins over the global env var so HTTP-mode sessions can label themselves
+  // per connection (e.g. when the SSE handshake reveals the client).
+  const sessionLabel = options.clientLabel || process.env.MCP_CLIENT_LABEL || null;
+  const sessionUserAgent = sessionLabel
+    ? `agent-planner-mcp/${pkgVersion} (${sessionLabel})`
+    : `agent-planner-mcp/${pkgVersion}`;
   const client = axios.create({
     baseURL: options.apiUrl || process.env.API_URL || 'http://localhost:3000',
     headers: {
       'Content-Type': 'application/json',
-      'Authorization': token ? `${scheme} ${token}` : undefined
+      'Authorization': token ? `${scheme} ${token}` : undefined,
+      'User-Agent': sessionUserAgent,
+      ...(sessionLabel ? { 'X-Client-Label': sessionLabel } : {}),
+      'X-MCP-Client': sessionLabel || 'unknown',
     }
   });
 
@@ -945,6 +981,13 @@ function createApiClient(token, options = {}) {
         return (await client.get(`/users/my-tasks${qs}`)).data;
       },
     },
+    agentLoop: {
+      briefing: async (params = {}) => (await client.get('/agent/briefing', { params })).data,
+      startWorkSession: async (data = {}) => (await client.post('/agent/work-sessions', data)).data,
+      completeWorkSession: async (sessionId, data = {}) => (await client.post(`/agent/work-sessions/${sessionId}/complete`, data)).data,
+      blockWorkSession: async (sessionId, data = {}) => (await client.post(`/agent/work-sessions/${sessionId}/block`, data)).data,
+      createIntention: async (data = {}) => (await client.post('/agent/intentions', data)).data,
+    },
     axiosInstance: client,
   };
 }
@@ -975,6 +1018,7 @@ module.exports = {
   dependencies,
   coherence,
   users,
+  agentLoop,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/setup.js

@@ -158,13 +158,16 @@ function updateClaudeConfig(configPath, mcpServerPath, apiUrl, token) {
     config.mcpServers = {};
   }
 
-  // Add or update planning-system server
+  // Add or update planning-system server.
+  // MCP_CLIENT_LABEL identifies this install in the Settings →
+  // Integrations dashboard's tool_calls telemetry stream.
   config.mcpServers['planning-system'] = {
     command: 'node',
     args: [path.join(mcpServerPath, 'src', 'index.js')],
     env: {
       API_URL: apiUrl,
-      USER_API_TOKEN: token
+      USER_API_TOKEN: token,
+      MCP_CLIENT_LABEL: 'Claude Desktop'
     }
   };
 

package/src/tools/bdi/beliefs.js

@@ -30,6 +30,20 @@ const briefingDefinition = {
 };
 
 async function briefingHandler(args, apiClient) {
+  try {
+    const response = await apiClient.axiosInstance.get('/agent/briefing', {
+      params: {
+        scope: args.scope,
+        goal_id: args.goal_id,
+        plan_id: args.plan_id,
+        recent_window_hours: args.recent_window_hours,
+      },
+    });
+    return formatResponse(response.data);
+  } catch {
+    // Fall back to the pre-facade fan-out for self-hosted older APIs.
+  }
+
   const recentHours = typeof args.recent_window_hours === 'number' ? args.recent_window_hours : 24;
   const recentSinceMs = Date.now() - recentHours * 3600 * 1000;
 
@@ -252,6 +266,19 @@ async function goalStateHandler(args, apiClient) {
       direct_downstream_count: t.direct_downstream_count || 0,
     }));
 
+  // Surface the goal's linked plans + tasks. The underlying GET /goals/:id
+  // already returns the `links` array; the previous handler discarded it,
+  // so quality.actionability could report "26 plans linked" while the
+  // response refused to name a single one. Callers had no read-side way
+  // to enumerate the plans served by a goal short of REST.
+  const links = safeArray(goal.links);
+  const linked_plans = links
+    .filter((l) => (l.linkedType || l.linked_type) === 'plan')
+    .map((l) => ({ id: l.linkedId || l.linked_id, link_id: l.id }));
+  const linked_tasks = links
+    .filter((l) => (l.linkedType || l.linked_type) === 'task')
+    .map((l) => ({ id: l.linkedId || l.linked_id, link_id: l.id }));
+
   return formatResponse({
     as_of: asOf(),
     goal: {
@@ -261,6 +288,8 @@ async function goalStateHandler(args, apiClient) {
       owner_id: goal.ownerId || goal.owner_id, success_criteria: goal.successCriteria || goal.success_criteria,
       promoted_at: goal.promotedAt || goal.promoted_at,
     },
+    linked_plans,
+    linked_tasks,
     quality: {
       score: quality.score, dimensions: quality.dimensions,
       suggestions: quality.suggestions, last_assessed_at: quality.as_of,
@@ -348,6 +377,79 @@ async function recallKnowledgeHandler(args, apiClient) {
   return formatResponse(out);
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// list_plans — list workspace plans with optional filters.
+// Counterpart to list_goals; previously the only ways to find a plan
+// were knowing the UUID a priori, parsing briefing.recent_activity,
+// or calling task_context on a known node — all bad.
+// ─────────────────────────────────────────────────────────────────────────
+
+const listPlansDefinition = {
+  name: 'list_plans',
+  description:
+    'List plans with optional filters by status, visibility, or text query. ' +
+    'Returns id, title, status, visibility, last update, and link counts so ' +
+    'you can pick a plan to operate on without round-tripping briefing.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      filter: {
+        type: 'object',
+        properties: {
+          status: { type: 'array', items: { type: 'string' } },
+          visibility: { type: 'array', items: { type: 'string', enum: ['private', 'unlisted', 'public'] } },
+          query: { type: 'string', description: 'Substring match on title (case-insensitive)' },
+          limit: { type: 'integer', default: 50 },
+        },
+      },
+    },
+  },
+};
+
+async function listPlansHandler(args, apiClient) {
+  const filter = args.filter || {};
+  try {
+    const raw = await apiClient.plans.getPlans();
+    let plans = Array.isArray(raw) ? raw : safeArray(raw.plans || raw);
+
+    if (filter.status?.length) plans = plans.filter((p) => filter.status.includes(p.status));
+    if (filter.visibility?.length) plans = plans.filter((p) => filter.visibility.includes(p.visibility));
+    if (filter.query) {
+      const q = filter.query.toLowerCase();
+      plans = plans.filter((p) => (p.title || '').toLowerCase().includes(q));
+    }
+    plans = plans.slice(0, filter.limit || 50);
+
+    const summary = plans.reduce(
+      (acc, p) => {
+        acc[p.status] = (acc[p.status] || 0) + 1;
+        acc.total += 1;
+        return acc;
+      },
+      { total: 0 },
+    );
+
+    return formatResponse({
+      as_of: asOf(),
+      summary,
+      plans: plans.map((p) => ({
+        id: p.id,
+        title: p.title,
+        status: p.status,
+        visibility: p.visibility,
+        owner_id: p.owner_id || p.ownerId,
+        updated_at: p.updated_at || p.updatedAt,
+        // Surface progress + tether info when the API decorates the rows;
+        // listPlans on the v2 API now bulk-loads stats + goal_tethers.
+        progress: p.progress ?? p.stats?.percentage,
+        goal_tethers: p.goal_tethers,
+      })),
+    });
+  } catch (err) {
+    return errorResponse('upstream_unavailable', `list_plans failed: ${err.response?.data?.error || err.message}`);
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // search — universal text search.
 // ─────────────────────────────────────────────────────────────────────────
@@ -376,13 +478,32 @@ const searchDefinition = {
 
 async function searchHandler(args, apiClient) {
   const { query, scope = 'global', scope_id, filters = {} } = args;
+  const limit = filters.limit || 20;
   try {
     let result;
-    const limit = filters.limit || 20;
-    if (scope === 'global') result = await apiClient.search.global(query, { limit, ...filters });
-    else if (scope === 'plans') result = await apiClient.search.plans(query, limit);
-    else if (scope === 'plan') result = await apiClient.search.inPlan(scope_id, query, limit);
-    else if (scope === 'node') result = await apiClient.search.inNode(scope_id, query, limit);
+    // Map MCP scopes onto the actual api-client surface. The handler
+    // previously called apiClient.search.{global,plans,inPlan,inNode}
+    // — none of those methods exist, so every invocation 500'd. The
+    // real api-client exposes globalSearch + searchPlan only; for
+    // 'plans' and 'node' we filter the global result client-side
+    // instead of hitting a (non-existent) per-bucket endpoint.
+    if (scope === 'plan') {
+      if (!scope_id) return errorResponse('invalid_arg', 'search scope=plan requires scope_id');
+      result = await apiClient.search.searchPlan(scope_id, query);
+    } else {
+      const global = await apiClient.search.globalSearch(query);
+      const all = Array.isArray(global?.results) ? global.results : [];
+      const matchScope = (r) => {
+        if (scope === 'global') return true;
+        if (scope === 'plans') return r.type === 'plan';
+        if (scope === 'node') return r.type === 'node' && (!scope_id || r.plan_id === scope_id);
+        return true;
+      };
+      const matchType = (r) => !filters.type || r.type === filters.type;
+      const matchStatus = (r) => !filters.status || r.status === filters.status;
+      const filtered = all.filter((r) => matchScope(r) && matchType(r) && matchStatus(r)).slice(0, limit);
+      result = { results: filtered, count: filtered.length, query, scope };
+    }
     return formatResponse({ as_of: asOf(), ...(result || {}) });
   } catch (err) {
     return errorResponse('upstream_unavailable', `Search failed: ${err.response?.data?.error || err.message}`);
@@ -437,6 +558,7 @@ module.exports = {
     taskContextDefinition,
     goalStateDefinition,
     recallKnowledgeDefinition,
+    listPlansDefinition,
     searchDefinition,
     planAnalysisDefinition,
   ],
@@ -445,6 +567,7 @@ module.exports = {
     task_context: taskContextHandler,
     goal_state: goalStateHandler,
     recall_knowledge: recallKnowledgeHandler,
+    list_plans: listPlansHandler,
     search: searchHandler,
     plan_analysis: planAnalysisHandler,
   },

package/src/tools/bdi/intentions.js

@@ -281,15 +281,37 @@ const updateTaskDefinition = {
         type: 'string',
         description: 'Optional: also write a knowledge episode (recommended on completion)',
       },
+      session_id: {
+        type: 'string',
+        description: 'Optional work-session id returned by claim_next_task. Uses the agent-loop completion/block endpoint when status is completed or blocked.',
+      },
+      decision: {
+        type: 'object',
+        description: 'Optional decision to queue when blocking a session through the agent-loop endpoint.',
+      },
     },
     required: ['task_id'],
   },
 };
 
 async function updateTaskHandler(args, apiClient) {
-  const { task_id, status, log_message, add_learning, release_claim } = args;
+  const { task_id, status, log_message, add_learning, release_claim, session_id, decision } = args;
   let planId = args.plan_id;
 
+  if (session_id && (status === 'completed' || status === 'blocked')) {
+    try {
+      const path = status === 'blocked' ? 'block' : 'complete';
+      const response = await apiClient.axiosInstance.post(`/agent/work-sessions/${session_id}/${path}`, {
+        summary: log_message,
+        learning: add_learning ? { content: add_learning } : undefined,
+        decision,
+      });
+      return formatResponse(response.data);
+    } catch {
+      // Fall back to legacy fan-out for older APIs or if the session was not found.
+    }
+  }
+
   // Resolve plan_id from task if not provided.
   if (!planId) {
     try {
@@ -405,6 +427,21 @@ async function claimNextTaskHandler(args, apiClient) {
   const { scope = {}, ttl_minutes = 30, fresh = false, context_depth = 2, dry_run = false } = args;
   const { plan_id, goal_id } = scope;
 
+  try {
+    const response = await apiClient.axiosInstance.post('/agent/work-sessions', {
+      plan_id,
+      goal_id,
+      ttl_minutes,
+      fresh,
+      dry_run,
+      depth: context_depth,
+      agent_id: 'mcp-agent',
+    });
+    return formatResponse(response.data);
+  } catch {
+    // Fall back to the pre-facade fan-out for self-hosted older APIs.
+  }
+
   let chosen = null;
   let source = null;
 
@@ -711,6 +748,37 @@ async function createSubtree(apiClient, planId, parentId, children, results) {
 async function formIntentionHandler(args, apiClient) {
   const { goal_id, title, description, rationale, status = 'active', visibility = 'private', tree = [] } = args;
 
+  if (apiClient.agentLoop?.createIntention) {
+    const treeError = validateTreeShape(tree);
+    if (treeError) {
+      return errorResponse('tree_shape_invalid', treeError);
+    }
+    try {
+      const result = await apiClient.agentLoop.createIntention({
+        goal_id,
+        title,
+        description,
+        rationale,
+        status,
+        visibility,
+        tree,
+      });
+      return formatResponse({
+        ...result,
+        plan_id: result.plan?.id || result.plan_id,
+        goal_id,
+        status: result.plan?.status || status,
+        is_draft: (result.plan?.status || status) === 'draft',
+        nodes_created: Array.isArray(result.tree) ? result.tree.length : undefined,
+        next_step: (result.plan?.status || status) === 'draft'
+          ? "Plan created as draft. Will surface in dashboard pending for human review. Auto-promotes to active when first task moves to in_progress."
+          : "Plan active. Claim a task with claim_next_task({plan_id}) to begin work.",
+      });
+    } catch {
+      // Fall through to the legacy multi-call path for older/self-hosted APIs.
+    }
+  }
+
   // Validate goal exists.
   let goal;
   try {

package/src/tools/bdi/utility.js

@@ -26,7 +26,7 @@ async function getStartedHandler(args) {
       "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', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
+      beliefs: ['briefing', 'list_plans', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
       desires: ['list_goals', 'update_goal'],
       intentions: ['claim_next_task', 'update_task', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
     },