@ezmodo/mcp-server 0.13.5 → 0.14.0

package/handlers/auth.js

@@ -0,0 +1,160 @@
+/**
+ * Sign-in handlers (#2632).
+ *
+ * THE SHAPE THAT MATTERS: `login` returns as soon as it has a URL, and does
+ * NOT wait for the user.
+ *
+ * Blocking until the browser round trip finished would read better in a
+ * transcript — one call, "signed in as you" — but it puts a human's attention
+ * span on the critical path of a tool call. Clients time tool calls out at
+ * wildly different limits, and a client that gives up at thirty seconds would
+ * report a failure for a sign-in that then succeeds in the background, leaving
+ * the agent with a wrong answer and the user with a working login. Returning
+ * immediately is correct under every timeout.
+ *
+ * The flow keeps running after the return: the loopback listener is alive in
+ * this process, and completion writes the tokens itself. So the recovery is
+ * simply for the agent to retry whatever it was doing.
+ */
+
+import { beginLogin, getSignedInIdentity, signOut } from '../lib/oauth.js';
+import { getApiKey } from '../lib/env.js';
+import { signInRequired } from '../lib/auth-guidance.js';
+import { resetCredentialCache } from '../lib/credentials.js';
+import { getLogger } from '../lib/logger.js';
+
+/**
+ * The sign-in currently waiting on a browser, if any.
+ *
+ * Held so a second `login` while one is already open returns the SAME URL
+ * rather than starting a rival flow. Two live flows would mean two loopback
+ * listeners and two states, and whichever URL the user did not click would sit
+ * there until it timed out.
+ */
+let pending = null;
+
+/**
+ * Abandon a sign-in that is still waiting on a browser.
+ *
+ * Real behaviour, not just a test seam: signing out while a browser tab is
+ * still open should not leave a loopback listener alive that would quietly
+ * complete the login the user just cancelled.
+ */
+export function cancelPendingLogin() {
+  if (!pending) return false;
+  pending.cancel();
+  pending = null;
+  return true;
+}
+
+/** Open a URL in the user's browser, best-effort. */
+async function openBrowser(url) {
+  const { execFile } = await import('child_process');
+  const commands =
+    process.platform === 'darwin'
+      ? [['open', [url]]]
+      : process.platform === 'win32'
+        ? [['cmd', ['/c', 'start', '', url]]]
+        : [
+          ['xdg-open', [url]],
+          ['sensible-browser', [url]],
+          ['x-www-browser', [url]],
+        ];
+
+  for (const [command, args] of commands) {
+    const opened = await new Promise((resolve) => {
+      // execFile, not exec: no shell, so a URL cannot be read as shell syntax.
+      execFile(command, args, (error) => resolve(!error));
+    });
+    if (opened) return true;
+  }
+  // Not a failure. The URL in the result is the contract; the browser launch
+  // is a convenience, and it is expected to fail over SSH or in a container.
+  return false;
+}
+
+async function login() {
+  const log = getLogger();
+
+  if (pending) {
+    return {
+      ...signInRequired({ authUrl: pending.authUrl, reason: 'A sign-in is already waiting.' }),
+      browserOpened: pending.browserOpened,
+    };
+  }
+
+  const flow = await beginLogin();
+  const browserOpened = await openBrowser(flow.authUrl);
+
+  pending = { authUrl: flow.authUrl, browserOpened, cancel: flow.cancel };
+  flow
+    .complete()
+    .then((tokens) => {
+      // The credential chain memoizes the CLI lookup; drop it so the fresh
+      // OAuth token is what the next call sees.
+      resetCredentialCache();
+      log.info('Browser sign-in completed', { email: tokens.email });
+    })
+    .catch((error) => log.warn('Browser sign-in did not complete', { error: error.message }))
+    .finally(() => {
+      pending = null;
+    });
+
+
+  return {
+    ...signInRequired({
+      authUrl: flow.authUrl,
+      reason: 'Sign-in started. Waiting for you to approve it in a browser.',
+    }),
+    browserOpened,
+    next_step: browserOpened
+      ? 'A browser should have opened. Once approved, retry the call you were making.'
+      : 'No browser could be opened here — show the URL to the user, then retry the call.',
+  };
+}
+
+function status() {
+  const envKey = getApiKey();
+  if (envKey) {
+    return {
+      authenticated: true,
+      source: 'EZMODO_API_KEY',
+      note: 'An explicit key is set, so it takes precedence over any browser sign-in.',
+    };
+  }
+
+  const identity = getSignedInIdentity();
+  if (identity) {
+    return { authenticated: true, source: 'OAuth', ...identity };
+  }
+
+  return signInRequired({ reason: 'This server is not signed in.' });
+}
+
+/**
+ * @param {{ action?: 'login'|'status'|'sign_out' }} args
+ */
+export async function authenticate(args = {}) {
+  switch (args.action || 'login') {
+  case 'status':
+    return status();
+  case 'sign_out': {
+    // Cancel first: a listener left alive would complete the very sign-in
+    // being abandoned.
+    const cancelled = cancelPendingLogin();
+    signOut();
+    resetCredentialCache();
+    return {
+      signedOut: true,
+      cancelledPendingSignIn: cancelled,
+      note:
+          'Stored OAuth tokens removed. EZMODO_API_KEY and the ezmodo CLI login ' +
+          'are untouched — this server does not own either.',
+    };
+  }
+  case 'login':
+    return login();
+  default:
+    throw new Error(`Unknown action: ${args.action}. Use login, status or sign_out.`);
+  }
+}

package/handlers/index.js

@@ -38,12 +38,14 @@ import * as agentHandlers from './agents.js';
 import * as recurringTaskHandlers from './recurring-tasks.js';
 import * as workTemplateHandlers from './work-templates.js';
 import { manageWorktree, listProjectWorktrees } from '../lib/worktree-tools.js';
+import { authenticate } from './auth.js';
 
 /**
  * Map of tool names to handler functions
  * Used by the MCP server to route tool calls
  */
 export const HANDLERS = {
+  authenticate,
   // Organizations
   get_organization: organizationHandlers.getOrganization,
 

package/http.js

@@ -91,7 +91,12 @@ export function protectedResourceMetadata() {
     authorization_servers: AUTH_SERVER ? [AUTH_SERVER] : [],
     scopes_supported: CONSENT_SCOPES,
     bearer_methods_supported: ['header'],
-    resource_documentation: 'https://ezmodo.com/help/connectors',
+    // The DB-backed help centre, verified to resolve. /help/connectors was
+    // invented for this field and never existed — a dead link shipped inside a
+    // public discovery document, where nobody would notice because nothing in
+    // the handshake reads it.
+    resource_documentation:
+      process.env.MCP_DOCS_URL || 'https://ezmodo.com/docs/emo/ezmodo/help/cli-mcp',
   };
 }
 

package/index.js

@@ -15,8 +15,7 @@ import { CONFIG } from './config/index.js';
 // The tool surface, shared with the HTTP entry point (http.js).
 import { createServer } from './lib/create-server.js';
 import { initLogger, getLogger } from './lib/logger.js';
-import { getApiKey } from './lib/env.js';
-import { readCliCredential } from './lib/cli-credential.js';
+import { describeCredentialSync } from './lib/credentials.js';
 
 // ============================================================
 // Configuration Validation
@@ -26,66 +25,36 @@ import { readCliCredential } from './lib/cli-credential.js';
 initLogger();
 const log = getLogger();
 
-let apiKey = getApiKey();
-let apiKeySource = 'EZMODO_API_KEY';
-
-// Fall back to the credential `ezmodo auth login` already stored (#2611).
+// The credential is REPORTED here, not required here.
 //
-// The environment always wins: an explicit key must beat an implicit one, or
-// overriding it for a single project becomes impossible to reason about. This
-// only runs when there is nothing to override.
+// This used to exit(1) when it found no API key, which was right when a key
+// was the only way in: a server that cannot authenticate can do nothing, so
+// failing loudly beat failing on every tool call. OAuth changes that (#2631) —
+// signing in happens through the browser AFTER startup, so a server with no
+// credential yet is not broken, it is waiting. Exiting would make the one case
+// we now want to support impossible.
 //
-// Assigning to process.env rather than threading the value through is
-// deliberate — lib/http-client.js re-reads getApiKey() on every request, so
-// this is the one place that has to know. It is the same thing the CLI's own
-// startMcpServer does before importing a handler.
-if (!apiKey) {
-  const stored = readCliCredential();
-  if (stored) {
-    process.env.EZMODO_API_KEY = stored.key;
-    apiKey = stored.key;
-    apiKeySource = stored.source;
-  }
-}
-
-if (!apiKey) {
-  log.error('No API key: EZMODO_API_KEY is unset and no ezmodo CLI credential was found', {
-    settingsUrl: CONFIG.settingsUrl,
-  });
-  console.error('ERROR: No ezmodo API key found.');
-  console.error('');
-  console.error('Checked, in order:');
-  console.error('  1. EZMODO_API_KEY (or legacy ZEPHLY_API_KEY) — not set');
-  console.error('  2. the credential stored by `ezmodo auth login` — not found');
-  console.error('');
-  console.error('Fix it either way:');
-  console.error('  • run `ezmodo auth login`, or');
-  console.error('  • set EZMODO_API_KEY in the environment');
-  console.error('');
-  console.error(`Generate a key at: ${CONFIG.settingsUrl}`);
-  console.error('\nOptional environment variables:');
-  console.error('- EZMODO_API_URL (default: production Go API URL)');
-  console.error('- EZMODO_ENVIRONMENT (dev/staging/production)');
-  console.error('\nEnvironment-specific URLs:');
-  console.error('  - dev: https://dev.ezmodo.com/api');
-  console.error('  - staging: https://staging.ezmodo.com/api');
-  console.error('  - production: https://ezmodo.com/api');
-  console.error('  - local: http://localhost:8787/api');
-  process.exit(1);
-}
+// Nothing is resolved asynchronously here either: a stale token would make the
+// server block on Keycloak before it ever spoke MCP. The refresh happens on
+// the first call that needs one.
+const credential = describeCredentialSync();
 
 log.info('MCP server starting', {
   environment: CONFIG.environment,
   apiUrl: CONFIG.apiUrl,
-  apiKeyPrefix: apiKey.substring(0, 12),
-  apiKeySource,
+  credentialSource: credential?.source ?? 'none',
 });
 console.error('🔧 ezmodo MCP Server Configuration:');
 console.error(`   Environment: ${CONFIG.environment} (build-time)`);
 console.error(`   API URL: ${CONFIG.apiUrl}`);
-// Name the source. A server that silently authenticates as whoever the CLI
-// happens to be logged in as, with no way to tell, is worse than one that fails.
-console.error(`   API Key: ${apiKey.substring(0, 12)}... (from ${apiKeySource})`);
+if (credential) {
+  // Name the source. A server that silently authenticates as whoever the CLI
+  // happens to be logged in as, with no way to tell, is worse than one that fails.
+  console.error(`   Credential: ${credential.detail ?? ''} (from ${credential.source})`);
+} else {
+  console.error('   Credential: none yet — sign in with the `authenticate` tool');
+  console.error(`   Or set EZMODO_API_KEY. Generate a key at: ${CONFIG.settingsUrl}`);
+}
 console.error('');
 
 // ============================================================

package/lib/auth-guidance.js

@@ -0,0 +1,67 @@
+/**
+ * What an agent is told when a call cannot be authenticated (#2632).
+ *
+ * The hard problem this solves: a stdio MCP server is started headlessly by an
+ * editor, with no terminal a human is watching. It cannot say "go to this URL".
+ * The server's own clear startup message goes to a stderr log nobody opens —
+ * which is exactly how #2611 produced an opaque CONNECTION_CLOSED instead of
+ * the message that was right there.
+ *
+ * So don't fight it. Use the channel the agent is already reading: the tool
+ * result. The agent shows the URL in chat, the user clicks, the agent retries.
+ * This is the pattern the claude.ai connector already uses, and it is better UX
+ * than an environment variable rather than a workaround for one.
+ *
+ * Everything here is DATA in a tool result, never a thrown transport error: a
+ * result is something the model can read and act on, an exception is not.
+ */
+
+import { CONFIG } from '../config/index.js';
+
+/** Marks the "there is no credential at all" failure, so dispatch can spot it. */
+export const NOT_AUTHENTICATED = 'EZMODO_NOT_AUTHENTICATED';
+
+/**
+ * The two things a user cannot guess, and will otherwise hit as bare failures.
+ *
+ * Stated on every sign-in prompt on purpose. Both are consequences of decisions
+ * made elsewhere, and neither is discoverable from the error the user would
+ * otherwise see.
+ */
+const CAVEATS = [
+  'A browser is required. This connector cannot take a username and password ' +
+    'directly — direct access grants are disabled on it deliberately, because ' +
+    'skipping the browser also skips the consent screen, which is the whole ' +
+    'reason for using OAuth here rather than a pasted key.',
+  'A brand-new EzModo account belongs to no organization yet, so tools will ' +
+    'return 403 until someone adds you to one. That is an access problem, not ' +
+    'a sign-in problem — signing in again will not change it.',
+];
+
+/**
+ * The payload returned when a sign-in is needed.
+ *
+ * @param {object} options
+ * @param {string} [options.authUrl] The URL to open, when a flow has started.
+ * @param {string} [options.reason]  What went wrong, in one line.
+ */
+export function signInRequired({ authUrl, reason } = {}) {
+  return {
+    authenticated: false,
+    reason: reason || 'No EzModo credential is available.',
+    ...(authUrl
+      ? {
+        action_required: 'Open this URL in a browser, approve the access, then retry the call.',
+        authUrl,
+      }
+      : {
+        action_required:
+            'Call the `authenticate` tool to start sign-in. It returns a URL to open.',
+      }),
+    alternatives: [
+      `Set EZMODO_API_KEY in the environment instead — generate a key at ${CONFIG.settingsUrl}. ` +
+        'This is the right path for CI and anything headless.',
+    ],
+    notes: CAVEATS,
+  };
+}

package/lib/cli-credential.js

@@ -23,19 +23,10 @@
 
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
-
-// `.config/ezmodo` is current, `.config/zephly` the pre-rebrand name still
-// present in older installs. Current wins; legacy is a read fallback only.
-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')];
-}
+// Shared with lib/token-store.js so the two cannot disagree about where the
+// ezmodo config directory is — they write files side by side there.
+import { configDirs } from './user-paths.js';
 
 /** The Linux/Windows path: a 0600 JSON file written by `ezmodo auth login`. */
 function fromCredentialsFile() {

package/lib/create-server.js

@@ -22,10 +22,12 @@ import {
 
 import { TOOLS } from '../tools/index.js';
 import { HANDLERS } from '../handlers/index.js';
-import { PROMPTS, getPromptContent } from '../prompts/index.js';
+import { listPrompts, getPromptContent } from '../prompts/index.js';
 import { MCP_VERSION } from './version.js';
 import { getLogger } from './logger.js';
 import { isRemoteSafe } from './remote-tools.js';
+import { NOT_AUTHENTICATED, signInRequired } from './auth-guidance.js';
+import { getInstructions } from './instructions.js';
 
 /**
  * @param {object} [options]
@@ -34,6 +36,23 @@ import { isRemoteSafe } from './remote-tools.js';
  *   'remote' excludes tools that operate on the local filesystem or git — see
  *   lib/remote-tools.js for why that is an allowlist and not a denylist.
  */
+/**
+ * Whether a failure means "nobody is signed in" rather than "the call went
+ * wrong".
+ *
+ * 401 counts as well as the no-credential case: a credential that WAS valid can
+ * stop being so — a revoked API key, or a refresh token whose grant expired
+ * while the editor sat open overnight — and telling the user to sign in is the
+ * right answer to both.
+ *
+ * 403 deliberately does NOT count. That means signed in but not permitted,
+ * most often a new account in no organization yet, and sending someone back
+ * through a sign-in that cannot fix it is worse than saying nothing.
+ */
+function isAuthFailure(error) {
+  return error?.code === NOT_AUTHENTICATED || error?.status === 401;
+}
+
 export function createServer({ surface = 'local' } = {}) {
   const log = getLogger();
 
@@ -46,7 +65,14 @@ export function createServer({ surface = 'local' } = {}) {
 
   const server = new Server(
     { name: 'ezmodo-mcp-server', version: MCP_VERSION },
-    { capabilities: { tools: {}, prompts: {} } }
+    {
+      capabilities: { tools: {}, prompts: {} },
+      // Reaches every client on every session, which is what makes it the one
+      // place the work-tracking discipline can live without a per-editor
+      // plugin (#2633). Varies by surface for the same reason the tool list
+      // does.
+      instructions: getInstructions(surface),
+    }
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -83,6 +109,19 @@ export function createServer({ surface = 'local' } = {}) {
     } catch (error) {
       const errMsg = error.message || String(error);
       log.error('Tool call failed', { tool: name, error: errMsg, durationMs: Date.now() - start });
+
+      // An authentication failure is not an error the model should relay as
+      // one — it is a request for the user to do something. Funnelled HERE, at
+      // the single dispatch point, for the same reason the surface filter is:
+      // every tool goes through it, so none of them can be missed or drift
+      // (#2632). Only on the local surface; over the connector Claude owns the
+      // OAuth and this advice would be wrong.
+      if (surface !== 'remote' && isAuthFailure(error)) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify(signInRequired({ reason: errMsg }), null, 2) }],
+          isError: true,
+        };
+      }
       // Returned as content rather than thrown: a tool that fails is a result
       // the model can read and act on, not a transport error.
       return {
@@ -92,10 +131,14 @@ export function createServer({ surface = 'local' } = {}) {
     }
   });
 
-  server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+  // Filtered by surface exactly as tools are, and for the same reason: `submit`
+  // reads git SHAs and links commits, which a hosted server cannot do.
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: listPrompts(surface),
+  }));
 
   server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    const content = getPromptContent(request.params.name);
+    const content = getPromptContent(request.params.name, request.params.arguments, surface);
     if (!content) {
       throw new Error(`Unknown prompt: ${request.params.name}`);
     }

package/lib/credentials.js

@@ -0,0 +1,106 @@
+/**
+ * The one place that decides which credential a request is made with.
+ *
+ * Four sources, and the ORDER is the contract (#2631):
+ *
+ *   1. The request context. Only ever set by the HTTP transport, where one
+ *      process serves many callers and the credential belongs to the request
+ *      rather than the process (#2599). Over stdio this is always empty.
+ *   2. EZMODO_API_KEY (or legacy ZEPHLY_API_KEY). An EXPLICIT credential must
+ *      beat an implicit one, or overriding the key for a single project becomes
+ *      impossible to reason about — and this is what keeps CI, containers and
+ *      anything headless working exactly as before OAuth existed.
+ *   3. The OAuth token this server obtained for itself, refreshed if stale.
+ *      The zero-configuration path: nothing to paste, nothing in a profile.
+ *   4. The credential `ezmodo auth login` stored. Last because it belongs to
+ *      another program: a server that silently authenticates as whoever the
+ *      CLI happens to be logged in as should do so only when nothing else
+ *      said otherwise.
+ *
+ * 3 above 4 is the deliberate part. Both are implicit, so neither "wins" on
+ * explicitness; what separates them is that the OAuth token is THIS server's
+ * own, obtained by a person who was shown a consent screen naming this
+ * connector, while the CLI's key is a credential borrowed from a different
+ * tool. Prefer the one whose grant the user actually saw.
+ */
+
+import { getApiKey } from './env.js';
+import { getRequestContext, resolveApiKey } from './request-context.js';
+import { getAccessToken, getSignedInIdentity } from './oauth.js';
+import { readCliCredential } from './cli-credential.js';
+
+/**
+ * The CLI credential, looked up at most once.
+ *
+ * Memoized because reading it is not free: on macOS it shells out to
+ * `security` to read the login Keychain, and doing that on every API call
+ * would put a subprocess spawn — and a possible ACL prompt — on the hot path.
+ * `undefined` means "not looked up yet"; `null` means "looked up, nothing
+ * there".
+ */
+let cachedCliCredential;
+
+function cliCredential() {
+  if (cachedCliCredential === undefined) {
+    cachedCliCredential = readCliCredential() ?? null;
+  }
+  return cachedCliCredential;
+}
+
+/**
+ * Resolve the credential for the call in flight.
+ *
+ * Returns null rather than throwing when there is nothing to use. Every caller
+ * is on the path of a tool call, and "sign in first" is something an agent can
+ * act on; an exception is not.
+ *
+ * @returns {Promise<{ token: string, source: string }|null>}
+ */
+export async function resolveCredential() {
+  // Steps 1 and 2 together. Deliberately NOT re-implemented here:
+  // resolveApiKey() already means "request context, else environment", and a
+  // second copy of that precedence is how the two drift apart.
+  const explicit = resolveApiKey();
+  if (explicit) {
+    const fromRequest = Boolean(getRequestContext()?.apiKey);
+    return { token: explicit, source: fromRequest ? 'request' : 'EZMODO_API_KEY' };
+  }
+
+  const fromOAuth = await getAccessToken();
+  if (fromOAuth) {
+    const identity = getSignedInIdentity();
+    return { token: fromOAuth, source: identity?.email ? `OAuth (${identity.email})` : 'OAuth' };
+  }
+
+  const fromCli = cliCredential();
+  if (fromCli) return { token: fromCli.key, source: fromCli.source };
+
+  return null;
+}
+
+/**
+ * What the startup banner reports, without triggering a network refresh.
+ *
+ * Startup must not block on Keycloak: an expired token at boot would make the
+ * server hang before it ever spoke MCP, and the refresh happens on the first
+ * call anyway.
+ *
+ * @returns {{ source: string, detail?: string }|null}
+ */
+export function describeCredentialSync() {
+  const fromEnv = getApiKey();
+  if (fromEnv) return { source: 'EZMODO_API_KEY', detail: `${fromEnv.substring(0, 12)}...` };
+
+  const identity = getSignedInIdentity();
+  if (identity) return { source: 'OAuth', detail: identity.email };
+
+  const fromCli = cliCredential();
+  if (fromCli) return { source: fromCli.source, detail: `${fromCli.key.substring(0, 12)}...` };
+
+  return null;
+}
+
+/** Test seam: forget the memoized CLI lookup. */
+export function resetCredentialCache() {
+  cachedCliCredential = undefined;
+}