@ezmodo/mcp-server 0.13.5 → 0.14.1

package/lib/token-store.js

@@ -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

@@ -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

@@ -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.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.13.5",
+  "version": "0.14.1",
   "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

@@ -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"
+  }
+];

package/prompts/index.js

@@ -1,39 +1,72 @@
 /**
- * MCP Prompts
- * Prompt definitions and content for the Zephly MCP server
+ * MCP prompts — the things a USER deliberately invokes (#2634).
+ *
+ * The split that decides what belongs here, now that the server also serves
+ * `instructions` (#2633):
+ *
+ *   instructions = what the agent should ALWAYS do. Injected into system
+ *                  context on every session, so it must be short and it must
+ *                  not need asking for.
+ *   prompts      = actions a person chooses. Clients surface them as slash
+ *                  commands, so they are invoked, not absorbed.
+ *
+ * Serving the always-on discipline in both places would be the same duplicate
+ * that #2594 removed from every repo's CLAUDE.md, so it lives in exactly one.
+ *
+ * WHAT WAS REMOVED HERE, and why it is a fix rather than a loss. This module
+ * used to serve `zephly-usage-guide` and `ai-workflow-automation`. Both were
+ * pre-rebrand in the user-visible prompt NAME, and both instructed agents to
+ * open a session with `list_organizations()` and `list_projects()` — tools that
+ * no longer exist in TOOLS. A prompt that names missing tools is not stale
+ * documentation, it is an instruction to make a call that fails, and the
+ * work-tracking content that replaced it now ships as `instructions`.
  */
 
-// Import prompt content from separate files (to be created)
-import { ZEPHLY_USAGE_GUIDE } from './zephly-usage-guide.js';
-import { AI_WORKFLOW_AUTOMATION } from './ai-workflow-automation.js';
+import { COMMAND_PROMPTS } from './commands.generated.js';
 
 /**
- * List of available prompts
+ * The placeholder a Claude Code command uses for its argument. Kept identical
+ * so one body serves both surfaces without a second copy.
  */
-export const PROMPTS = [
-  {
-    name: 'zephly-usage-guide',
-    description: 'Guidelines for using Zephly MCP tools effectively in project management workflows',
-  },
-  {
-    name: 'ai-workflow-automation',
-    description: 'Guidelines for AI agents to automatically track '
-      + 'their work in Zephly (create epics, tasks, steps, and documentation)',
-  },
-];
+const ARGUMENTS_TOKEN = '$ARGUMENTS';
+
+/** Prompts available on a surface, in the MCP list shape. */
+export function listPrompts(surface = 'local') {
+  return COMMAND_PROMPTS.filter((prompt) => prompt.surfaces.includes(surface)).map(
+    ({ name, description, argumentHint }) => ({
+      name,
+      description,
+      arguments: argumentHint
+        ? [
+          {
+            name: 'arguments',
+            description: argumentHint.replace(/^[[<]|[\]>]$/g, ''),
+            // Never required. `submit` and `untracked` are perfectly usable
+            // with nothing to add, and a required argument would make a
+            // client refuse to run them at all.
+            required: false,
+          },
+        ]
+        : [],
+    })
+  );
+}
 
 /**
- * Get prompt content by name
- * @param {string} name - Prompt name
- * @returns {string|null} - Prompt content or null if not found
+ * The body of one prompt, with the user's argument substituted.
+ *
+ * Returns null for a name this surface does not serve — including one it holds
+ * but does not serve remotely, so `submit` is as absent over the connector as
+ * a name that never existed. Reporting it differently would tell a caller a
+ * prompt is there and then refuse it.
  */
-export function getPromptContent(name) {
-  switch (name) {
-  case 'zephly-usage-guide':
-    return ZEPHLY_USAGE_GUIDE;
-  case 'ai-workflow-automation':
-    return AI_WORKFLOW_AUTOMATION;
-  default:
-    return null;
-  }
+export function getPromptContent(name, args = {}, surface = 'local') {
+  const prompt = COMMAND_PROMPTS.find((candidate) => candidate.name === name);
+  if (!prompt || !prompt.surfaces.includes(surface)) return null;
+
+  const supplied = args?.arguments ?? '';
+  return prompt.body.split(ARGUMENTS_TOKEN).join(supplied);
 }
+
+/** Back-compat for callers that only want the list. */
+export const PROMPTS = listPrompts('local');

package/scripts/build-instructions.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Generate lib/instructions.generated.js from the work-tracking skill.
+ *
+ * WHY GENERATE RATHER THAN WRITE IT TWICE. The MCP `instructions` string and
+ * plugins/ezmodo/skills/work-tracking/SKILL.md say the same thing to different
+ * audiences: the string reaches every MCP client on every session, the skill
+ * reaches Claude Code on demand and in full. Two hand-maintained prose copies
+ * of one contract is precisely the failure that moved these rules out of every
+ * repo's CLAUDE.md and into the plugin in the first place (#2594) — copies
+ * drift, and the drift is invisible until someone follows the stale one.
+ *
+ * WHY GENERATE AT BUILD TIME RATHER THAN READ THE SKILL AT RUNTIME. This
+ * package is published to npm and launched with `npx @ezmodo/mcp-server`. It
+ * ships no plugins/ directory and cannot: the skill lives in the plugin, which
+ * is a different artifact. So the extracted text is committed here, and
+ * __tests__/instructions.test.js re-extracts it whenever the skill IS present
+ * (i.e. in the repo, never in a published install) and fails on any difference.
+ * That test is the drift guard; there is no CI wiring to forget.
+ *
+ * Run: npm run generate:instructions --workspace=@ezmodo/mcp-server
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const SKILL_PATH = join(here, '..', '..', 'plugins', 'ezmodo', 'skills', 'work-tracking', 'SKILL.md');
+const OUTPUT_PATH = join(here, '..', 'lib', 'instructions.generated.js');
+
+/**
+ * Pull the text between a marker pair.
+ *
+ * Throws rather than returning empty on a missing marker: a silently empty
+ * instructions string would ship a server that says nothing, and look fine.
+ */
+export function extract(markdown, marker) {
+  const open = `<!-- mcp:${marker}:start -->`;
+  const close = `<!-- mcp:${marker}:end -->`;
+  const from = markdown.indexOf(open);
+  const to = markdown.indexOf(close);
+  if (from === -1 || to === -1 || to < from) {
+    throw new Error(`Marker mcp:${marker} not found (or inverted) in the skill.`);
+  }
+  return markdown.slice(from + open.length, to).trim();
+}
+
+/** Build the module source from a skill document. */
+export function render(markdown) {
+  const core = extract(markdown, 'core');
+  const local = extract(markdown, 'local');
+
+  return `/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Extracted from plugins/ezmodo/skills/work-tracking/SKILL.md by
+ * scripts/build-instructions.mjs. Edit the SKILL, then run:
+ *
+ *   npm run generate:instructions --workspace=@ezmodo/mcp-server
+ *
+ * __tests__/instructions.test.js fails if this drifts from the skill.
+ */
+
+export const WORK_TRACKING_CORE = ${JSON.stringify(core)};
+
+export const WORK_TRACKING_LOCAL = ${JSON.stringify(local)};
+`;
+}
+
+// Only write when run directly, so the test can import the helpers above.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const skill = readFileSync(SKILL_PATH, 'utf-8');
+  writeFileSync(OUTPUT_PATH, render(skill), 'utf-8');
+  console.log(`Wrote ${OUTPUT_PATH}`);
+}

package/scripts/build-prompts.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Generate prompts/commands.generated.js from the plugin's slash commands.
+ *
+ * WHAT PROMPTS ARE FOR, now that #2633 exists. The two overlap enough to be
+ * worth stating: `instructions` is what the agent should ALWAYS do, injected
+ * into system context on every session. Prompts are things a USER deliberately
+ * invokes. That split is what decides the content — the four plugin commands
+ * (start, resume, submit, untracked) are user-invoked actions, so they belong
+ * here; the always-on discipline does not, and serving it twice would be the
+ * drift problem again.
+ *
+ * Same generate-don't-retype rule as scripts/build-instructions.mjs, for the
+ * same reason: plugins/ is a different artifact and is absent from a published
+ * npx install, so the text is extracted at build time and committed, with
+ * __tests__/prompts.test.js re-extracting whenever the commands ARE present.
+ *
+ * TWO TRANSLATIONS ARE NECESSARY, neither cosmetic. Both are cases where the
+ * command body refers to something only Claude Code has, which an MCP client
+ * would read as an instruction it cannot carry out:
+ *
+ *   1. !`cmd` shell interpolation. The Claude Code CLI runs it before the model
+ *      sees it. MCP has no such preprocessor, so the raw syntax arrives as
+ *      literal text and the model reads a backtick as a command result.
+ *      Rewritten into an explicit instruction to run the command.
+ *   2. "the **EzModo Work Tracking** skill". There are no skills outside Claude
+ *      Code — but the same contract IS served to every client as the MCP
+ *      `instructions` string (#2633), so the reference is repointed there
+ *      rather than deleted. A reference to a sibling skill with no MCP
+ *      equivalent (Link Upkeep) is dropped instead: the step that cites it
+ *      already names the tools it needs, and pointing at something absent is
+ *      worse than not pointing.
+ *
+ * Tests assert that neither form survives into a served prompt.
+ *
+ * Run: npm run generate:prompts --workspace=@ezmodo/mcp-server
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const COMMANDS_DIR = join(here, '..', '..', 'plugins', 'ezmodo', 'commands');
+const OUTPUT_PATH = join(here, '..', 'prompts', 'commands.generated.js');
+
+/**
+ * Which surfaces each command is served on.
+ *
+ * `submit` is local-only: it reads git SHAs and links commits, neither of which
+ * exists on a hosted server. Serving it remotely would hand someone a checklist
+ * whose third step cannot be done.
+ */
+export const COMMANDS = [
+  { file: 'start.md', name: 'start', surfaces: ['local', 'remote'] },
+  { file: 'resume.md', name: 'resume', surfaces: ['local', 'remote'] },
+  { file: 'submit.md', name: 'submit', surfaces: ['local'] },
+  { file: 'untracked.md', name: 'untracked', surfaces: ['local', 'remote'] },
+];
+
+/** Split YAML-ish frontmatter from the body. Only the two keys we use. */
+export function parseCommand(markdown) {
+  const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
+  if (!match) {
+    return { description: '', argumentHint: '', body: markdown.trim() };
+  }
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const at = line.indexOf(':');
+    if (at === -1) continue;
+    meta[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+  }
+  return {
+    description: meta.description || '',
+    argumentHint: meta['argument-hint'] || '',
+    body: markdown.slice(match[0].length).trim(),
+  };
+}
+
+/**
+ * Rewrite Claude Code's !`cmd` shell interpolation into a plain instruction.
+ *
+ * `HEAD: !`git rev-parse HEAD`` becomes
+ * `HEAD: run `git rev-parse HEAD` and use its output`.
+ */
+export function stripShellInterpolation(body) {
+  return body.replace(/!`([^`]+)`/g, (_, command) => `run \`${command}\` and use its output`);
+}
+
+/**
+ * Repoint or remove references to Claude Code skills.
+ *
+ * The patterns allow \s+ between words rather than a literal space: these
+ * bodies are hard-wrapped markdown, so a reference routinely straddles a line
+ * break and a space-literal pattern silently misses exactly those.
+ *
+ * Work Tracking is repointed because its content genuinely reaches every
+ * client, as this server's `instructions`. Anything else is removed with its
+ * sentence, because it does not.
+ */
+export function retargetSkillReferences(body) {
+  return body
+    .replace(
+      /the\s+\*\*EzModo\s+Work\s+Tracking\*\*\s+skill/g,
+      'the work-tracking contract in this server\'s instructions'
+    )
+    .replace(/\s*See\s+the\s+\*\*EzModo\s+[^*]+\*\*\s+skill\./g, '');
+}
+
+export function render(read = (file) => readFileSync(join(COMMANDS_DIR, file), 'utf-8')) {
+  const entries = COMMANDS.map(({ file, name, surfaces }) => {
+    const { description, argumentHint, body } = parseCommand(read(file));
+    if (!description) throw new Error(`${file} has no description in its frontmatter.`);
+    return {
+      name,
+      description,
+      argumentHint,
+      surfaces,
+      body: retargetSkillReferences(stripShellInterpolation(body)),
+    };
+  });
+
+  return `/**
+ * 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 = ${JSON.stringify(entries, null, 2)};
+`;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  if (!existsSync(COMMANDS_DIR)) {
+    throw new Error(`No commands directory at ${COMMANDS_DIR} — run this from the repo.`);
+  }
+  writeFileSync(OUTPUT_PATH, render(), 'utf-8');
+  console.log(`Wrote ${OUTPUT_PATH}`);
+}

package/tools/auth.js

@@ -0,0 +1,34 @@
+/**
+ * Sign-in tools for the LOCAL (stdio) server (#2632).
+ *
+ * Never served remotely: over the connector, Claude performs its own OAuth
+ * before a single tool call is made, so an `authenticate` tool there would be
+ * an inert second sign-in offering to confuse people with. See
+ * lib/remote-tools.js.
+ */
+
+export const AUTH_TOOLS = [
+  {
+    name: 'authenticate',
+    description:
+      'Sign this EzModo MCP server in, or report who it is signed in as. Call ' +
+      'it when a tool reports that no credential is available. `login` ' +
+      'returns a URL to open in a browser — SHOW THAT URL TO THE USER, then ' +
+      'retry the original call once they say they have approved it. Not ' +
+      'needed when EZMODO_API_KEY is set.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['login', 'status', 'sign_out'],
+          description:
+            'login: start browser sign-in and return the URL to open (default). ' +
+            'status: report the current credential without changing anything. ' +
+            'sign_out: forget the stored tokens. Does not affect EZMODO_API_KEY ' +
+            'or the ezmodo CLI login, neither of which this server owns.',
+        },
+      },
+    },
+  },
+];

package/tools/index.js

@@ -40,8 +40,12 @@ import { FACT_TOOLS } from './facts.js';
 import { AGENT_TOOLS } from './agents.js';
 import { RECURRING_TASK_TOOLS } from './recurring-tasks.js';
 import { WORK_TEMPLATE_TOOLS } from './work-templates.js';
+import { AUTH_TOOLS } from './auth.js';
 
 export const TOOLS = [
+  // First in the list on purpose: it is the one tool that works before the
+  // server has a credential, so it should be the one an agent notices.
+  ...AUTH_TOOLS,
   ...ORGANIZATION_TOOLS,
   ...PROJECT_TOOLS,
   ...COMPONENT_TOOLS,