npm - @ezmodo/mcp-server - Versions diffs - 0.13.5 → 0.14.0 - Mend

@ezmodo/mcp-server 0.13.5 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/handlers/auth.js +160 -0
package/handlers/index.js +2 -0
package/http.js +6 -1
package/index.js +21 -52
package/lib/auth-guidance.js +67 -0
package/lib/cli-credential.js +3 -12
package/lib/create-server.js +47 -4
package/lib/credentials.js +106 -0
package/lib/git-helpers.js +115 -52
package/lib/http-client.js +19 -6
package/lib/instructions.generated.js +14 -0
package/lib/instructions.js +37 -0
package/lib/oauth-config.js +98 -0
package/lib/oauth.js +353 -0
package/lib/remote-tools.js +6 -0
package/lib/token-store.js +136 -0
package/lib/user-paths.js +41 -0
package/lib/version.js +1 -1
package/package.json +9 -6
package/prompts/commands.generated.js +52 -0
package/prompts/index.js +62 -29
package/scripts/build-instructions.mjs +76 -0
package/scripts/build-prompts.mjs +144 -0
package/tools/auth.js +34 -0
package/tools/index.js +4 -0
package/prompts/ai-workflow-automation.js +0 -96
package/prompts/zephly-usage-guide.js +0 -119

package/lib/oauth.js ADDED Viewed

@@ -0,0 +1,353 @@
+/**
+ * Authorization Code + PKCE sign-in, run by the MCP server for itself (#2631).
+ *
+ * Ported from cli/src/lib/oauth-login.ts, oauth-callback-server.ts and
+ * token-refresh.ts rather than imported from them. This package is published to
+ * npm and launched with `npx @ezmodo/mcp-server`; it must not require the CLI
+ * to be installed. lib/cli-credential.js re-implements the CLI's credential
+ * read for the same reason, and records the same trade-off: when the CLI's
+ * formats move, a copy goes stale and stops working, which is the safe
+ * direction to fail in.
+ *
+ * WHAT IS DIFFERENT FROM THE CLI'S COPY, and why:
+ *
+ *   - An EPHEMERAL loopback port, not the CLI's fixed 19838. The `ezmodo-mcp`
+ *     client registers http://localhost/* and http://127.0.0.1/*, so any port
+ *     matches; a fixed port would collide with a concurrent `ezmodo auth
+ *     login`, which is precisely when someone is likely to be signing in.
+ *   - NOTHING is written to stdout. Over stdio, stdout IS the MCP protocol
+ *     channel — a stray console.log is a protocol violation that corrupts the
+ *     session. The CLI's copy prints progress freely because it owns its
+ *     terminal. Here, diagnostics go to the logger (stderr) and anything the
+ *     user must read is returned to the caller to surface (#2632).
+ *   - Refresh is single-flight. Tool calls run concurrently, so several can
+ *     find the same expired token at once; without this they would each burn a
+ *     refresh token and all but one would fail, because Keycloak rotates it.
+ */
+import { createHash, randomBytes } from 'crypto';
+import { createServer } from 'http';
+import fetch from 'node-fetch';
+import { getKeycloakEndpoints, getScopes } from './oauth-config.js';
+import { clearTokens, isExpired, readTokens, writeTokens } from './token-store.js';
+import { getLogger } from './logger.js';
+/** How long to wait for the user to finish in the browser before giving up. */
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+// ============================================================
+// PKCE primitives (RFC 7636)
+// ============================================================
+function generateState() {
+  return randomBytes(32).toString('hex');
+}
+function generateCodeVerifier() {
+  return randomBytes(32)
+    .toString('base64url')
+    .replace(/[^a-zA-Z0-9\-._~]/g, '')
+    .substring(0, 128);
+}
+function generateCodeChallenge(verifier) {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+/**
+ * Read the `sub`, `email` and `exp` out of a JWT WITHOUT verifying it.
+ *
+ * Safe here, and only here: this token came from a TLS connection to the token
+ * endpoint moments ago, and nothing security-relevant is decided from these
+ * claims — they are stored so a human can be told which account is signed in.
+ * The API verifies the signature on every request, which is where that check
+ * belongs.
+ */
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return {};
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+  } catch {
+    return {};
+  }
+}
+// ============================================================
+// Loopback callback capture
+// ============================================================
+const DONE_PAGE = (heading, detail) => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>EzModo</title>
+<style>
+ body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:#0f1115;color:#e8eaed;
+      display:flex;align-items:center;justify-content:center;height:100vh;margin:0}
+ main{text-align:center;max-width:26rem;padding:2rem}
+ h1{font-size:1.25rem;font-weight:600;margin:0 0 .5rem}
+ p{color:#9aa0a6;line-height:1.5;margin:0}
+</style></head>
+<body><main><h1>${heading}</h1><p>${detail}</p></main></body></html>`;
+/**
+ * Listen on an ephemeral loopback port for the authorization redirect.
+ *
+ * Resolves with the code once one arrives. The redirect URI is returned before
+ * the code is, because the caller needs the port to build the authorize URL —
+ * hence the two-stage shape rather than a single promise.
+ *
+ * @param {string} expectedState
+ * @returns {Promise<{ redirectUri: string, code: Promise<string>, close: () => void }>}
+ */
+function startCallbackServer(expectedState) {
+  return new Promise((resolveReady, rejectReady) => {
+    let settle;
+    const code = new Promise((resolve, reject) => {
+      settle = { resolve, reject };
+    });
+    let finished = false;
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname === '/favicon.ico') {
+        res.writeHead(204).end();
+        return;
+      }
+      const fail = (message) => {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(DONE_PAGE('Sign-in failed', message));
+        if (!finished) {
+          finished = true;
+          settle.reject(new Error(message));
+        }
+      };
+      const error = url.searchParams.get('error');
+      if (error) {
+        // Keycloak reports a refused consent here rather than by not
+        // redirecting, so this is the ordinary "user clicked Cancel" path.
+        const description = url.searchParams.get('error_description') || error;
+        fail(description);
+        return;
+      }
+      const received = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      if (!received) {
+        fail('No authorization code in the callback.');
+        return;
+      }
+      if (state !== expectedState) {
+        // The CSRF check. A mismatch means this redirect was not the one we
+        // started, so the code must not be exchanged.
+        fail('State mismatch — this sign-in did not come from this request.');
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(DONE_PAGE('You are signed in', 'You can close this tab and return to your editor.'));
+      if (!finished) {
+        finished = true;
+        settle.resolve(received);
+      }
+    });
+    server.on('error', (error) => {
+      if (!finished) {
+        finished = true;
+        settle.reject(error);
+      }
+      rejectReady(error);
+    });
+    const timer = setTimeout(() => {
+      if (!finished) {
+        finished = true;
+        settle.reject(new Error('Timed out waiting for the browser sign-in to complete.'));
+      }
+    }, CALLBACK_TIMEOUT_MS);
+    // Do not hold the process open purely to wait for a browser.
+    timer.unref?.();
+    const close = () => {
+      clearTimeout(timer);
+      server.close();
+    };
+    code.then(close, close);
+    // Port 0 = let the OS pick. 127.0.0.1 rather than a wildcard bind: this
+    // socket briefly accepts an authorization code, and it has no business
+    // being reachable from the network.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolveReady({ redirectUri: `http://127.0.0.1:${port}/callback`, code, close });
+    });
+  });
+}
+// ============================================================
+// Token endpoint
+// ============================================================
+async function postToken(body) {
+  const endpoints = getKeycloakEndpoints();
+  const response = await fetch(endpoints.token, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(body).toString(),
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    const error = new Error(`Token request failed (${response.status}): ${text}`);
+    error.status = response.status;
+    throw error;
+  }
+  return JSON.parse(text);
+}
+/** Turn a Keycloak token response into what the store holds. */
+function toStoredTokens(response) {
+  const claims = decodeJwtPayload(response.access_token);
+  return {
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    expiresAt: new Date(Date.now() + (response.expires_in ?? 60) * 1000).toISOString(),
+    userId: claims.sub,
+    email: claims.email || claims.preferred_username,
+    scope: response.scope,
+    issuer: getKeycloakEndpoints().issuer,
+  };
+}
+// ============================================================
+// Sign-in
+// ============================================================
+/**
+ * Build the authorize URL and start listening for its redirect.
+ *
+ * Split from the wait deliberately: the caller needs the URL to hand to the
+ * user (in a tool result, or a browser it opened) BEFORE anyone can complete
+ * the flow. Returning both at once would mean the URL only became available
+ * after it was already too late to show it.
+ *
+ * @returns {Promise<{ authUrl: string, complete: () => Promise<StoredTokens>, cancel: () => void }>}
+ */
+export async function beginLogin() {
+  const endpoints = getKeycloakEndpoints();
+  const state = generateState();
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+  const { redirectUri, code, close } = await startCallbackServer(state);
+  const authUrl = new URL(endpoints.authorization);
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', endpoints.clientId);
+  authUrl.searchParams.set('redirect_uri', redirectUri);
+  authUrl.searchParams.set('scope', getScopes());
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('code_challenge', challenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+  getLogger().debug('OAuth sign-in started', { redirectUri, environment: endpoints.environment });
+  const complete = async () => {
+    const authorizationCode = await code;
+    const response = await postToken({
+      grant_type: 'authorization_code',
+      client_id: endpoints.clientId,
+      code: authorizationCode,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    });
+    const tokens = toStoredTokens(response);
+    writeTokens(tokens);
+    getLogger().info('OAuth sign-in complete', { email: tokens.email });
+    return tokens;
+  };
+  return { authUrl: authUrl.toString(), complete, cancel: close };
+}
+// ============================================================
+// Refresh
+// ============================================================
+/**
+ * In-flight refresh, shared by every caller that arrives while it runs.
+ *
+ * Keycloak ROTATES refresh tokens: the old one dies the moment the new one is
+ * issued. Two concurrent refreshes therefore do not merely waste a round trip,
+ * they race to invalidate each other, and the loser signs the user out. One
+ * promise, awaited by all.
+ */
+let refreshInFlight = null;
+async function refreshTokens(tokens) {
+  const endpoints = getKeycloakEndpoints();
+  try {
+    const response = await postToken({
+      grant_type: 'refresh_token',
+      client_id: endpoints.clientId,
+      refresh_token: tokens.refreshToken,
+    });
+    const refreshed = toStoredTokens(response);
+    // Keycloak may omit a new refresh token; keep the old one when it does,
+    // or the next refresh has nothing to present.
+    if (!refreshed.refreshToken) refreshed.refreshToken = tokens.refreshToken;
+    writeTokens(refreshed);
+    return refreshed;
+  } catch (error) {
+    // 400 from the token endpoint on a refresh means the grant is dead —
+    // expired, revoked, or already rotated. Keeping it would retry forever
+    // against something that can never succeed, so drop it and let the caller
+    // ask for a fresh sign-in.
+    if (error.status === 400) {
+      getLogger().info('Refresh token no longer valid; signing out', { error: error.message });
+      clearTokens();
+      return null;
+    }
+    // Anything else (network, 5xx) is plausibly transient. Leave the stored
+    // tokens alone so a later call can try again.
+    getLogger().warn('Token refresh failed', { error: error.message });
+    return null;
+  }
+}
+/**
+ * A usable access token, refreshing if needed, or null when a sign-in is due.
+ *
+ * Null is the ONLY failure mode: every caller is on the path of a tool call,
+ * and "you need to sign in" is a message the agent can act on, whereas a thrown
+ * error is one it cannot.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function getAccessToken() {
+  const tokens = readTokens();
+  if (!tokens) return null;
+  if (!isExpired(tokens)) return tokens.accessToken;
+  if (!tokens.refreshToken) return null;
+  if (!refreshInFlight) {
+    refreshInFlight = refreshTokens(tokens).finally(() => {
+      refreshInFlight = null;
+    });
+  }
+  const refreshed = await refreshInFlight;
+  return refreshed?.accessToken ?? null;
+}
+/** Who is signed in, for diagnostics. Null when nobody is. */
+export function getSignedInIdentity() {
+  const tokens = readTokens();
+  if (!tokens) return null;
+  return { email: tokens.email, userId: tokens.userId, scope: tokens.scope };
+}
+/** Forget the stored tokens. */
+export function signOut() {
+  return clearTokens();
+}

package/lib/remote-tools.js CHANGED Viewed

@@ -41,6 +41,12 @@
 /** Tools that operate on the local machine and are never served remotely. */
 export const LOCAL_ONLY_TOOLS = Object.freeze([
+  // Not a filesystem tool, but local for the same reason: over the connector
+  // Claude completes its own OAuth before any tool call, so a second sign-in
+  // offered there would be inert and confusing (#2632). It also opens a
+  // browser and binds a loopback port, neither of which means anything in a
+  // container.
+  'authenticate',
   'detect_git_repository',
   'get_current_project_context',
   'initialize_project_context',

package/lib/token-store.js ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ * On-disk store for the OAuth tokens this server obtains for itself (#2631).
+ *
+ * Lives at <config dir>/mcp-oauth.json, beside the CLI's own `credentials`
+ * file. A DISTINCT filename on purpose: the CLI owns `credentials` and
+ * `oauth.json`, and two programs writing one file is how a working login
+ * disappears the next time the other one runs. This server only ever reads the
+ * CLI's files (see lib/cli-credential.js) and only ever writes its own.
+ *
+ * Three properties this module is responsible for:
+ *
+ *   1. It never throws. It sits on the path every tool call takes to resolve a
+ *      credential. A malformed or unreadable file must degrade to "not signed
+ *      in" — which prompts a fresh sign-in and fixes itself — rather than
+ *      taking down the server, which does not.
+ *   2. It writes 0600, and creates the directory 0700. These are bearer
+ *      tokens for the user's whole account; a world-readable file in a shared
+ *      home directory hands the account over.
+ *   3. It writes atomically, via a temp file in the same directory and a
+ *      rename. A torn write here is indistinguishable from corruption, and
+ *      corruption logs a user out.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { configDir } from './user-paths.js';
+import { getLogger } from './logger.js';
+const FILENAME = 'mcp-oauth.json';
+/**
+ * Treat a token as expired this many milliseconds BEFORE it actually expires.
+ *
+ * Without a margin, a token that passes the check can still be rejected by the
+ * time the request lands — clock skew between this machine and Keycloak, plus
+ * the request's own flight time. Thirty seconds costs nothing (the refresh is
+ * one round trip) and removes a class of intermittent 401 that would look like
+ * a server bug rather than a clock.
+ */
+const EXPIRY_MARGIN_MS = 30_000;
+function tokenPath() {
+  return join(configDir(), FILENAME);
+}
+/**
+ * @typedef {object} StoredTokens
+ * @property {string} accessToken
+ * @property {string} [refreshToken]
+ * @property {string} expiresAt   ISO 8601
+ * @property {string} [userId]
+ * @property {string} [email]
+ * @property {string} [scope]
+ * @property {string} [issuer]    Which Keycloak issued these
+ */
+/**
+ * Read the stored tokens, or null if there are none to read.
+ *
+ * @returns {StoredTokens|null}
+ */
+export function readTokens() {
+  const path = tokenPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed.accessToken !== 'string' || !parsed.accessToken.trim()) {
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    // Malformed, truncated, or unreadable. Reporting "not signed in" sends the
+    // user through a sign-in that overwrites it; throwing would strand them.
+    getLogger().warn('Ignoring unreadable OAuth token file', { path, error: error.message });
+    return null;
+  }
+}
+/**
+ * Persist tokens, replacing whatever was there.
+ *
+ * @param {StoredTokens} tokens
+ * @returns {boolean} whether the write landed
+ */
+export function writeTokens(tokens) {
+  const dir = configDir();
+  const path = tokenPath();
+  const temp = `${path}.${process.pid}.tmp`;
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(temp, JSON.stringify(tokens, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    renameSync(temp, path);
+    return true;
+  } catch (error) {
+    getLogger().warn('Could not persist OAuth tokens', { path, error: error.message });
+    try {
+      if (existsSync(temp)) unlinkSync(temp);
+    } catch {
+      // Nothing useful to do about a leftover temp file.
+    }
+    return false;
+  }
+}
+/** Forget the stored tokens. Used by sign-out and by an unrecoverable refresh. */
+export function clearTokens() {
+  const path = tokenPath();
+  try {
+    if (existsSync(path)) unlinkSync(path);
+    return true;
+  } catch (error) {
+    getLogger().warn('Could not clear OAuth tokens', { path, error: error.message });
+    return false;
+  }
+}
+/**
+ * Whether an access token is past use, margin included.
+ *
+ * Missing or unparseable expiry counts as expired: if we cannot tell, the safe
+ * answer is the one that triggers a refresh rather than the one that sends a
+ * possibly-dead token to the API.
+ *
+ * @param {StoredTokens|null} tokens
+ */
+export function isExpired(tokens) {
+  if (!tokens?.expiresAt) return true;
+  const expiry = Date.parse(tokens.expiresAt);
+  if (Number.isNaN(expiry)) return true;
+  return Date.now() >= expiry - EXPIRY_MARGIN_MS;
+}
+/** The path tokens are stored at, for diagnostics and messages. */
+export function getTokenPath() {
+  return tokenPath();
+}

package/lib/user-paths.js ADDED Viewed

@@ -0,0 +1,41 @@
+/**
+ * Where this server keeps per-user state on disk.
+ *
+ * Extracted so the credential reader and the OAuth token store cannot disagree
+ * about where "the ezmodo config directory" is. They had better not: the two
+ * files live side by side, and a writer that picks a different directory from
+ * the reader produces a login that appears to succeed and then is never found
+ * again.
+ *
+ * `.config/ezmodo` is current, `.config/zephly` the pre-rebrand name still
+ * present in older installs. Current always wins; legacy is READ-ONLY. Nothing
+ * here ever writes to the legacy directory — migrating it is the CLI's job
+ * (cli/src/lib/user-paths.ts owns that), and a second migrator racing the first
+ * over the same files is worse than not migrating at all.
+ */
+import { homedir } from 'os';
+import { join } from 'path';
+/**
+ * Every directory to SEARCH, current first.
+ *
+ * @returns {string[]}
+ */
+export function configDirs() {
+  const home = homedir();
+  if (process.platform === 'win32') {
+    const base = process.env.APPDATA || home;
+    return [join(base, 'ezmodo'), join(base, 'zephly')];
+  }
+  return [join(home, '.config', 'ezmodo'), join(home, '.config', 'zephly')];
+}
+/**
+ * The single directory to WRITE to. Always the current name.
+ *
+ * @returns {string}
+ */
+export function configDir() {
+  return configDirs()[0];
+}

package/lib/version.js CHANGED Viewed

@@ -7,4 +7,4 @@
  *
  * Update this when bumping the version in package.json.
  */
-export const MCP_VERSION = '0.13.5';
+export const MCP_VERSION = '0.14.0';

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",
@@ -21,7 +21,9 @@
     "test:watch": "BUILD_ENV=development NODE_OPTIONS=--experimental-vm-modules jest --watch",
     "test:coverage": "BUILD_ENV=development NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test:smoke": "BUILD_ENV=development node test.js",
-    "lint": "eslint . --fix"
+    "lint": "eslint . --fix",
+    "generate:instructions": "node scripts/build-instructions.mjs",
+    "generate:prompts": "node scripts/build-prompts.mjs"
   },
   "keywords": [
     "mcp",
@@ -36,14 +38,15 @@
     "access": "public"
   },
   "files": [
-    "index.js",
-    "http.js",
+    "README.md",
     "config/",
     "handlers/",
+    "http.js",
+    "index.js",
     "lib/",
     "prompts/",
-    "tools/",
-    "README.md"
+    "scripts/",
+    "tools/"
   ],
   "homepage": "https://ezmodo.com/docs/emo/ezmodo/help/cli-mcp",
   "bugs": {

package/prompts/commands.generated.js ADDED Viewed

@@ -0,0 +1,52 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Extracted from plugins/ezmodo/commands/ by scripts/build-prompts.mjs.
+ * Edit the command, then run:
+ *
+ *   npm run generate:prompts --workspace=@ezmodo/mcp-server
+ *
+ * __tests__/prompts.test.js fails if this drifts from the commands.
+ */
+export const COMMAND_PROMPTS = [
+  {
+    "name": "start",
+    "description": "Create an EzModo task for what you are about to build, and start it",
+    "argumentHint": "[what you are about to work on]",
+    "surfaces": [
+      "local",
+      "remote"
+    ],
+    "body": "Start tracked work on: **$ARGUMENTS**\n\nFollow the work-tracking contract in this server's instructions. In short:\n\n1. `get_current_project_context()` — cache the `projectId`, note the components,\n   tags and `terminology`.\n2. `get_context` with a keyword query drawn from the request above. Read what\n   comes back before writing anything: it tells you which files exist, what\n   patterns they follow, and what the change will touch.\n3. `resolve_links` on the paths you expect to change. A component you did not\n   expect means the work is broader than the request sounds.\n4. Create the work:\n   - **Single scope** (a fix, a small feature, a config or docs change) —\n     `manage_task action:\"create\"` with `status:\"in_progress\"`, a description\n     that says why/where/how, steps that name real files, `componentIds` for\n     every component involved, and the right `taskType`.\n   - **Multi scope** (spanning areas, or a large refactor) — `manage_epic\n     action:\"create\"` with its child tasks in the same request, ordered by\n     dependency.\n\nThen report the task number and web URL and begin. Do not edit anything before\nthe task exists — a task created afterwards is a task written from memory.\n\nIf no `.ezmodo/config.json` is found, say so and stop rather than guessing at a\nproject."
+  },
+  {
+    "name": "resume",
+    "description": "Load an EzModo task or epic by number and continue where the last session stopped",
+    "argumentHint": "<task number, epic number, or id>",
+    "surfaces": [
+      "local",
+      "remote"
+    ],
+    "body": "Resume: **$ARGUMENTS**\n\nLoad it **directly** — `get_task` (with `taskNumber` + `projectId`, or `taskId`)\nor `get_epic`. Do not search; a number or id is an exact address, and\n`search_tasks` / `search_epics` are for when you have neither.\n\nYou will need the `projectId` from `get_current_project_context()` to resolve a\ntask number.\n\nThen, before doing anything:\n\n1. Read **every** knowledge item. That is where the previous session put its\n   reasoning — root causes, decisions and what they rejected, blockers.\n2. Look for knowledge tagged `progress-checkpoint` for the latest status.\n3. Note which steps are already complete. Do not redo them.\n\nReport back: what the task is, what has been done, what the last session\nlearned that changes how you would approach the rest, and which step you are\npicking up. Then continue from there, following the work-tracking contract in this server's instructions for the rest.\n\nIf the task is already `in_review` or `completed`, say so and ask before\nreopening it."
+  },
+  {
+    "name": "submit",
+    "description": "Finish the active EzModo task — steps, knowledge, commit links, then in_review",
+    "argumentHint": "[anything to note in the completion summary]",
+    "surfaces": [
+      "local"
+    ],
+    "body": "Close out the active task.\n\nHEAD: run `git rev-parse HEAD` and use its output\nRecent commits: run `git log --oneline -5` and use its output\n\nWork through, in order:\n\n1. **Steps** — `toggleSteps` for everything now done. If work happened that no\n   step covered, `addStep` it first rather than leaving it unrecorded. If a step\n   was deliberately not done, leave it open and say why in the notes.\n2. **Knowledge** — `addKnowledge` for anything the next session would have to\n   rediscover: root causes (`fact`), decisions and what they rejected\n   (`decision`), blockers (`fact`). Specific: file paths, function names, exact\n   error messages.\n3. **Commits** — `link_commit` for every commit not yet linked, using the full\n   40-character SHA above. A short SHA is rejected.\n4. **Link suggestions** — check `list_agent_suggestions action:\"link\"` for this\n   task and clear the queue with `resolve_link_suggestions`. Reject with a real\n   reason; leaving them pending is the only wrong outcome.\n5. **Test cases** — only if `autoGenerateTestCases` is true in the project\n   context. 3-6 cases covering happy path, edges and errors.\n6. **Submit** — `manage_task action:\"update\"` with `status:\"in_review\"` and\n   `completionNotes`.\n\nThe notes are the deliverable. They must say what was done, what was verified\nand how, and — explicitly — anything in scope that was **not** done and why.\nA summary that omits the gap is worse than none, because the reviewer trusts it.\n\nDo **not** call `manage_task action:\"complete\"`. A human completes the task.\n\nAnything to include: $ARGUMENTS"
+  },
+  {
+    "name": "untracked",
+    "description": "Retroactively capture work already in progress that has no EzModo task",
+    "argumentHint": "[what the work was, if the diff does not make it obvious]",
+    "surfaces": [
+      "local",
+      "remote"
+    ],
+    "body": "Capture the current uncommitted work as a task.\n\nCurrent branch: run `git rev-parse --abbrev-ref HEAD` and use its output\nChanged files: run `git status --porcelain` and use its output\n\nUse `report_untracked_work` with:\n\n- `projectId` from `get_current_project_context()`\n- `title` — concise, describing what was actually done\n- `description` — what and **why**. Do not restate the branch or file list; they\n  are appended automatically as evidence.\n- `changedFiles` — the paths above\n- `branch` — as above\n- `componentIds` — resolve the changed paths with `resolve_links` rather than\n  guessing; untracked work often spans more than one area, which is part of why\n  it went untracked\n- `origin`:\n  - `discovered` — found while working on another task (set `discoveredDuringTaskId`)\n  - `scope-creep` — went beyond the active task's scope (set `discoveredDuringTaskId`)\n  - `rework` — redoing prior work\n  - `untracked` — unplanned standalone work (the default)\n\nIf there is an active task in this session, prefer `discovered` or\n`scope-creep` and link it — the discovery chain is the point of the\nclassification.\n\nThe new task comes back `in_progress` and becomes the active one. Track against\nit for the rest of the work.\n\nExtra context from the user, if any: $ARGUMENTS"
+  }
+];