@ezmodo/mcp-server 0.14.1 → 0.14.3

package/README.md

@@ -11,7 +11,7 @@ Point any MCP client at the package. There is nothing to configure:
   "mcpServers": {
     "ezmodo": {
       "command": "npx",
-      "args": ["-y", "@ezmodo/mcp-server"]
+      "args": ["-y", "-p", "@ezmodo/mcp-server", "ezmodo-mcp-server"]
     }
   }
 }
@@ -65,7 +65,7 @@ For CI, containers and anything headless where no browser exists, set
   "mcpServers": {
     "ezmodo": {
       "command": "npx",
-      "args": ["-y", "@ezmodo/mcp-server"],
+      "args": ["-y", "-p", "@ezmodo/mcp-server", "ezmodo-mcp-server"],
       "env": {
         "EZMODO_API_KEY": "ezm_sk_your_key_here"
       }

package/handlers/auth.js

@@ -20,7 +20,7 @@
 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 { describeCliCredential, resetCredentialCache } from '../lib/credentials.js';
 import { getLogger } from '../lib/logger.js';
 
 /**
@@ -73,7 +73,23 @@ async function openBrowser(url) {
   return false;
 }
 
-async function login() {
+/**
+ * Start (or rejoin) a browser sign-in and return the payload that hands its URL
+ * to the agent.
+ *
+ * Exported because it has two callers: the `authenticate` tool, and the
+ * dispatch funnel in lib/create-server.js, which calls it on the FIRST call that
+ * finds no credential (#2654). Before that, the first call only said "call
+ * `authenticate`", and the URL took a second round trip to appear.
+ *
+ * @param {object} [options]
+ * @param {string} [options.reason] Why sign-in is needed, when it was not asked for.
+ */
+export async function startSignIn({ reason } = {}) {
+  return login(reason);
+}
+
+async function login(reason) {
   const log = getLogger();
 
   if (pending) {
@@ -104,7 +120,9 @@ async function login() {
   return {
     ...signInRequired({
       authUrl: flow.authUrl,
-      reason: 'Sign-in started. Waiting for you to approve it in a browser.',
+      reason: reason
+        ? `${reason} Sign-in started — waiting for approval in a browser.`
+        : 'Sign-in started. Waiting for you to approve it in a browser.',
     }),
     browserOpened,
     next_step: browserOpened
@@ -128,6 +146,23 @@ function status() {
     return { authenticated: true, source: 'OAuth', ...identity };
   }
 
+  // Same order as lib/credentials.js resolveCredential(): the CLI's key is
+  // used when there is nothing else, so status must say so (#2655).
+  const cli = describeCliCredential();
+  if (cli) {
+    return {
+      authenticated: true,
+      source: cli.source,
+      keyPrefix: cli.keyPrefix,
+      note: cli.legacy
+        ? 'Calls are using an API key left in the Keychain by the pre-rebrand zephly CLI. ' +
+          'Run `authenticate` to sign in with a browser instead — that takes precedence — ' +
+          'or `ezmodo auth login` to replace the old entry.'
+        : 'Calls are using the API key the ezmodo CLI stored. A browser sign-in via ' +
+          '`authenticate` would take precedence over it.',
+    };
+  }
+
   return signInRequired({ reason: 'This server is not signed in.' });
 }
 

package/index.js

@@ -52,7 +52,7 @@ if (credential) {
   // 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('   Credential: none yet — the first tool call starts a browser sign-in');
   console.error(`   Or set EZMODO_API_KEY. Generate a key at: ${CONFIG.settingsUrl}`);
 }
 console.error('');

package/lib/auth-guidance.js

@@ -54,7 +54,7 @@ const CAVEATS = [
   'A brand-new EzModo account belongs to no organization yet, so tools will ' +
     'return 403 until it does. That is an access problem, not a sign-in ' +
     'problem — signing in again will not change it. The call that hits it ' +
-    'says how to fix it; see `organizationRequired` below.',
+    'returns an `onboardingUrl` to finish setting up a workspace.',
 ];
 
 /**
@@ -70,8 +70,15 @@ export function signInRequired({ authUrl, reason } = {}) {
     reason: reason || 'No EzModo credential is available.',
     ...(authUrl
       ? {
-        action_required: 'Open this URL in a browser, approve the access, then retry the call.',
+        action_required: 'Show this URL to the user. Once they have approved it in the browser, retry the call.',
         authUrl,
+        // The tab can vanish without the user doing anything (#2654): with an
+        // existing EzModo browser session there is no login or consent screen,
+        // so it goes straight to "Signed in". Someone who closes it thinking
+        // nothing happened is usually already signed in.
+        if_unsure: 'If the browser tab closed, or showed "Signed in" without asking anything, ' +
+          'sign-in has probably already completed — retry the call, or run `authenticate` ' +
+          'with action "status" to see which account.',
       }
       : {
         action_required:

package/lib/cli-credential.js

@@ -56,6 +56,12 @@ function fromCredentialsFile() {
  */
 function fromMacKeychain() {
   if (process.platform !== 'darwin') return null;
+  // `zephly-cli` is still read because the CLI still reads it
+  // (LEGACY_SERVICE_NAME in cli/src/lib/auth-store.ts): dropping it here alone
+  // would have the server report "not signed in" to someone `ezmodo auth
+  // status` calls signed in. But it is REPORTED as legacy (#2655) — a
+  // pre-rebrand key silently answering for a new install is how a developer
+  // machine went months without ever exercising the OAuth path customers get.
   for (const service of ['ezmodo-cli', 'zephly-cli']) {
     try {
       const key = execFileSync(
@@ -63,7 +69,7 @@ function fromMacKeychain() {
         ['find-generic-password', '-s', service, '-a', 'api-key', '-w'],
         { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
       ).trim();
-      if (key) return key;
+      if (key) return { key, legacy: service === 'zephly-cli' };
     } catch {
       // Not stored under this name, no `security` binary, denied, or timed
       // out. All of them mean the same thing here: try the next, then stop.
@@ -84,8 +90,16 @@ export function readCliCredential() {
     const fileKey = fromCredentialsFile();
     if (fileKey) return { key: fileKey, source: 'ezmodo CLI credentials file' };
 
-    const keychainKey = fromMacKeychain();
-    if (keychainKey) return { key: keychainKey, source: 'macOS Keychain (ezmodo CLI)' };
+    const keychain = fromMacKeychain();
+    if (keychain) {
+      return keychain.legacy
+        ? {
+          key: keychain.key,
+          source: 'macOS Keychain (legacy zephly-cli entry)',
+          legacy: true,
+        }
+        : { key: keychain.key, source: 'macOS Keychain (ezmodo CLI)' };
+    }
   } catch {
     // Belt and braces. Nothing above should throw, and if something does, a
     // missing fallback must not take down the server.

package/lib/create-server.js

@@ -35,6 +35,8 @@ import {
   signInRequired,
 } from './auth-guidance.js';
 import { getInstructions } from './instructions.js';
+import { getApiKey } from './env.js';
+import { startSignIn as defaultStartSignIn } from '../handlers/auth.js';
 
 /**
  * @param {object} [options]
@@ -81,7 +83,7 @@ function isEmailAlreadyRegistered(error) {
   return error?.code === EMAIL_ALREADY_REGISTERED;
 }
 
-export function createServer({ surface = 'local' } = {}) {
+export function createServer({ surface = 'local', startSignIn = defaultStartSignIn } = {}) {
   const log = getLogger();
 
   // Filtered ONCE here rather than at each call site, so listing and dispatch
@@ -144,11 +146,40 @@ export function createServer({ surface = 'local' } = {}) {
       // 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.
+      //
+      // Two changes from the first version (#2654), both from its first real
+      // run:
+      //
+      // - It STARTS the sign-in, instead of telling the agent to call
+      //   `authenticate`. The URL is what the user needs, and making it take a
+      //   second tool call bought nothing.
+      // - It is NOT flagged isError. Nothing is broken; the user has something
+      //   to do. Clients differ in how they treat an error result — some drop
+      //   its text or report the call as failed — and this text is the one
+      //   thing that must reach the user.
+      //
+      // Except when EZMODO_API_KEY was the credential that got rejected: an
+      // explicit key outranks OAuth, so a browser sign-in could not take
+      // effect, and opening one would send the user on an errand that cannot
+      // work. That case says so, and stays an error.
       if (surface !== 'remote' && isAuthFailure(error)) {
-        return {
-          content: [{ type: 'text', text: JSON.stringify(signInRequired({ reason: errMsg }), null, 2) }],
-          isError: true,
-        };
+        if (getApiKey()) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify(signInRequired({
+              reason: `EZMODO_API_KEY was rejected (${errMsg}). It takes precedence over a browser ` +
+                'sign-in, so fix or unset it — signing in will not help while it is set.',
+            }), null, 2) }],
+            isError: true,
+          };
+        }
+        let payload;
+        try {
+          payload = await startSignIn({ reason: 'Not signed in to EzModo.' });
+        } catch (signInError) {
+          log.warn('Could not start sign-in from the dispatch funnel', { error: signInError.message });
+          payload = signInRequired({ reason: errMsg });
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
       }
       // Answered on EVERY surface, unlike the sign-in prompt above. Sign-in
       // advice is surface-specific because over the connector Claude owns the

package/lib/credentials.js

@@ -100,6 +100,26 @@ export function describeCredentialSync() {
   return null;
 }
 
+/**
+ * The borrowed CLI credential, without the key, for `authenticate status`.
+ *
+ * Status used to look only at EZMODO_API_KEY and its own OAuth tokens, so with
+ * nothing but a CLI key present it said "not signed in" while every call
+ * succeeded as the CLI's user (#2655). A status that disagrees with what calls
+ * actually do is worse than none.
+ *
+ * @returns {{ source: string, legacy?: boolean, keyPrefix: string }|null}
+ */
+export function describeCliCredential() {
+  const fromCli = cliCredential();
+  if (!fromCli) return null;
+  return {
+    source: fromCli.source,
+    ...(fromCli.legacy ? { legacy: true } : {}),
+    keyPrefix: `${fromCli.key.substring(0, 12)}...`,
+  };
+}
+
 /** Test seam: forget the memoized CLI lookup. */
 export function resetCredentialCache() {
   cachedCliCredential = undefined;

package/lib/logger.js

@@ -1,7 +1,13 @@
 /**
  * MCP Server Logger - Structured JSON Lines logging to disk
  *
- * Writes to ~/.zephly/logs/zephly-YYYY-MM-DD.log
+ * Writes to ~/.ezmodo/logs/ezmodo-YYYY-MM-DD.log
+ *
+ * Moved from ~/.zephly/logs/zephly-*.log (#2655), matching the CLI's
+ * currentLogsDir() in cli/src/lib/user-paths.ts. The old directory is NOT
+ * migrated or cleaned: these are diagnostics, safe to delete, and a server that
+ * reaches into a directory it no longer owns to tidy it is a server that can
+ * delete the wrong thing. Nothing is written under the old brand any more.
  * Daily rotation, 7-day auto-cleanup on init
  * Async fire-and-forget writes so logging never blocks tool execution
  */
@@ -11,14 +17,14 @@ import { join } from 'path';
 import { homedir } from 'os';
 
 const RETENTION_DAYS = 7;
-const DATE_PATTERN = /^zephly-(\d{4}-\d{2}-\d{2})\.log$/;
+const DATE_PATTERN = /^ezmodo-(\d{4}-\d{2}-\d{2})\.log$/;
 
 function getDateString() {
   return new Date().toISOString().slice(0, 10);
 }
 
 function getLogFilePath(logsDir) {
-  return join(logsDir, `zephly-${getDateString()}.log`);
+  return join(logsDir, `ezmodo-${getDateString()}.log`);
 }
 
 /**
@@ -31,7 +37,7 @@ export function createLogger(options = {}) {
   const {
     source = 'mcp',
     verbose = false,
-    logsDir = join(homedir(), '.zephly', 'logs'),
+    logsDir = join(homedir(), '.ezmodo', 'logs'),
   } = options;
 
   // Ensure logs directory exists (fire-and-forget)

package/lib/oauth.js

@@ -77,6 +77,13 @@ function decodeJwtPayload(token) {
 // Loopback callback capture
 // ============================================================
 
+/** The loopback page is HTML built from strings, so anything interpolated is escaped. */
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', '\'': '&#39;',
+  })[c]);
+}
+
 const DONE_PAGE = (heading, detail) => `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>EzModo</title>
 <style>
@@ -84,19 +91,22 @@ const DONE_PAGE = (heading, detail) => `<!doctype html>
       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}
+ p{color:#9aa0a6;line-height:1.5;margin:0 0 .75rem}
+ strong{color:#e8eaed;font-weight:600}
 </style></head>
-<body><main><h1>${heading}</h1><p>${detail}</p></main></body></html>`;
+<body><main><h1>${escapeHtml(heading)}</h1>${detail}</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
+ * Resolves with the code, and a `respond` to answer the browser with, 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 }>}
+ * @typedef {{ code: string, respond: (status: number, page: string) => void }} Callback
+ * @returns {Promise<{ redirectUri: string, code: Promise<Callback>, close: () => void }>}
  */
 function startCallbackServer(expectedState) {
   return new Promise((resolveReady, rejectReady) => {
@@ -115,7 +125,7 @@ function startCallbackServer(expectedState) {
 
       const fail = (message) => {
         res.writeHead(400, { 'Content-Type': 'text/html' });
-        res.end(DONE_PAGE('Sign-in failed', message));
+        res.end(DONE_PAGE('Sign-in failed', `<p>${escapeHtml(message)}</p>`));
         if (!finished) {
           finished = true;
           settle.reject(new Error(message));
@@ -144,11 +154,20 @@ function startCallbackServer(expectedState) {
         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.'));
+      // The page is NOT written here. It waits for the token exchange, so it
+      // can say which account was signed in (#2654). With an existing Keycloak
+      // session the browser never shows a login or consent screen — the tab
+      // flashes straight here — and "you are signed in" with no name is how
+      // someone ends up connected as an identity they did not expect.
       if (!finished) {
         finished = true;
-        settle.resolve(received);
+        settle.resolve({ code: received, respond: (status, page) => {
+          res.writeHead(status, { 'Content-Type': 'text/html' });
+          res.end(page);
+        } });
+      } else {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(DONE_PAGE('Already handled', '<p>This sign-in has already completed. You can close this tab.</p>'));
       }
     });
 
@@ -254,17 +273,32 @@ export async function beginLogin() {
   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);
+    const { code: authorizationCode, respond } = await code;
+    let tokens;
+    try {
+      const response = await postToken({
+        grant_type: 'authorization_code',
+        client_id: endpoints.clientId,
+        code: authorizationCode,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+      });
+      tokens = toStoredTokens(response);
+      writeTokens(tokens);
+    } catch (error) {
+      // The browser is still waiting on this response. Leaving it hanging
+      // would look exactly like the silent success this page exists to avoid.
+      respond(400, DONE_PAGE('Sign-in failed',
+        `<p>${escapeHtml(error.message)}</p><p>Return to your editor and try again.</p>`));
+      throw error;
+    }
+
     getLogger().info('OAuth sign-in complete', { email: tokens.email });
+    respond(200, DONE_PAGE('Signed in to EzModo',
+      (tokens.email ? `<p>as <strong>${escapeHtml(tokens.email)}</strong></p>` : '') +
+      '<p>You can close this tab and return to your editor.</p>' +
+      '<p>Not the account you meant? Ask your agent to run <code>authenticate</code> ' +
+      'with <code>sign_out</code>, then sign in again.</p>'));
     return tokens;
   };
 

package/lib/version.js

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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",
   "bin": {
+    "mcp-server": "./index.js",
     "ezmodo-mcp-server": "./index.js",
     "zephly-mcp-server": "./index.js",
     "ezmodo-mcp-server-http": "./http.js"
@@ -49,6 +50,11 @@
     "tools/"
   ],
   "homepage": "https://ezmodo.com/docs/emo/ezmodo/help/cli-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EasyModeOnly/ezmodo-mcp-server.git",
+    "directory": "mcp-server"
+  },
   "bugs": {
     "url": "https://ezmodo.com/support",
     "email": "help@ezmodo.com"

package/tools/auth.js

@@ -11,11 +11,13 @@ 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.',
+      'Sign this EzModo MCP server in, or report who it is signed in as. You ' +
+      'rarely need `login`: any tool called with no credential starts the ' +
+      'browser sign-in itself and returns its `authUrl` — SHOW THAT URL TO THE ' +
+      'USER, then retry the original call once they have approved it. Use ' +
+      '`status` to see which account calls run as (useful when the browser ' +
+      'signed in silently from an existing session), and `sign_out` to switch ' +
+      'accounts. Not needed when EZMODO_API_KEY is set.',
     inputSchema: {
       type: 'object',
       properties: {