@ezmodo/mcp-server 0.13.5 → 0.14.0

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,

package/prompts/ai-workflow-automation.js

@@ -1,96 +0,0 @@
-/**
- * AI Workflow Automation Prompt
- * Guidelines for AI agents to automatically track their work in Zephly
- */
-
-export const AI_WORKFLOW_AUTOMATION = `# AI Workflow Automation Guide
-
-## Overview
-
-When you (as an AI agent) are implementing features or working on
-complex tasks, **automatically track your work in Zephly in real-time**.
-Don't wait for users to ask you to update documentation or check off tasks.
-
-## When to Use Workflow Automation
-
-- User asks you to implement a feature (not just explain or plan)
-- Task involves multiple implementation steps (>3 steps)
-- Work needs team visibility or historical tracking
-
-## Session Setup
-
-First, discover the user's context:
-
-\`\`\`javascript
-// 1. Get organization
-const orgs = await list_organizations();
-const orgId = orgs.organizations[0].id;
-
-// 2. Get projects
-const projects = await list_projects({ organizationId: orgId });
-const projectId = projects.projects[0].id;
-\`\`\`
-
-## Workflow Steps
-
-1. **Create or Select Project** - Use existing project or create new one with \`create_project\`
-2. **Create Epic** (optional) - Use \`create_epic\` to group related tasks under a milestone
-3. **Break Down Tasks** - Create 3-7 tasks with \`create_task\`, each with implementation steps
-4. **Track Progress** - Update steps with \`update_task\` (toggle, add, modify) as you work
-5. **Update Status** - Move tasks through workflow: backlog → todo → in_progress → in_review → completed
-6. **Document** - Use \`create_document\` to create setup guides, API docs, or troubleshooting guides
-7. **Complete** - Use \`complete_task\` when done, update epic status if applicable
-
-## Example Workflow
-
-\`\`\`javascript
-// 1. Get context
-const orgs = await list_organizations();
-const orgId = orgs.organizations[0].id;
-const projects = await list_projects({ organizationId: orgId });
-const projectId = projects.projects[0].id;
-
-// 2. Create epic (milestone)
-const epic = await create_epic({
-  projectId,
-  title: "User Authentication System",
-  description: "Complete auth implementation with OAuth2"
-});
-
-// 3. Create tasks with steps
-await create_task({
-  projectId,
-  epicId: epic.id,
-  title: "Implement OAuth2 backend",
-  description: "Set up OAuth2 authentication flow",
-  steps: ["Set up OAuth2 config", "JWT generation", "Validation middleware", "Tests"],
-  assigneeType: "ai",
-  assigneeId: "claude",
-  assigneeName: "Claude"
-});
-
-// 4. Track progress as you work
-await update_task({ taskId: "task1", status: "in_progress" });
-await update_task({ taskId: "task1", toggleStep: { stepId: "step_0", completed: true } });
-
-// 5. Document what you built
-await create_document({
-  projectId,
-  title: "Authentication Setup Guide",
-  content: "# How to configure OAuth2...",
-  type: "setup"
-});
-
-// 6. Complete task
-await complete_task({ taskId: "task1", completionNotes: "OAuth2 implementation complete" });
-
-// 7. Update epic when all tasks done
-await update_epic({ epicId: epic.id, status: "completed" });
-\`\`\`
-
-## Benefits
-
-- Real-time visibility for users (no "black box" AI work)
-- Historical record of decisions and implementation details
-- Documentation created alongside code
-- The only PM tool where AI agents manage their own project tracking`;

package/prompts/zephly-usage-guide.js

@@ -1,119 +0,0 @@
-/**
- * Zephly Usage Guide Prompt
- * Guidelines for using Zephly MCP tools effectively
- */
-
-export const ZEPHLY_USAGE_GUIDE = `# Zephly MCP Integration Guide
-
-You have access to Zephly's intelligent project management tools.
-Zephly uses a **project-first** model where projects are the primary
-work containers.
-
-## Session Start - Discover Context
-
-At the start of each session, discover the user's context:
-
-\`\`\`
-1. list_organizations()                              # Get user's workspaces (usually one)
-2. list_projects({ organizationId })                 # Get projects
-\`\`\`
-
-This gives you the organizationId and projects needed for all other operations.
-
-## Project-First Hierarchy
-
-\`\`\`
-Organization
-  └── Projects (primary work containers)
-        └── Epics (milestones within projects)
-              └── Tasks (individual work items)
-  └── Goals (strategic alignment, links to epics)
-\`\`\`
-
-**Key points:**
-- Tasks belong to **projects** (projectId is required)
-- Epics are project-scoped milestones
-- Goals provide strategic alignment and can link to epics
-
-## When to Use Zephly Tools
-
-**Proactively use these tools when:**
-- User mentions tasks, projects, epics, sprints, or team coordination
-- User asks about project status, health, or blockers
-- User needs help prioritizing work or deciding what to work on next
-- User is planning team assignments or workload distribution
-- User is breaking down features into tasks
-- User asks about timelines or estimates
-- User mentions dependencies, blockers, or handoffs
-
-## Core Tools
-
-### Discovery
-- \`list_organizations\` - List all workspaces
-- \`list_projects\` - List projects for an organization
-- \`search_projects\` - Search/filter projects
-
-### Project Management
-- \`create_project\` - Create new project
-- \`get_project_context\` - Get project details with progress
-
-### Task Operations
-- \`create_task\` - Create task in a project (requires projectId)
-- \`update_task\` - Update task properties and steps
-- \`complete_task\` - Mark task completed
-- \`search_tasks\` - Semantic search or filter tasks
-- \`get_task\` - Get task by ID or number
-
-### Epic Management
-- \`create_epic\` - Create epic in project
-- \`update_epic\` - Update epic
-- \`list_epics\` - List epics for project
-- \`get_epic\` - Get epic details
-
-### Goal Management
-- \`create_goal\` - Create strategic goal
-- \`update_goal\` - Update goal
-- \`list_goals\` - List goals for organization
-- \`link_epic_to_goal\` - Link epic to goal for alignment
-
-### AI Intelligence
-- \`get_project_insights\` - Project health analysis
-- \`suggest_next_actions\` - Task recommendations
-- \`analyze_dependency_graph\` - Critical path analysis
-- \`estimate_task_duration\` - AI time estimates
-
-### Team Coordination
-- \`analyze_team_capacity\` - Resource allocation
-- \`suggest_task_assignments\` - Smart task matching
-- \`bulk_task_operations\` - Batch operations
-- \`identify_handoff_needs\` - Detect blocked tasks
-- \`pull_ai_task_from_queue\` - AI agent task queue
-
-## Example Workflow
-
-\`\`\`javascript
-// 1. Discover context
-const orgs = await list_organizations();
-const orgId = orgs.organizations[0].id;
-
-const projects = await list_projects({ organizationId: orgId });
-const projectId = projects.projects[0].id;
-
-// 2. Create a task
-await create_task({
-  projectId,
-  title: 'Implement user authentication',
-  description: 'Add login/logout functionality',
-  priority: 'high'
-});
-
-// 3. Search existing tasks
-await search_tasks({ projectId, status: 'in_progress' });
-\`\`\`
-
-## Best Practices
-
-1. **Discover context first** - Call list_organizations + list_projects at session start
-2. **Project-first** - Always have a projectId before creating tasks
-3. **Check health proactively** - Use get_project_insights to identify issues
-4. **Track AI work** - Create tasks for significant work you're doing`;