agent-planner-mcp 1.4.1 → 1.5.1

package/AGENT_GUIDE.md

@@ -42,13 +42,14 @@ get_started()
 ### Intentions — creation (v1.0)
 | Tool | When |
 |---|---|
-| `form_intention` | Create plan + initial tree under a goal, atomically |
+| `form_intention` | Create plan + initial tree under a goal, atomically. Declare order inline with `ref`/`depends_on` (→ `blocks` edges); warns `created_without_dependencies` |
 | `extend_intention` | Add children under existing parent (lightweight, no queue) |
 | `propose_research_chain` | RPI triple with 2 blocking edges in one call |
 
 ### Intentions — structural mutation (v1.0)
 | Tool | When |
 |---|---|
+| `list_plans` | List plans (filter by status / visibility / workspace) |
 | `update_plan` | Edit plan title/description/status/visibility/metadata |
 | `update_node` | Edit any node property except status |
 | `move_node` | Reparent within plan; cycle-safe |
@@ -148,9 +149,9 @@ Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue
 ## Atomic patterns to remember
 
 - `update_task` does status + log + claim release + learning in one call. Don't decompose.
-- `claim_next_task` does suggest + claim + context. Don't decompose.
+- `claim_next_task` does suggest + claim + context. Don't decompose. Fails closed — an empty result is structured: `reason: no_work_in_scope` (nothing left) vs `blocked_on_dep` (work remains but all of it is dependency-blocked). Don't treat empty as "done" without checking `reason`.
 - `briefing` does goals + decisions + tasks + activity + recommendation. Don't decompose.
-- `form_intention` creates plan + tree atomically. Don't trickle node-by-node.
+- `form_intention` creates plan + tree atomically — and declares execution order inline via `ref`/`depends_on` (don't ship a bare hierarchy with no edges). Don't trickle node-by-node.
 - `share_plan` does visibility + add + remove in one call. Don't fan out.
 
 ## Output discipline

package/SKILL.md

@@ -54,11 +54,12 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `add_learning` — record a knowledge episode for future recall
 
 **Creation (v1.0):**
-- `form_intention` — create a plan + initial phase/task tree under a goal, atomically
+- `form_intention` — create a plan + initial phase/task tree under a goal, atomically. **Declare execution order inline:** give nodes a `ref` and list prerequisites in `depends_on` (refs or titles) to create `blocks` edges in the same call. Returns a `structure` summary and warns `created_without_dependencies` when a multi-task plan has no edges — don't ship a bare hierarchy with no executable ordering. Every plan it creates is provenance-stamped (`created_by: agent-planner-mcp@<version>`) for version-drift diagnosis.
 - `extend_intention` — add children under an existing phase or task (lightweight, no decision-queue gate)
 - `propose_research_chain` — Research → Plan → Implement triple with two blocking edges, in one call
 
 **Structural mutation (v1.0):**
+- `list_plans` — list plans (filter by status / visibility / workspace)
 - `update_plan` — edit any plan property (title, description, status, visibility, metadata)
 - `update_node` — edit any node property except status (status routes through `update_task`)
 - `move_node` — reparent within the same plan; cycle-safe
@@ -85,7 +86,7 @@ A Workspace is a folder under an Organization that owns goals + plans — a grou
 
 ### Utility
 
-- `get_started` — dynamic reference; call this if you're new to AgentPlanner
+- `get_started` — dynamic reference; call this if you're new to AgentPlanner. Reports `mcp_version` so you can self-report your build (diagnose version drift across OpenClaw / Claude Code / local checkouts).
 
 ## Canonical workflows
 
@@ -138,6 +139,8 @@ claim_next_task({ scope: { plan_id }, dry_run: true })
 claim_next_task({ scope: { plan_id } })  // dry_run defaults to false
 ```
 
+**Fails closed.** When nothing is claimable, `claim_next_task` never hands back a dependency-blind task — it returns a structured no-work result whose `reason` distinguishes `no_work_in_scope` (nothing left to do) from `blocked_on_dep` (work remains, but every remaining task is blocked on an incomplete dependency). Check `reason` before treating an empty result as "done."
+
 ### Proposing subtasks for human approval (v0.9.1+)
 
 For high-touch proposals (entire new directions, structural changes the human should review before they materialize), use `queue_decision` with `proposed_subtasks` — tasks only get created on `resolve_decision({action: 'approve'})`.
@@ -176,11 +179,17 @@ form_intention({
   title: 'Ship new auth flow',
   rationale: 'User-requested plan to migrate auth to passkeys',
   tree: [
-    { node_type: 'phase', title: 'Discovery', children: [...] },
-    { node_type: 'phase', title: 'Implementation', children: [...] },
+    { node_type: 'phase', title: 'Discovery', children: [
+      { ref: 'research', title: 'Research passkey libraries', task_mode: 'research' },
+    ]},
+    { node_type: 'phase', title: 'Implementation', children: [
+      { title: 'Implement passkey flow', task_mode: 'implement', depends_on: ['research'] },
+    ]},
   ]
 })
-// Plan lands as active. No approval needed — user already approved by asking.
+// Active, with a `blocks` edge (research → implement) created inline from depends_on.
+// Response carries a `structure` summary; a multi-task plan with zero edges would
+// return created_without_dependencies + a warning instead.
 ```
 
 ```

package/package.json

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

package/src/oauth/consent.js

@@ -0,0 +1,99 @@
+/**
+ * Consent + login surface for the OAuth authorization step.
+ *
+ * provider.authorize() renders this page (GET /authorize handled by the SDK).
+ * The form POSTs to /oauth/consent, which authenticates against the existing
+ * AgentPlanner /auth/login endpoint and, on success, mints a one-time
+ * authorization code bound to the user's AP credential, then redirects back to
+ * the client's redirect_uri with code + state.
+ */
+const axios = require('axios');
+
+const esc = (s = '') => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+function renderConsentPage(params, { clientName = 'an application', error = null } = {}) {
+  const hidden = (name) => `<input type="hidden" name="${name}" value="${esc(params[name])}">`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect AgentPlanner</title>
+<style>
+  body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#0f1115;color:#e7e9ee;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+  .card{background:#171a21;border:1px solid #262b36;border-radius:14px;padding:32px;width:360px;box-shadow:0 10px 40px rgba(0,0,0,.4)}
+  h1{font-size:18px;margin:0 0 4px}p{color:#9aa3b2;font-size:13px;margin:0 0 20px;line-height:1.5}
+  label{display:block;font-size:12px;color:#9aa3b2;margin:14px 0 6px}
+  input[type=email],input[type=password]{width:100%;box-sizing:border-box;padding:10px 12px;background:#0f1115;border:1px solid #2b3140;border-radius:8px;color:#e7e9ee;font-size:14px}
+  button{margin-top:22px;width:100%;padding:11px;background:#e0a96d;color:#1a1205;border:0;border-radius:8px;font-weight:600;font-size:14px;cursor:pointer}
+  .err{background:#3a1d1d;border:1px solid #6b2b2b;color:#f3b6b6;padding:9px 12px;border-radius:8px;font-size:12px;margin-bottom:14px}
+  .grant{color:#cfd5e1;font-size:12px;margin-top:16px}.grant b{color:#e7e9ee}
+</style></head><body>
+<div class="card">
+  <h1>Connect AgentPlanner</h1>
+  <p><b>${esc(clientName)}</b> wants to access your AgentPlanner plans, goals, and knowledge on your behalf.</p>
+  ${error ? `<div class="err">${esc(error)}</div>` : ''}
+  <form method="POST" action="/oauth/consent">
+    ${hidden('client_id')}${hidden('redirect_uri')}${hidden('code_challenge')}${hidden('code_challenge_method')}${hidden('state')}${hidden('scope')}${hidden('resource')}
+    <label for="email">Email</label>
+    <input id="email" name="email" type="email" autocomplete="username" required>
+    <label for="password">Password</label>
+    <input id="password" name="password" type="password" autocomplete="current-password" required>
+    <button type="submit">Sign in &amp; authorize</button>
+  </form>
+  <div class="grant">Signing in authorizes this connection only. You can disconnect <b>${esc(clientName)}</b> anytime from its connector settings, or from AgentPlanner → Settings → Connections.</div>
+</div></body></html>`;
+}
+
+// Builds the POST /oauth/consent handler. `apiUrl` is the AgentPlanner REST base.
+function makeConsentHandler({ store, apiUrl }) {
+  return async (req, res) => {
+    const b = req.body || {};
+    const params = {
+      client_id: b.client_id,
+      redirect_uri: b.redirect_uri,
+      code_challenge: b.code_challenge,
+      code_challenge_method: b.code_challenge_method,
+      state: b.state,
+      scope: b.scope,
+      resource: b.resource,
+    };
+
+    const client = await store.getClient(b.client_id);
+    if (!client) {
+      return res.status(400).send('Unknown client.');
+    }
+    // Defense-in-depth: redirect_uri must be one the client registered.
+    if (!Array.isArray(client.redirect_uris) || !client.redirect_uris.includes(b.redirect_uri)) {
+      return res.status(400).send('Invalid redirect_uri.');
+    }
+
+    let session;
+    try {
+      const resp = await axios.post(`${apiUrl}/auth/login`, { email: b.email, password: b.password }, { timeout: 10000 });
+      session = resp.data?.session;
+      var userId = resp.data?.user?.id;
+    } catch (err) {
+      const msg = err.response?.status === 401 ? 'Invalid email or password.' : 'Sign-in failed. Please try again.';
+      return res.status(200).send(renderConsentPage(params, { clientName: client.client_name, error: msg }));
+    }
+
+    if (!session?.access_token) {
+      return res.status(200).send(renderConsentPage(params, { clientName: client.client_name, error: 'Sign-in failed. Please try again.' }));
+    }
+
+    const code = await store.createCode({
+      clientId: b.client_id,
+      codeChallenge: b.code_challenge,
+      redirectUri: b.redirect_uri,
+      scopes: (b.scope || '').split(' ').filter(Boolean),
+      userId,
+    });
+
+    const url = new URL(b.redirect_uri);
+    url.searchParams.set('code', code);
+    if (b.state) url.searchParams.set('state', b.state);
+    return res.redirect(302, url.toString());
+  };
+}
+
+module.exports = { renderConsentPage, makeConsentHandler, esc };

package/src/oauth/provider.js

@@ -0,0 +1,99 @@
+/**
+ * OAuthServerProvider for the hosted MCP authorization server.
+ *
+ * Plugs into the MCP SDK's mcpAuthRouter (discovery metadata, DCR, /authorize,
+ * /token, /revoke, PKCE validation). Persistence is delegated to the backend
+ * via BackendOAuthStore.
+ *
+ * Token model: the OAuth access_token is a short-lived (1h) AgentPlanner JWT
+ * minted from the consenting user (validated statelessly on /mcp). The refresh
+ * token is opaque, revocable, and bound to the client — backed by the backend's
+ * oauth_refresh_tokens table. Revoking it kills the connection within the
+ * access-token TTL. No AP credential is stored at rest.
+ */
+const { renderConsentPage } = require('./consent');
+
+class ApOAuthProvider {
+  constructor({ store }) {
+    this._store = store;
+
+    this.clientsStore = {
+      getClient: (clientId) => this._store.getClient(clientId),
+      registerClient: (client) => this._store.registerClient(client),
+    };
+  }
+
+  // Render the consent/login page. mcpAuthRouter's /authorize handler has
+  // already validated redirect_uri against the registered client.
+  async authorize(client, params, res) {
+    res.status(200).set('Content-Type', 'text/html').send(renderConsentPage({
+      client_id: client.client_id,
+      redirect_uri: params.redirectUri,
+      code_challenge: params.codeChallenge,
+      code_challenge_method: 'S256',
+      state: params.state,
+      scope: (params.scopes || []).join(' '),
+      resource: params.resource ? params.resource.toString() : '',
+    }, { clientName: client.client_name }));
+  }
+
+  async challengeForAuthorizationCode(client, authorizationCode) {
+    const rec = await this._store.getCode(authorizationCode);
+    if (!rec || rec.clientId !== client.client_id) {
+      throw new Error('invalid_grant: unknown authorization code');
+    }
+    return rec.codeChallenge;
+  }
+
+  // Backend consume validates client/redirect/PKCE-bound code, mints + returns
+  // the token set (short-lived access JWT + opaque, revocable refresh token).
+  async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri) {
+    const tokens = await this._store.consumeCode(authorizationCode, {
+      clientId: client.client_id,
+      redirectUri,
+    });
+    if (!tokens || !tokens.access_token) {
+      throw new Error('invalid_grant: authorization code is invalid or expired');
+    }
+    return tokens;
+  }
+
+  // Rotate the opaque refresh token (bound to client_id) for a fresh token set.
+  async exchangeRefreshToken(client, refreshToken, _scopes) {
+    const tokens = await this._store.refresh(refreshToken, client.client_id);
+    if (!tokens || !tokens.access_token) {
+      throw new Error('invalid_grant: refresh token is invalid or expired');
+    }
+    return tokens;
+  }
+
+  // RFC 7009 revocation — revoke the (opaque) refresh token, killing the
+  // connection. Enables /oauth/revoke so connectors can disconnect.
+  async revokeToken(_client, request) {
+    if (request?.token) await this._store.revoke(request.token);
+  }
+
+  // Access tokens are AP JWTs; the MCP doesn't hold JWT_SECRET, so this is a
+  // structural/expiry decode only — the AP API performs real validation when it
+  // receives the JWT. /mcp itself uses the server-http auth middleware, not this.
+  async verifyAccessToken(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) throw new Error('invalid_token');
+    let payload;
+    try {
+      payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    } catch {
+      throw new Error('invalid_token');
+    }
+    if (payload.exp && payload.exp * 1000 < Date.now()) throw new Error('invalid_token: expired');
+    return {
+      token,
+      clientId: payload.client_id || 'agentplanner',
+      scopes: ['agentplanner'],
+      expiresAt: payload.exp,
+      extra: { apToken: token, userId: payload.sub || payload.userId },
+    };
+  }
+}
+
+module.exports = { ApOAuthProvider };

package/src/oauth/store.js

@@ -0,0 +1,111 @@
+/**
+ * OAuth state store — thin HTTP client over the AgentPlanner backend's
+ * secret-guarded /internal/oauth endpoints. The MCP server has no database of
+ * its own; DCR clients and one-time PKCE codes live in the backend's Postgres.
+ *
+ * There is no token storage: the OAuth access_token is the user's AP JWT, so a
+ * restart never drops authenticated connections.
+ */
+const axios = require('axios');
+
+// Map a backend (camelCase) client row → the SDK's OAuthClientInformationFull
+// (snake_case) shape that mcpAuthRouter / the provider expect.
+function toSdkClient(row) {
+  if (!row) return undefined;
+  return {
+    client_id: row.clientId,
+    ...(row.clientSecret ? { client_secret: row.clientSecret, client_secret_expires_at: 0 } : {}),
+    client_name: row.clientName || undefined,
+    redirect_uris: row.redirectUris || [],
+    grant_types: row.grantTypes || [],
+    response_types: row.responseTypes || [],
+    scope: row.scope || undefined,
+    token_endpoint_auth_method: row.tokenEndpointAuthMethod || 'client_secret_basic',
+    client_id_issued_at: row.clientIdIssuedAt ? Math.floor(new Date(row.clientIdIssuedAt).getTime() / 1000) : undefined,
+  };
+}
+
+class BackendOAuthStore {
+  constructor({ apiUrl, internalSecret }) {
+    this.base = `${(apiUrl || 'http://localhost:3000').replace(/\/$/, '')}/internal/oauth`;
+    this.http = axios.create({
+      timeout: 10000,
+      headers: { 'X-Internal-Token': internalSecret || '' },
+    });
+  }
+
+  async getClient(clientId) {
+    try {
+      const { data } = await this.http.get(`${this.base}/clients/${encodeURIComponent(clientId)}`);
+      return toSdkClient(data);
+    } catch (err) {
+      if (err.response?.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  // SDK passes the client minus client_id (snake_case). Backend mints id/secret.
+  async registerClient(client) {
+    const { data } = await this.http.post(`${this.base}/clients`, client);
+    return toSdkClient(data);
+  }
+
+  // Stores the code bound to the authenticated user (no AP credential at rest).
+  async createCode({ clientId, codeChallenge, redirectUri, scopes, userId }) {
+    const { data } = await this.http.post(`${this.base}/codes`, {
+      client_id: clientId,
+      code_challenge: codeChallenge,
+      redirect_uri: redirectUri,
+      scopes: scopes || [],
+      user_id: userId || null,
+    });
+    return data.code;
+  }
+
+  // Peek (no consume) for the PKCE challenge lookup.
+  async getCode(code) {
+    try {
+      const { data } = await this.http.get(`${this.base}/codes/${encodeURIComponent(code)}`);
+      return { clientId: data.client_id, codeChallenge: data.code_challenge, redirectUri: data.redirect_uri };
+    } catch (err) {
+      if (err.response?.status === 404) return null;
+      throw err;
+    }
+  }
+
+  // One-time consume → backend validates client/redirect, mints + returns the
+  // OAuth token set (access JWT + opaque refresh). Null if the code is invalid.
+  async consumeCode(code, { clientId, redirectUri } = {}) {
+    try {
+      const { data } = await this.http.post(`${this.base}/codes/${encodeURIComponent(code)}/consume`, {
+        client_id: clientId,
+        redirect_uri: redirectUri,
+      });
+      return data; // { access_token, token_type, expires_in, refresh_token, scope }
+    } catch (err) {
+      if (err.response?.status === 404 || err.response?.status === 400) return null;
+      throw err;
+    }
+  }
+
+  // Rotate a refresh token → new token set (bound to client_id).
+  async refresh(refreshToken, clientId) {
+    try {
+      const { data } = await this.http.post(`${this.base}/refresh`, {
+        refresh_token: refreshToken,
+        client_id: clientId,
+      });
+      return data;
+    } catch (err) {
+      if (err.response?.status === 400) return null;
+      throw err;
+    }
+  }
+
+  // Revoke a refresh token (RFC 7009) — kills the connection.
+  async revoke(token) {
+    await this.http.post(`${this.base}/revoke`, { token });
+  }
+}
+
+module.exports = { BackendOAuthStore, toSdkClient };

package/src/server-http.js

@@ -17,7 +17,15 @@ const { SessionManager } = require('./session-manager');
 const { setupTools } = require('./tools');
 const { createApiClient } = require('./api-client');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { createOAuthMetadata, mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } = require('@modelcontextprotocol/sdk/server/auth/router.js');
+const { authorizationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/authorize.js');
+const { tokenHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/token.js');
+const { clientRegistrationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/register.js');
+const { revocationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/revoke.js');
 const { version } = require('../package.json');
+const { BackendOAuthStore } = require('./oauth/store');
+const { ApOAuthProvider } = require('./oauth/provider');
+const { makeConsentHandler } = require('./oauth/consent');
 require('dotenv').config();
 
 // MCP Protocol Version
@@ -37,6 +45,15 @@ class MCPHTTPServer {
     // Store for pending SSE streams per session
     this.sseStreams = new Map(); // sessionId -> { res, req }
 
+    // OAuth authorization server (for claude.ai / Claude Design connectors,
+    // which require the MCP OAuth handshake — static ApiKey is rejected there).
+    // The issuer/public origin is where claude.ai reaches the AS endpoints.
+    this.publicBaseUrl = (options.publicBaseUrl || process.env.OAUTH_ISSUER_URL || process.env.PUBLIC_URL || 'https://agentplanner.io').replace(/\/$/, '');
+    this.apiUrl = options.apiUrl || process.env.API_URL || 'http://localhost:3000';
+    this.oauthStore = new BackendOAuthStore({ apiUrl: this.apiUrl, internalSecret: process.env.MCP_INTERNAL_SECRET });
+    this.oauthProvider = new ApOAuthProvider({ store: this.oauthStore, apiUrl: this.apiUrl });
+    this.resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(new URL(`${this.publicBaseUrl}/mcp`));
+
     // Create Express app
     this.app = express();
 
@@ -51,15 +68,70 @@ class MCPHTTPServer {
    * Setup Express middleware
    */
   setupMiddleware() {
-    // Parse JSON bodies
+    // Behind nginx: trust the proxy so express-rate-limit (on the OAuth
+    // endpoints) reads the real client IP from X-Forwarded-For instead of
+    // throwing ERR_ERL_UNEXPECTED_X_FORWARDED_FOR.
+    this.app.set('trust proxy', 1);
+
+    // Parse JSON + urlencoded bodies (OAuth /token uses form encoding; the
+    // consent form posts urlencoded; /register + MCP use JSON).
     this.app.use(express.json());
+    this.app.use(express.urlencoded({ extended: false }));
 
-    // Logging middleware
+    // Logging middleware — log the request and, on finish, the status (+ the
+    // redirect target for 3xx, which is critical for debugging the OAuth flow).
     this.app.use((req, res, next) => {
       console.error(`${req.method} ${req.path} - ${req.get('MCP-Protocol-Version') || 'no version'}`);
+      res.on('finish', () => {
+        const loc = res.getHeader('location');
+        console.error(`  ↳ ${req.method} ${req.path} → ${res.statusCode}${loc ? ` Location=${loc}` : ''}`);
+      });
       next();
     });
 
+    // ── OAuth authorization server ───────────────────────────────────────────
+    // Mounted BEFORE the MCP auth/version/origin middleware so the browser- and
+    // connector-facing OAuth endpoints bypass the MCP-protocol checks. Unmatched
+    // paths (e.g. /mcp) fall through to the middleware below.
+    //
+    // The endpoints live under /oauth/* — NOT the SDK's default root paths —
+    // because /register would otherwise collide with the web UI's signup route.
+    // The SDK's mcpAuthRouter hard-codes root-relative endpoint paths, so we
+    // compose it by hand: serve discovery metadata advertising the /oauth/* URLs,
+    // and mount the handlers under /oauth.
+    const issuerUrl = new URL(this.publicBaseUrl);
+    const oauthBase = `${this.publicBaseUrl}/oauth`;
+    const baseMetadata = createOAuthMetadata({ provider: this.oauthProvider, issuerUrl, scopesSupported: ['agentplanner'] });
+    const oauthMetadata = {
+      ...baseMetadata,
+      authorization_endpoint: `${oauthBase}/authorize`,
+      token_endpoint: `${oauthBase}/token`,
+      registration_endpoint: baseMetadata.registration_endpoint ? `${oauthBase}/register` : undefined,
+      revocation_endpoint: baseMetadata.revocation_endpoint ? `${oauthBase}/revoke` : undefined,
+    };
+
+    // Discovery metadata at the RFC well-known paths (AS metadata at root,
+    // protected-resource at /.well-known/oauth-protected-resource/mcp).
+    this.app.use(mcpAuthMetadataRouter({
+      oauthMetadata,
+      resourceServerUrl: new URL(`${this.publicBaseUrl}/mcp`),
+      scopesSupported: ['agentplanner'],
+      resourceName: 'AgentPlanner',
+    }));
+
+    // AS endpoints under /oauth/* (matches the advertised metadata URLs).
+    const oauthRouter = express.Router();
+    oauthRouter.use('/authorize', authorizationHandler({ provider: this.oauthProvider }));
+    oauthRouter.use('/token', tokenHandler({ provider: this.oauthProvider }));
+    oauthRouter.post('/consent', makeConsentHandler({ store: this.oauthStore, apiUrl: this.apiUrl }));
+    oauthRouter.use('/register', clientRegistrationHandler({ clientsStore: this.oauthProvider.clientsStore }));
+    // Revocation only if the provider supports it. Access tokens are stateless
+    // AP JWTs (no denylist), so we don't — and the metadata omits the endpoint.
+    if (typeof this.oauthProvider.revokeToken === 'function') {
+      oauthRouter.use('/revoke', revocationHandler({ provider: this.oauthProvider }));
+    }
+    this.app.use('/oauth', oauthRouter);
+
     // Protocol version validation
     this.app.use((req, res, next) => {
       // Skip version check for health and discovery endpoints
@@ -79,28 +151,39 @@ class MCPHTTPServer {
       next();
     });
 
-    // Authentication — require Authorization header on /mcp
+    // Authentication — require Authorization header on /mcp.
+    // Three credential types are accepted:
+    //   1. ApiKey <token>      — AP API token (legacy, Desktop/Code/CLI)
+    //   2. Bearer <ap-jwt>     — raw AP JWT (legacy)
+    //   3. Bearer <oauth-tok>  — opaque token issued by our OAuth AS; resolved
+    //                            to the user's AP JWT (claude.ai / Claude Design)
+    // On a missing/invalid token we emit WWW-Authenticate with the protected-
+    // resource metadata URL so OAuth clients can discover the auth server.
     this.app.use((req, res, next) => {
-      if (req.path === '/health' || req.path === '/.well-known/mcp.json') return next();
+      if (req.path === '/health' || req.path.startsWith('/.well-known/')) return next();
+
+      const unauthorized = (message) => {
+        res.set('WWW-Authenticate', `Bearer resource_metadata="${this.resourceMetadataUrl}"`);
+        return res.status(401).json({ jsonrpc: '2.0', error: { code: -32000, message } });
+      };
 
       const authHeader = req.get('Authorization');
       if (!authHeader) {
-        return res.status(401).json({
-          jsonrpc: '2.0',
-          error: { code: -32000, message: 'Authorization header required. Use "Authorization: Bearer <token>" or "Authorization: ApiKey <token>".' }
-        });
+        return unauthorized('Authorization required. Use OAuth (add AgentPlanner as a connector) or "Authorization: ApiKey <token>".');
       }
 
       const parts = authHeader.split(' ');
       if (parts.length !== 2 || !['Bearer', 'ApiKey'].includes(parts[0])) {
-        return res.status(401).json({
-          jsonrpc: '2.0',
-          error: { code: -32000, message: 'Invalid Authorization format. Use "Bearer <token>" or "ApiKey <token>".' }
-        });
+        return unauthorized('Invalid Authorization format. Use "Bearer <token>" or "ApiKey <token>".');
       }
 
-      // Store the raw token for per-session API client creation
-      req.userToken = parts[1];
+      const [, token] = parts;
+
+      // The token is an AP credential: an API key, a raw AP JWT, or an
+      // OAuth-issued access token (which IS an AP JWT — see oauth/provider.js).
+      // All three are passed straight to the per-session API client; the AP API
+      // validates JWTs/keys. No separate OAuth token store to consult.
+      req.userToken = token;
       next();
     });
 

package/src/tools/bdi/intentions.js

@@ -14,6 +14,11 @@
  */
 
 const { asOf, formatResponse, errorResponse, isV1Unavailable } = require('./_shared');
+const { version: PKG_VERSION } = require('../../../package.json');
+
+// Provenance tag stamped onto every plan this server creates, so a plan stays
+// debuggable later even if this MCP build is stale relative to the API.
+const CLIENT_TAG = `agent-planner-mcp@${PKG_VERSION}`;
 
 // ─────────────────────────────────────────────────────────────────────────
 // queue_decision — real decision queue. Replaces add_learning workaround.
@@ -737,10 +742,14 @@ const formIntentionDefinition = {
   name: 'form_intention',
   description:
     "Create a plan that achieves a goal, including an initial phase/task " +
-    "tree, in one call. Defaults to status='active' for human-directed " +
-    "creation; pass status='draft' for autonomous loops so a human can " +
-    "review before promotion. Drafts surface in the dashboard pending " +
-    "queue and auto-promote to active when work begins on any node.",
+    "tree, in one call. Declare execution order inline: give nodes a `ref` and " +
+    "list prerequisite refs/titles in `depends_on` to create 'blocks' edges in " +
+    "the same call — don't ship a bare hierarchy. The response returns a " +
+    "`structure` summary and warns (`created_without_dependencies`) when a " +
+    "multi-task plan has no edges. Defaults to status='active' for " +
+    "human-directed creation; pass status='draft' for autonomous loops so a " +
+    "human can review before promotion. Drafts surface in the dashboard " +
+    "pending queue and auto-promote to active when work begins on any node.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -769,6 +778,12 @@ const formIntentionDefinition = {
             description: { type: 'string' },
             task_mode: { type: 'string', enum: VALID_TASK_MODES, default: 'free' },
             agent_instructions: { type: 'string' },
+            ref: { type: 'string', description: "Optional stable key so other nodes can reference this one in depends_on. Falls back to title if omitted." },
+            depends_on: {
+              type: 'array',
+              items: { type: 'string' },
+              description: "Refs (or titles) of nodes that must complete before this one. Creates a 'blocks' edge from each prerequisite to this node.",
+            },
             children: { type: 'array' },
           },
           required: ['title'],
@@ -779,7 +794,10 @@ const formIntentionDefinition = {
   },
 };
 
-async function createSubtree(apiClient, planId, parentId, children, results) {
+// `ctx` (optional) collects ref/title → id maps and depends_on intents so the
+// caller can wire dependency edges after the whole tree exists. Omitted by
+// callers that don't support inline deps (e.g. extend_intention).
+async function createSubtree(apiClient, planId, parentId, children, results, ctx = null) {
   for (const child of children || []) {
     let createdNode;
     try {
@@ -801,8 +819,18 @@ async function createSubtree(apiClient, planId, parentId, children, results) {
       continue;
     }
 
+    if (ctx && createdNode?.id) {
+      if (child.ref) ctx.refMap.set(String(child.ref), createdNode.id);
+      const list = ctx.titleMap.get(child.title) || [];
+      list.push(createdNode.id);
+      ctx.titleMap.set(child.title, list);
+      if (Array.isArray(child.depends_on) && child.depends_on.length) {
+        ctx.edgeIntents.push({ dependsOn: child.depends_on.map(String), targetId: createdNode.id });
+      }
+    }
+
     if (child.children?.length && createdNode?.id) {
-      await createSubtree(apiClient, planId, createdNode.id, child.children, results);
+      await createSubtree(apiClient, planId, createdNode.id, child.children, results, ctx);
     }
   }
 }
@@ -824,6 +852,7 @@ async function formIntentionHandler(args, apiClient) {
         status,
         visibility,
         tree,
+        client_version: CLIENT_TAG,
       });
       return formatResponse({
         ...result,
@@ -866,6 +895,7 @@ async function formIntentionHandler(args, apiClient) {
       title,
       description: composedDescription,
       status,
+      metadata: { created_by: CLIENT_TAG },
     });
   } catch (err) {
     return errorResponse('create_failed', `Failed to create plan: ${err.response?.data?.error || err.message}`);
@@ -889,9 +919,48 @@ async function formIntentionHandler(args, apiClient) {
 
   // 3. Create tree (top-level children parent to root via omitted parent_id).
   const nodeResults = [];
-  await createSubtree(apiClient, plan.id, null, tree, nodeResults);
+  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
+  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
+
+  // 4. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
+  const resolveRef = (ref) => {
+    if (ctx.refMap.has(ref)) return ctx.refMap.get(ref);
+    const byTitle = ctx.titleMap.get(ref);
+    return byTitle && byTitle.length === 1 ? byTitle[0] : null;
+  };
+  const dependencyWarnings = [];
+  let dependencyEdges = 0;
+  for (const intent of ctx.edgeIntents) {
+    for (const ref of intent.dependsOn) {
+      const sourceId = resolveRef(ref);
+      if (!sourceId || sourceId === intent.targetId) {
+        dependencyWarnings.push(`Unresolved, ambiguous, or self depends_on reference "${ref}"`);
+        continue;
+      }
+      try {
+        await apiClient.axiosInstance.post('/dependencies', {
+          source_node_id: sourceId,
+          target_node_id: intent.targetId,
+          dependency_type: 'blocks',
+        });
+        dependencyEdges += 1;
+      } catch (err) {
+        dependencyWarnings.push(`Edge ${ref}→task rejected: ${err.response?.data?.error || err.message}`);
+      }
+    }
+  }
 
-  return formatResponse({
+  const taskCount = nodeResults.filter((n) => n.id && (n.node_type === 'task' || n.node_type === 'milestone')).length;
+  const createdWithoutDependencies = taskCount >= 2 && dependencyEdges === 0;
+  const structure = {
+    task_count: taskCount,
+    dependency_edges: dependencyEdges,
+    created_without_dependencies: createdWithoutDependencies,
+    created_by: CLIENT_TAG,
+  };
+  if (dependencyWarnings.length) structure.dependency_warnings = dependencyWarnings;
+
+  const response = {
     as_of: asOf(),
     plan_id: plan.id,
     goal_id,
@@ -900,10 +969,18 @@ async function formIntentionHandler(args, apiClient) {
     nodes_created: nodeResults.filter((n) => n.id).length,
     node_failures: nodeResults.filter((n) => n.error),
     nodes: nodeResults,
+    structure,
     next_step: plan.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.",
-  });
+  };
+  if (createdWithoutDependencies) {
+    response.warning =
+      `Plan has ${taskCount} tasks but no dependency edges — execution order is implicit only.`;
+    response.next_required_action =
+      'Call link_intentions to add blocking edges, or confirm the tasks are order-independent.';
+  }
+  return formatResponse(response);
 }
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/tools/bdi/utility.js

@@ -3,6 +3,7 @@
  */
 
 const { asOf, formatResponse } = require('./_shared');
+const { version: MCP_VERSION } = require('../../../package.json');
 
 const getStartedDefinition = {
   name: 'get_started',
@@ -21,17 +22,27 @@ const getStartedDefinition = {
 async function getStartedHandler(args) {
   return formatResponse({
     as_of: asOf(),
+    mcp_version: MCP_VERSION,
     overview:
       "AgentPlanner exposes a BDI-aligned MCP surface. Tools are grouped by " +
       "Beliefs (state queries), Desires (goals), and Intentions (committed actions). " +
       "Each tool answers one whole agentic question and returns an `as_of` timestamp.",
     tools_by_namespace: {
       beliefs: ['briefing', 'list_plans', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
-      desires: ['list_goals', 'update_goal'],
-      intentions: ['claim_next_task', 'update_task', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
+      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal'],
+      intentions: ['form_intention', 'extend_intention', 'link_intentions', 'propose_research_chain', 'claim_next_task', 'update_task', 'update_node', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
       workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint'],
     },
     recommended_workflows: [
+      {
+        name: 'Set up new work a human asked for',
+        steps: [
+          'list_goals / recall_knowledge — check what already exists',
+          'create_goal(...) — create the goal directly (status active). Agents create goals; there is no UI step or approval gate when a human asked.',
+          'form_intention(goal_id, nodes with ref + depends_on) — create the plan + task tree atomically, with execution order declared inline',
+          'Then execute it: claim_next_task → update_task',
+        ],
+      },
       {
         name: 'Mission control loop (Cowork autopilot or scheduled task)',
         steps: [
@@ -60,6 +71,7 @@ async function getStartedHandler(args) {
       },
     ],
     key_principles: [
+      'Agents create goals AND plans, not just execute — when a human asks you to set something up, use create_goal / form_intention directly (no UI round-trip, no approval gate). The UI is for human oversight, not the only way to create work.',
       'Tools are intent-shaped, not CRUD-shaped',
       'Reads are bundled to minimize round trips',
       'Writes are atomic where possible (update_task does status+log+release)',