agent-planner-mcp 0.7.0 → 0.8.1

package/README.md

@@ -13,6 +13,117 @@ MCP server for [AgentPlanner](https://agentplanner.io) — AI agent orchestratio
 
 ## Setup
 
+### Claude Desktop — one-click install (`.mcpb`)
+
+The fastest path. Download `agent-planner.mcpb` from the [latest release](https://github.com/TAgents/agent-planner-mcp/releases), double-click it, and Claude Desktop will install the extension and prompt for your AgentPlanner API token. No Node.js setup, no JSON editing.
+
+To build the bundle yourself:
+
+```bash
+npm run build:mcpb        # produces agent-planner.mcpb
+npm run validate:mcpb     # schema-check manifest.json
+```
+
+### Manual config (Claude Desktop, Claude Code, Cursor, etc.)
+
+Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "agentplanner": {
+      "command": "npx",
+      "args": ["-y", "agent-planner-mcp"],
+      "env": {
+        "API_URL": "https://agentplanner.io/api",
+        "USER_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Thin local client (v1)
+
+A lightweight CLI loop for task-driven workflows. No MCP client required — useful when an agent (Claude Code, OpenClaw, a script) just needs to read its current task as files and write status back.
+
+### Mental model
+
+- AgentPlanner (the API) is the source of truth.
+- `.agentplanner/` files are a regeneratable cache, written by the CLI for the agent to read.
+- The agent works in the real repo. Status changes flow back via explicit writeback commands. There is no live sync.
+
+> **Running locally?** See [agent-planner/LOCAL_QUICKSTART.md](https://github.com/TAgents/agent-planner/blob/main/LOCAL_QUICKSTART.md) for the 5-minute path to a full local stack you can point this CLI at. Use `--api-url http://localhost:3000` in the `login` step below.
+
+### The loop
+
+```bash
+# 1. Login — saves credentials and auto-selects a default plan
+#    (pass --plan-id to pick one, or it auto-selects if you have exactly one plan)
+npx agent-planner-mcp login --token <token> --api-url https://agentplanner.io/api [--plan-id <id>]
+#    Localhost variant (after `docker compose -f docker-compose.local.yml up`):
+npx agent-planner-mcp login --token <token> --api-url http://localhost:3000
+
+# 2. See your task queue
+npx agent-planner-mcp tasks [--plan-id <id>]
+
+# 3. Pick the next task and pull context (claims it for 30 minutes)
+npx agent-planner-mcp next [--plan-id <id>]
+#    Force a fresh recommendation even if you have active work:
+npx agent-planner-mcp next --fresh
+
+# 4. Or pull context for a specific plan/node (no claim, no status change)
+npx agent-planner-mcp context --plan-id <plan-id> --node-id <node-id>
+#    If a default plan is set, --plan-id can be omitted:
+npx agent-planner-mcp context --node-id <node-id>
+
+# 5. Explicit writeback. No live sync.
+npx agent-planner-mcp start                          # claim + mark in_progress
+npx agent-planner-mcp blocked --message "Waiting on API decision"
+npx agent-planner-mcp done    --message "Implemented and verified"
+```
+
+### `next` resolution order
+
+`next` is a smart picker. It resolves in this order:
+
+1. **Resume** — if any task in scope is `in_progress`, pick it. (Source: `resume_in_progress`.)
+2. **Recommend** — call `suggest_next_tasks` (dependency- and RPI-aware) for a fresh pick. (Source: `suggest_next_tasks`.)
+3. **Fallback** — first `not_started` task in your queue. (Source: `my_tasks_fallback`.)
+
+`tasks` is the queue view; `next` is the smart picker; `next --fresh` skips step 1 and forces a fresh recommendation even when active work exists.
+
+### What `start`, `blocked`, `done` actually do
+
+| Command | Status | Claim | Log entry | Learning written to Graphiti |
+|---|---|---|---|---|
+| `start` | `in_progress` | claim (30m TTL) | — | — |
+| `blocked --message ...` | `blocked` | release | `challenge` | — |
+| `done --message ...` | `completed` | release | `progress` | yes (entry_type: `learning`) |
+
+All hooks are best-effort: claim/release/learning failures do not block the status update. Claim collisions (another agent already holds the lease) are reported but not fatal.
+
+### What `current-task.md` surfaces
+
+Beyond title, description, agent_instructions, and acceptance criteria, the generated `current-task.md` includes BDI signals from the API responses already being fetched:
+
+- **Plan health** — `quality_score`, rationale, `coherence_checked_at` (or "never")
+- **Coherence warning** — flagged when `node.coherence_status` is `contradiction_detected` or `stale_beliefs`, with concrete next-step pointers (`check_contradictions`, `recall_knowledge`)
+- **Detected contradictions** — listed when present in the node context
+- **Task mode** — shown when not `free` (RPI awareness for `research`/`plan`/`implement`)
+- **Linked goals**, **relevant knowledge** (top 5), **plan progress snapshot**
+
+### When to use CLI vs MCP vs API skill
+
+| You want… | Use |
+|---|---|
+| Zero-setup local task context for any coding agent (Claude Code, OpenClaw, scripts) | **CLI** (this thin client) |
+| Rich, structured tool access from inside an MCP-aware agent (Claude Desktop, Cursor, etc.) | **MCP** (run `npx agent-planner-mcp` as an MCP server) |
+| Direct programmatic integration from your own service | **API** (REST endpoints; same routes the MCP and CLI use) |
+
+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).
+
+
 ### Claude Desktop
 
 Add to your `claude_desktop_config.json`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {
@@ -15,6 +15,8 @@
     "test:tools": "node test-tools.js",
     "setup": "node src/setup.js",
     "setup-claude-code": "node src/setup-claude-code.js",
+    "build:mcpb": "npm install --omit=dev --ignore-scripts && npx --yes @anthropic-ai/mcpb pack . agent-planner.mcpb",
+    "validate:mcpb": "npx --yes @anthropic-ai/mcpb validate manifest.json",
     "prepublishOnly": "echo 'Ready to publish agent-planner-mcp'"
   },
   "keywords": [

package/src/api-client.js

@@ -727,6 +727,17 @@ const graphiti = {
   }
 };
 
+// ─── Users (my-tasks queue) ────────────────────────────────────
+const users = {
+  getMyTasks: async (options = {}) => {
+    const params = new URLSearchParams();
+    if (options.plan_id) params.append('plan_id', options.plan_id);
+    const qs = params.toString() ? `?${params.toString()}` : '';
+    const response = await apiClient.get(`/users/my-tasks${qs}`);
+    return response.data;
+  },
+};
+
 // ─── Dependencies (cross-plan & external) ─────────────────────
 const dependencies = {
   /**
@@ -765,10 +776,10 @@ const dependencies = {
  * @param {string} token - API token or JWT
  * @returns {Object} - API client modules (plans, nodes, etc.)
  */
-function createApiClient(token) {
+function createApiClient(token, options = {}) {
   const scheme = getAuthScheme(token);
   const client = axios.create({
-    baseURL: process.env.API_URL || 'http://localhost:3000',
+    baseURL: options.apiUrl || process.env.API_URL || 'http://localhost:3000',
     headers: {
       'Content-Type': 'application/json',
       'Authorization': token ? `${scheme} ${token}` : undefined
@@ -818,6 +829,10 @@ function createApiClient(token) {
       claimTask: async (planId, nodeId, agentId = 'mcp-agent', ttlMinutes = 30) => (await client.post(`/plans/${planId}/nodes/${nodeId}/claim`, { agent_id: agentId, ttl_minutes: ttlMinutes })).data,
       releaseTask: async (planId, nodeId, agentId = 'mcp-agent') => (await client.delete(`/plans/${planId}/nodes/${nodeId}/claim`, { data: { agent_id: agentId } })).data,
       getTaskClaim: async (planId, nodeId) => (await client.get(`/plans/${planId}/nodes/${nodeId}/claim`)).data,
+      suggestNextTasks: async (planId, limit = 5) => {
+        const params = new URLSearchParams({ plan_id: planId, limit: String(limit) });
+        return (await client.get(`/context/suggest?${params.toString()}`)).data;
+      },
     },
     comments: {
       getComments: async (planId, nodeId) => (await client.get(`/plans/${planId}/nodes/${nodeId}/comments`)).data,
@@ -888,6 +903,12 @@ function createApiClient(token) {
       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,
+      getQuality: async (goalId) => (await client.get(`/goals/${goalId}/quality`)).data,
+    },
+    coherence: {
+      getPending: async () => (await client.get('/coherence/pending')).data,
+      runCheck: async (planId, goalId) => (await client.post(`/plans/${planId}/coherence/check`, goalId ? { goal_id: goalId } : {})).data,
+      getPlanCoherence: async (planId) => (await client.get(`/plans/${planId}/coherence`)).data,
     },
     context: {
       getNodeContext: async (nodeId, options = {}) => {
@@ -916,6 +937,14 @@ function createApiClient(token) {
       listCrossPlan: async (planIds) => (await client.get('/dependencies/cross-plan', { params: { plan_ids: planIds.join(',') } })).data,
       createExternal: async (data) => (await client.post('/dependencies/external', data)).data,
     },
+    users: {
+      getMyTasks: async (options = {}) => {
+        const params = new URLSearchParams();
+        if (options.plan_id) params.append('plan_id', options.plan_id);
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        return (await client.get(`/users/my-tasks${qs}`)).data;
+      },
+    },
     axiosInstance: client,
   };
 }
@@ -945,6 +974,7 @@ module.exports = {
   graphiti,
   dependencies,
   coherence,
+  users,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/cli/config.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function getConfigDir() {
+  if (process.env.AGENT_PLANNER_CONFIG_DIR) {
+    return process.env.AGENT_PLANNER_CONFIG_DIR;
+  }
+
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'agent-planner');
+  }
+
+  return path.join(os.homedir(), '.config', 'agent-planner');
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readConfig() {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function writeConfig(config) {
+  const configDir = getConfigDir();
+  ensureDir(configDir);
+  const configPath = getConfigPath();
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  return configPath;
+}
+
+function resolveApiConfig(overrides = {}) {
+  const config = readConfig();
+  return {
+    apiUrl: overrides.apiUrl || process.env.API_URL || config.apiUrl || 'http://localhost:3000',
+    token: overrides.token || process.env.USER_API_TOKEN || process.env.API_TOKEN || config.token || null,
+  };
+}
+
+function mergeConfig(partial) {
+  const existing = readConfig();
+  return writeConfig({ ...existing, ...partial, updatedAt: new Date().toISOString() });
+}
+
+module.exports = {
+  ensureDir,
+  getConfigDir,
+  getConfigPath,
+  readConfig,
+  writeConfig,
+  mergeConfig,
+  resolveApiConfig,
+};

package/src/cli/local-client.js

@@ -0,0 +1,646 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { createApiClient } = require('../api-client');
+const { ensureDir, getConfigPath, mergeConfig, readConfig, resolveApiConfig, writeConfig } = require('./config');
+
+const DEFAULT_AGENT_ID = 'ap-cli';
+const DEFAULT_CLAIM_TTL_MIN = 30;
+
+function parseArgs(args = []) {
+  const positional = [];
+  const options = {};
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const keyValue = arg.slice(2).split('=');
+    const key = keyValue[0].replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (keyValue.length > 1) {
+      options[key] = keyValue.slice(1).join('=');
+      continue;
+    }
+
+    const next = args[i + 1];
+    if (!next || next.startsWith('--')) {
+      options[key] = true;
+      continue;
+    }
+
+    options[key] = next;
+    i += 1;
+  }
+
+  return { positional, options };
+}
+
+async function promptForLogin(options) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const prompt = (question) => new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+
+  const apiUrl = options.apiUrl || await prompt('API URL (default: https://agentplanner.io/api): ') || 'https://agentplanner.io/api';
+  const token = options.token || await prompt('API token: ');
+  rl.close();
+
+  if (!token) {
+    throw new Error('API token is required. Pass --token or run in an interactive terminal.');
+  }
+
+  return { apiUrl, token };
+}
+
+async function login(options = {}) {
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const credentials = (options.token && options.apiUrl)
+    ? { apiUrl: options.apiUrl, token: options.token }
+    : interactive
+      ? await promptForLogin(options)
+      : (() => {
+          if (!options.token) {
+            throw new Error('Missing token. Pass --token for non-interactive login.');
+          }
+          return {
+            apiUrl: options.apiUrl || 'https://agentplanner.io/api',
+            token: options.token,
+          };
+        })();
+
+  const api = createApiClient(credentials.token, { apiUrl: credentials.apiUrl });
+  const plans = await api.plans.getPlans();
+
+  const configData = {
+    apiUrl: credentials.apiUrl,
+    token: credentials.token,
+    updatedAt: new Date().toISOString(),
+  };
+
+  let defaultPlanId = null;
+  if (options.planId) {
+    defaultPlanId = options.planId;
+  } else if (Array.isArray(plans) && plans.length === 1) {
+    defaultPlanId = plans[0].id;
+  }
+  if (defaultPlanId) {
+    configData.defaultPlanId = defaultPlanId;
+  }
+
+  const configPath = writeConfig(configData);
+
+  return {
+    configPath,
+    apiUrl: credentials.apiUrl,
+    defaultPlanId,
+  };
+}
+
+function getWorkspaceStatePath(baseDir = process.cwd()) {
+  return path.join(baseDir, '.agentplanner');
+}
+
+function getWorkspaceContextPath(baseDir = process.cwd()) {
+  return path.join(getWorkspaceStatePath(baseDir), 'context.json');
+}
+
+function readWorkspaceContext(baseDir = process.cwd()) {
+  const contextPath = getWorkspaceContextPath(baseDir);
+  if (!fs.existsSync(contextPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(contextPath, 'utf8'));
+}
+
+function resolveSelection(options = {}, baseDir = process.cwd()) {
+  const workspaceContext = readWorkspaceContext(baseDir) || {};
+  const config = readConfig();
+  return {
+    planId: options.planId || workspaceContext.selection?.planId || config.defaultPlanId || null,
+    nodeId: options.nodeId || workspaceContext.selection?.nodeId || null,
+  };
+}
+
+function renderPlanTree(nodes = []) {
+  const lines = [];
+
+  function walk(node, depth) {
+    const indent = '  '.repeat(depth);
+    const marker = node.node_type === 'phase' ? '▸' : node.node_type === 'milestone' ? '◆' : '•';
+    const status = node.status ? ` [${node.status}]` : '';
+    lines.push(`${indent}${marker} ${node.title}${status}`);
+    for (const child of node.children || []) {
+      walk(child, depth + 1);
+    }
+  }
+
+  for (const node of nodes) {
+    walk(node, 0);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function stringifyJson(data) {
+  return JSON.stringify(data, null, 2) + '\n';
+}
+
+function renderBulletList(items = []) {
+  return items.filter(Boolean).map((item) => `- ${item}`);
+}
+
+function extractAcceptanceCriteria(text = '') {
+  const match = text.match(/Acceptance criteria:\s*([\s\S]*)/i);
+  if (!match) return [];
+
+  return match[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('-'))
+    .map((line) => line.replace(/^-\s*/, '').trim());
+}
+
+function stripAcceptanceCriteria(text = '') {
+  return text.replace(/\n*Acceptance criteria:\s*[\s\S]*/i, '').trim();
+}
+
+function renderPlanHealth(plan) {
+  if (!plan) return [];
+  const hasQuality = plan.quality_score !== null && plan.quality_score !== undefined;
+  const hasChecked = Boolean(plan.coherence_checked_at);
+  if (!hasQuality && !hasChecked) return [];
+
+  const out = ['## Plan health', ''];
+  if (hasQuality) {
+    out.push(`- Quality score: ${plan.quality_score}`);
+    if (plan.quality_rationale) {
+      out.push(`- Rationale: ${plan.quality_rationale}`);
+    }
+  }
+  out.push(`- Last coherence check: ${hasChecked ? plan.coherence_checked_at : 'never'}`);
+  if (!hasChecked) {
+    out.push('- Run `run_coherence_check` (MCP) before acting on stale plans.');
+  }
+  out.push('');
+  return out;
+}
+
+function renderCoherenceWarning(task) {
+  if (!task || !task.coherence_status) return [];
+  const status = task.coherence_status;
+  if (status === 'clean' || status === 'unchecked') return [];
+
+  const out = ['## Coherence warning', ''];
+  out.push(`- Status: ${status}`);
+  if (status === 'contradiction_detected') {
+    out.push('- Supporting knowledge contains contradictions. Run `check_contradictions` (MCP) and re-verify before acting.');
+  } else if (status === 'stale_beliefs') {
+    out.push('- Knowledge backing this task may be outdated. Run `recall_knowledge` (MCP) to refresh before deciding.');
+  }
+  out.push('');
+  return out;
+}
+
+function renderContradictions(nodeContext) {
+  const list = Array.isArray(nodeContext?.contradictions) ? nodeContext.contradictions : [];
+  if (!list.length) return [];
+
+  const out = ['## Detected contradictions', ''];
+  out.push(...renderBulletList(
+    list.slice(0, 5).map((c) => c.summary || c.content || c.message || JSON.stringify(c)),
+  ));
+  out.push('');
+  return out;
+}
+
+function renderCurrentTask(selection, plan, nodeContext, planContext) {
+  const lines = [];
+  lines.push(`# ${selection.nodeId && nodeContext?.node ? nodeContext.node.title : plan.title}`);
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- Plan: ${plan.title}`);
+  lines.push(`- Plan ID: ${plan.id}`);
+  if (selection.nodeId && nodeContext?.node) {
+    lines.push(`- Task ID: ${selection.nodeId}`);
+    lines.push(`- Status: ${nodeContext.node.status || 'unknown'}`);
+    if (nodeContext.node.task_mode && nodeContext.node.task_mode !== 'free') {
+      lines.push(`- Task mode: ${nodeContext.node.task_mode}`);
+    }
+  }
+  lines.push(`- Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  lines.push(...renderPlanHealth(plan));
+
+  if (!selection.nodeId || !nodeContext?.node) {
+    lines.push('No node selected. Re-run with --node-id to materialize a task-specific current-task.md.');
+    lines.push('');
+    lines.push('Generated file. Safe to overwrite with `agent-planner-mcp context ...`.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const task = nodeContext.node;
+  const ancestry = Array.isArray(nodeContext.ancestry) ? nodeContext.ancestry : [];
+  const parentPhase = ancestry.find((item) => item.node_type === 'phase');
+  const acceptanceCriteria = extractAcceptanceCriteria(task.description || '');
+  const description = stripAcceptanceCriteria(task.description || '');
+  const knowledge = (nodeContext.knowledge || []).slice(0, 5).map((item) => item.content);
+  const phaseSummaries = (planContext?.phases || []).map((phase) => `${phase.title}: ${phase.completed_tasks}/${phase.total_tasks} complete`);
+
+  lines.push(...renderCoherenceWarning(task));
+  lines.push(...renderContradictions(nodeContext));
+
+  if (parentPhase) {
+    lines.push('## Placement');
+    lines.push('');
+    lines.push(`- Phase: ${parentPhase.title}`);
+    lines.push(`- Phase status: ${parentPhase.status || 'unknown'}`);
+    lines.push('');
+  }
+
+  if (description) {
+    lines.push('## Task');
+    lines.push('');
+    lines.push(description);
+    lines.push('');
+  }
+
+  if (task.context) {
+    lines.push('## Implementation context');
+    lines.push('');
+    lines.push(task.context);
+    lines.push('');
+  }
+
+  if (task.agent_instructions) {
+    lines.push('## Agent instructions');
+    lines.push('');
+    lines.push(task.agent_instructions);
+    lines.push('');
+  }
+
+  if (acceptanceCriteria.length) {
+    lines.push('## Acceptance criteria');
+    lines.push('');
+    lines.push(...renderBulletList(acceptanceCriteria));
+    lines.push('');
+  }
+
+  const goalsData = (nodeContext.goals || []).concat(
+    (planContext?.goals || []).filter(
+      (pg) => !(nodeContext.goals || []).some((ng) => ng.id === pg.id)
+    )
+  );
+  if (goalsData.length) {
+    lines.push('## Linked goals');
+    lines.push('');
+    lines.push(...goalsData.map((g) => `- ${g.title || g.name}${g.status ? ` [${g.status}]` : ''}`));
+    lines.push('');
+  }
+
+  if (knowledge.length) {
+    lines.push('## Relevant knowledge');
+    lines.push('');
+    lines.push(...renderBulletList(knowledge));
+    lines.push('');
+  }
+
+  if (phaseSummaries.length) {
+    lines.push('## Plan progress snapshot');
+    lines.push('');
+    lines.push(...renderBulletList(phaseSummaries));
+    lines.push('');
+  }
+
+  lines.push('## Suggested loop');
+  lines.push('');
+  lines.push('- Run `agent-planner-mcp start` when you begin active work (claims the task for 30 min).');
+  lines.push('- Do the implementation work in the repo, not in `.agentplanner/`.');
+  lines.push('- If blocked, run `agent-planner-mcp blocked --message "why"` (releases the claim).');
+  lines.push('- When complete, run `agent-planner-mcp done --message "what changed"` (logs progress and writes a learning to the temporal graph).');
+  lines.push('- Refresh with `agent-planner-mcp context --plan-id ... --node-id ...` when you need updated context.');
+  lines.push('');
+  lines.push('## Source of truth');
+  lines.push('');
+  lines.push('- AgentPlanner (the API) is the source of truth for this plan and task.');
+  lines.push('- Files under `.agentplanner/` are a regeneratable cache produced by `agent-planner-mcp context`.');
+  lines.push('- Do not hand-edit `.agentplanner/` files; changes here are not synced back. Use the writeback commands above.');
+  lines.push('- Safe to delete `.agentplanner/` at any time — re-run `context` or `next` to repopulate.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function materializeContext(options = {}) {
+  const baseDir = path.resolve(options.dir || process.cwd());
+  const selection = resolveSelection(options, baseDir);
+  if (!selection.planId) {
+    throw new Error('Missing plan id. Pass --plan-id or run context after generating workspace state.');
+  }
+
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const api = createApiClient(token, { apiUrl });
+  const stateDir = getWorkspaceStatePath(baseDir);
+  ensureDir(stateDir);
+
+  const [plan, nodes, planContext, nodeContext] = await Promise.all([
+    api.plans.getPlan(selection.planId),
+    api.nodes.getNodes(selection.planId),
+    api.context.getPlanContext(selection.planId),
+    selection.nodeId ? api.context.getNodeContext(selection.nodeId) : Promise.resolve(null),
+  ]);
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    apiUrl,
+    selection,
+    plan,
+    planContext,
+    nodeContext,
+  };
+
+  fs.writeFileSync(path.join(stateDir, 'context.json'), stringifyJson(payload));
+  fs.writeFileSync(path.join(stateDir, 'plan-tree.md'), renderPlanTree(nodes));
+  fs.writeFileSync(path.join(stateDir, 'current-task.md'), renderCurrentTask(selection, plan, nodeContext, planContext));
+
+  return {
+    stateDir,
+    selection,
+  };
+}
+
+async function tryClaim(api, planId, nodeId, options = {}) {
+  if (typeof api.nodes?.claimTask !== 'function') return false;
+  try {
+    await api.nodes.claimTask(
+      planId,
+      nodeId,
+      options.agentId || DEFAULT_AGENT_ID,
+      Number(options.ttl) || DEFAULT_CLAIM_TTL_MIN,
+    );
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function tryRelease(api, planId, nodeId, options = {}) {
+  if (typeof api.nodes?.releaseTask !== 'function') return false;
+  try {
+    await api.nodes.releaseTask(planId, nodeId, options.agentId || DEFAULT_AGENT_ID);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function tryRecordLearning(api, { planId, nodeId, taskTitle, message }) {
+  if (!message || typeof api.graphiti?.addEpisode !== 'function') return false;
+  try {
+    await api.graphiti.addEpisode({
+      content: message,
+      name: taskTitle ? `[done] ${taskTitle}` : `[done] ${nodeId}`,
+      plan_id: planId,
+      node_id: nodeId,
+      metadata: { entry_type: 'learning', source: DEFAULT_AGENT_ID },
+    });
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function updateStatus(command, options = {}) {
+  const statusMap = {
+    start: 'in_progress',
+    blocked: 'blocked',
+    done: 'completed',
+  };
+  const logTypeMap = {
+    blocked: 'challenge',
+    done: 'progress',
+  };
+
+  const baseDir = path.resolve(options.dir || process.cwd());
+  const selection = resolveSelection(options, baseDir);
+  if (!selection.planId || !selection.nodeId) {
+    throw new Error('Missing plan/node selection. Pass --plan-id and --node-id, or run context with both first.');
+  }
+
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const api = createApiClient(token, { apiUrl });
+  await api.nodes.updateNodeStatus(selection.planId, selection.nodeId, statusMap[command]);
+
+  let logged = false;
+  if (options.message && logTypeMap[command]) {
+    await api.logs.addLogEntry(selection.planId, selection.nodeId, {
+      content: options.message,
+      log_type: logTypeMap[command],
+    });
+    logged = true;
+  }
+
+  let claimed = false;
+  let released = false;
+  let learned = false;
+
+  if (command === 'start') {
+    claimed = await tryClaim(api, selection.planId, selection.nodeId, options);
+  } else if (command === 'blocked' || command === 'done') {
+    released = await tryRelease(api, selection.planId, selection.nodeId, options);
+  }
+
+  if (command === 'done' && options.message) {
+    const workspaceContext = readWorkspaceContext(baseDir);
+    const taskTitle = workspaceContext?.nodeContext?.node?.title;
+    learned = await tryRecordLearning(api, {
+      planId: selection.planId,
+      nodeId: selection.nodeId,
+      taskTitle,
+      message: options.message,
+    });
+  }
+
+  return {
+    planId: selection.planId,
+    nodeId: selection.nodeId,
+    status: statusMap[command],
+    logged,
+    claimed,
+    released,
+    learned,
+  };
+}
+
+async function getMyTasks(options = {}) {
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const config = readConfig();
+  const planId = options.planId || config.defaultPlanId || null;
+  const api = createApiClient(token, { apiUrl });
+  const fetchOptions = {};
+  if (planId) fetchOptions.plan_id = planId;
+
+  const tasks = await api.users.getMyTasks(fetchOptions);
+  if (!planId) {
+    return { tasks, planId };
+  }
+
+  const taskList = Array.isArray(tasks) ? tasks : tasks?.tasks;
+  if (!Array.isArray(taskList)) {
+    return { tasks, planId };
+  }
+
+  const filteredTasks = taskList.filter((task) => task.plan_id === planId);
+  if (Array.isArray(tasks)) {
+    return { tasks: filteredTasks, planId };
+  }
+
+  return {
+    tasks: {
+      ...tasks,
+      tasks: filteredTasks,
+    },
+    planId,
+  };
+}
+
+function normalizeSuggestion(suggestion, planId) {
+  if (!suggestion) return null;
+  const id = suggestion.id || suggestion.node_id;
+  if (!id) return null;
+  return {
+    id,
+    title: suggestion.title,
+    status: suggestion.status,
+    plan_id: suggestion.plan_id || planId,
+    task_mode: suggestion.task_mode,
+    knowledge_ready: suggestion.knowledge_ready,
+    ...suggestion,
+  };
+}
+
+async function pickViaSuggestNextTasks(api, planId, limit) {
+  if (!planId || typeof api.nodes?.suggestNextTasks !== 'function') return null;
+  try {
+    const suggestions = await api.nodes.suggestNextTasks(planId, limit);
+    const list = Array.isArray(suggestions)
+      ? suggestions
+      : (suggestions?.suggestions || suggestions?.tasks || []);
+    if (!list.length) return null;
+    return normalizeSuggestion(list[0], planId);
+  } catch (_err) {
+    return null;
+  }
+}
+
+async function pickFromQueue(options, status) {
+  try {
+    const { tasks, planId: queuePlanId } = await getMyTasks(options);
+    const list = Array.isArray(tasks) ? tasks : tasks?.tasks || [];
+    const match = list.find((t) => t.status === status);
+    if (!match) return null;
+    if (!match.plan_id && queuePlanId) match.plan_id = queuePlanId;
+    return match;
+  } catch (_err) {
+    return null;
+  }
+}
+
+async function getNextTask(options = {}) {
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const config = readConfig();
+  const planId = options.planId || config.defaultPlanId || null;
+  const api = createApiClient(token, { apiUrl });
+  const fresh = Boolean(options.fresh);
+
+  // Resolution order:
+  //  1. Resume any in_progress task in scope (unless --fresh).
+  //  2. Dependency-aware recommendation via suggest_next_tasks.
+  //  3. Fallback: first not_started task in the my-tasks queue.
+  //
+  // `tasks` is the queue view; `next` is the smart picker. `next --fresh`
+  // forces a fresh recommendation even when active work exists.
+
+  let chosen = null;
+  let source = null;
+
+  if (!fresh) {
+    chosen = await pickFromQueue(options, 'in_progress');
+    if (chosen) source = 'resume_in_progress';
+  }
+
+  if (!chosen) {
+    chosen = await pickViaSuggestNextTasks(api, planId, options.limit ? Number(options.limit) : 5);
+    if (chosen) source = 'suggest_next_tasks';
+  }
+
+  if (!chosen) {
+    chosen = await pickFromQueue(options, 'not_started');
+    if (chosen) source = 'my_tasks_fallback';
+  }
+
+  if (!chosen) {
+    throw new Error('No actionable tasks (in_progress or not_started) found.');
+  }
+
+  const taskPlanId = chosen.plan_id || planId;
+  if (!taskPlanId) {
+    throw new Error('Could not determine plan_id for the selected task. Pass --plan-id explicitly.');
+  }
+
+  const claimed = await tryClaim(api, taskPlanId, chosen.id, options);
+
+  const contextResult = await materializeContext({
+    ...options,
+    planId: taskPlanId,
+    nodeId: chosen.id,
+  });
+
+  return {
+    task: chosen,
+    planId: taskPlanId,
+    stateDir: contextResult.stateDir,
+    claimed,
+    source,
+  };
+}
+
+module.exports = {
+  getMyTasks,
+  getNextTask,
+  getWorkspaceContextPath,
+  getWorkspaceStatePath,
+  login,
+  materializeContext,
+  parseArgs,
+  readWorkspaceContext,
+  renderCurrentTask,
+  renderPlanTree,
+  resolveSelection,
+  updateStatus,
+};

package/src/cli.js

@@ -1,39 +1,57 @@
 #!/usr/bin/env node
 
 /**
- * CLI Entry Point for agent-planner-mcp
- * Routes to different commands or starts the MCP server
+ * CLI entry point for agent-planner-mcp.
+ * Preserves the existing MCP server/setup commands while adding
+ * a thin local-client loop for login/context/status writeback.
  */
 
-const path = require('path');
+const { getMyTasks, getNextTask, materializeContext, login, parseArgs, updateStatus } = require('./cli/local-client');
 
 const args = process.argv.slice(2);
 const command = args[0];
+const { options } = parseArgs(args.slice(1));
 
-// Route to different commands
-switch (command) {
-  case 'setup-claude-code':
-    // Run the setup-claude-code script
-    const setupClaudeCode = require('./setup-claude-code.js');
-    setupClaudeCode.main();
-    break;
-
-  case 'setup':
-    // Run the interactive setup wizard
-    require('./setup.js');
-    break;
-
-  case '--help':
-  case '-h':
-  case 'help':
-    console.log(`
-Agent Planner MCP - Model Context Protocol Server
+function printHelp() {
+  console.log(`
+Agent Planner MCP - MCP server + thin local client
 
 Usage:
-  npx agent-planner-mcp                    Start MCP server (requires USER_API_TOKEN)
-  npx agent-planner-mcp setup-claude-code  Install orchestration commands to .claude/
-  npx agent-planner-mcp setup              Interactive setup wizard
-  npx agent-planner-mcp --help             Show this help message
+  npx agent-planner-mcp                          Start MCP server (requires USER_API_TOKEN)
+  npx agent-planner-mcp setup-claude-code       Install orchestration commands to .claude/
+  npx agent-planner-mcp setup                   Interactive setup wizard
+  npx agent-planner-mcp login --token <token> [--api-url <url>] [--plan-id <id>]
+  npx agent-planner-mcp tasks [--plan-id <id>]
+  npx agent-planner-mcp next [--plan-id <id>] [--fresh]
+  npx agent-planner-mcp context --plan-id <id> [--node-id <id>] [--dir <path>]
+  npx agent-planner-mcp start [--plan-id <id>] [--node-id <id>]
+  npx agent-planner-mcp blocked [--plan-id <id>] [--node-id <id>] [--message "..."]
+  npx agent-planner-mcp done [--plan-id <id>] [--node-id <id>] [--message "..."]
+  npx agent-planner-mcp --help
+
+Commands:
+  login    Authenticate and store credentials. If --plan-id is passed it is
+           saved as the default plan. If exactly one plan is accessible, it is
+           auto-selected as the default.
+  tasks    Queue view: list tasks assigned to you (uses /users/my-tasks).
+           Filters by --plan-id or falls back to the stored default plan.
+  next     Smart picker. Resolution order: (1) resume any in_progress task
+           in scope, (2) dependency-aware recommendation via suggest_next_tasks,
+           (3) fall back to first not_started task in your queue. Claims the
+           picked task for 30 minutes and materializes its context files.
+           Pass --fresh to skip step 1 and force a fresh recommendation
+           even when active work exists.
+  context  Pull context for a specific plan/node and write .agentplanner/ files
+           (a regeneratable cache; AgentPlanner remains the source of truth).
+           Surfaces plan health (quality, coherence) and any contradictions
+           detected on the task. --node-id can be used alone when a default
+           plan is set.
+  start    Mark the current task as in_progress and claim it (30-minute TTL).
+  blocked  Mark the current task as blocked and release the claim. Optional
+           --message is logged as a challenge entry.
+  done     Mark the current task as completed and release the claim. Optional
+           --message is logged as progress AND written to the temporal
+           knowledge graph as a learning episode.
 
 Environment Variables:
   API_URL          - Agent Planner API URL (default: http://localhost:3000)
@@ -44,21 +62,104 @@ Environment Variables:
 Documentation:
   https://github.com/talkingagents/agent-planner-mcp
 `);
-    break;
-
-  case '--version':
-  case '-v':
-    const pkg = require('../package.json');
-    console.log(`agent-planner-mcp v${pkg.version}`);
-    break;
-
-  default:
-    // No command or unknown command - start MCP server
-    if (command && !command.startsWith('-')) {
-      console.error(`Unknown command: ${command}`);
-      console.error('Run "npx agent-planner-mcp --help" for usage information.');
-      process.exit(1);
+}
+
+async function main() {
+  switch (command) {
+    case 'setup-claude-code': {
+      const setupClaudeCode = require('./setup-claude-code.js');
+      setupClaudeCode.main();
+      return;
+    }
+
+    case 'setup':
+      require('./setup.js');
+      return;
+
+    case 'login': {
+      const result = await login(options);
+      console.log(`Saved credentials to ${result.configPath}`);
+      console.log(`API URL: ${result.apiUrl}`);
+      if (result.defaultPlanId) {
+        console.log(`Default plan: ${result.defaultPlanId}`);
+      }
+      return;
+    }
+
+    case 'tasks': {
+      const result = await getMyTasks(options);
+      const taskList = Array.isArray(result.tasks) ? result.tasks : result.tasks?.tasks || [];
+      if (result.planId) {
+        console.log(`Tasks for plan ${result.planId}:`);
+      } else {
+        console.log('All tasks:');
+      }
+      if (!taskList.length) {
+        console.log('  (no tasks)');
+        return;
+      }
+      for (const t of taskList) {
+        const plan = t.plan_id && t.plan_id !== result.planId ? ` (plan: ${t.plan_id})` : '';
+        console.log(`  [${t.status || '?'}] ${t.title || t.id}${plan}`);
+      }
+      return;
+    }
+
+    case 'next': {
+      const result = await getNextTask(options);
+      console.log(`Selected task: ${result.task.title || result.task.id} [${result.task.status}]`);
+      console.log(`Plan: ${result.planId}`);
+      console.log(`Source: ${result.source}`);
+      if (result.claimed) console.log('Claimed task for 30 minutes.');
+      console.log(`Context written to ${result.stateDir}`);
+      return;
     }
-    // Start the MCP server
-    require('./index.js');
+
+    case 'context': {
+      const result = await materializeContext(options);
+      console.log(`Wrote generated context files to ${result.stateDir}`);
+      if (result.selection.nodeId) {
+        console.log(`Selected node: ${result.selection.nodeId}`);
+      }
+      return;
+    }
+
+    case 'start':
+    case 'blocked':
+    case 'done': {
+      const result = await updateStatus(command, options);
+      console.log(`Updated ${result.nodeId} to ${result.status}`);
+      if (result.logged) console.log('Added log entry.');
+      if (result.claimed) console.log('Claimed task.');
+      if (result.released) console.log('Released task claim.');
+      if (result.learned) console.log('Recorded learning to temporal knowledge graph.');
+      return;
+    }
+
+    case '--help':
+    case '-h':
+    case 'help':
+      printHelp();
+      return;
+
+    case '--version':
+    case '-v': {
+      const pkg = require('../package.json');
+      console.log(`agent-planner-mcp v${pkg.version}`);
+      return;
+    }
+
+    default:
+      if (command && !command.startsWith('-')) {
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "npx agent-planner-mcp --help" for usage information.');
+        process.exit(1);
+      }
+      require('./index.js');
+  }
 }
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exit(1);
+});