@ezmodo/mcp-server 0.14.0 → 0.14.2

package/README.md

@@ -2,73 +2,114 @@
 
 Model Context Protocol (MCP) server for ezmodo - AI-first project management.
 
-## Installation
+## Install
 
-### Global Installation (Recommended)
+Point any MCP client at the package. There is nothing to configure:
 
-```bash
-npm install -g @ezmodo/mcp-server
+```json
+{
+  "mcpServers": {
+    "ezmodo": {
+      "command": "npx",
+      "args": ["-y", "-p", "@ezmodo/mcp-server", "ezmodo-mcp-server"]
+    }
+  }
+}
 ```
 
-### Local Installation
+The first tool call returns a sign-in URL. Open it, approve the access, and
+retry — the server holds the token from then on and refreshes it itself. No API
+key, no environment variable, no CLI.
 
-For local development, use the ezmodo CLI (recommended):
-
-```bash
-# Install CLI
-curl -fsSL https://ezmodo.com/cli/install/scripts/latest/install.sh | sh
+That block is the same for Claude Desktop, Cursor, Windsurf, Zed, Codex and
+anything else that speaks stdio MCP; only the file it goes in differs.
 
-# Authenticate
-ezmodo auth login
+**Claude Code users should install the plugin instead**, which bundles this
+server along with the work-tracking skills, slash commands and hooks:
 
-# Configure MCP
-ezmodo mcp install
 ```
+/plugin marketplace add EasyModeOnly/ezmodo-plugins
+/plugin install ezmodo@ezmodo
+```
+
+### Signing in
 
-## Prerequisites
+Sign-in happens through the `authenticate` tool rather than at startup, because
+a server launched by an editor has no terminal to prompt in:
 
-1. **ezmodo Account**: Sign up at [ezmodo.com](https://ezmodo.com)
-2. **API Key**: Generate an API key in your ezmodo account settings
+| Action | What it does |
+| --- | --- |
+| `authenticate` | Starts browser sign-in and returns the URL to open |
+| `authenticate action:"status"` | Reports which credential is in use |
+| `authenticate action:"sign_out"` | Forgets the stored tokens |
 
-### Generating an API Key
+It returns the URL immediately rather than blocking until you finish in the
+browser, so it cannot trip a client's tool-call timeout. Approve, then retry
+whatever you were doing.
 
-1. Log in to [ezmodo.com](https://ezmodo.com)
-2. Navigate to **Settings** → **API Keys**
-3. Click **Generate New API Key**
-4. Copy your API key
-5. Store it securely - you won't be able to see it again!
+Tokens are stored at `~/.config/ezmodo/mcp-oauth.json` (`%APPDATA%\ezmodo\` on
+Windows), mode `0600`.
 
-## Configuration
+The sign-in asks for `ezmodo:read` and `ezmodo:write`. It deliberately does not
+ask for `ezmodo:delete`: consent is accept-or-decline over the whole set, and
+"permanently delete your projects" should not be a condition of installing an
+MCP server. Set `EZMODO_OAUTH_SCOPES` if you want a different set.
 
-### For Claude Desktop
+## Using an API key instead
 
-Add to your `claude_desktop_config.json`:
+For CI, containers and anything headless where no browser exists, set
+`EZMODO_API_KEY` and skip sign-in entirely:
 
 ```json
 {
   "mcpServers": {
     "ezmodo": {
-      "command": "ezmodo-mcp-server",
+      "command": "npx",
+      "args": ["-y", "-p", "@ezmodo/mcp-server", "ezmodo-mcp-server"],
       "env": {
-        "EZMODO_API_KEY": "your_api_key_here",
-        "EZMODO_API_URL": "https://ezmodo.com/api"
+        "EZMODO_API_KEY": "ezm_sk_your_key_here"
       }
     }
   }
 }
 ```
 
-**Configuration Options:**
+Generate one at **Settings → API Keys** on [ezmodo.com](https://ezmodo.com).
+Keys start with `ezm_sk_` and are shown once. Pre-rename `zeph_sk_` keys remain
+valid indefinitely.
+
+### Which credential wins
+
+Resolved per call, in this order:
+
+1. `EZMODO_API_KEY` (or legacy `ZEPHLY_API_KEY`) — an explicit credential beats
+   an implicit one, which is what keeps CI predictable.
+2. The OAuth token this server obtained for itself.
+3. The credential `ezmodo auth login` stored, if you happen to have the CLI.
+
+`authenticate action:"status"` reports which of these is actually in use.
+
+### Other environment variables
+
+- `EZMODO_API_URL` (optional): custom API URL. Defaults to production
+  (`https://ezmodo.com/api`).
+- `EZMODO_OAUTH_SCOPES` (optional): space-separated scopes to request at
+  sign-in.
+
+## What the server provides besides tools
 
-- `EZMODO_API_KEY` (required): Your ezmodo API key. Legacy `ZEPHLY_API_KEY` is still read as a fallback during the rebrand transition.
-- `EZMODO_API_URL` (optional): Custom API URL. Defaults to production (`https://ezmodo.com/api`).
+**Instructions.** The initialize result carries the work-tracking contract —
+create the task before you edit, tick steps off, capture knowledge, link the
+commit, finish at `in_review`. Most clients inject it into system context, so
+the discipline travels with the tools rather than needing a per-editor plugin.
 
-### For Local Development
+**Prompts.** `start`, `resume`, `submit` and `untracked`, which clients surface
+as slash commands. `submit` is local-only, since it reads git SHAs.
 
-If running from source:
+## Running from source
 
 ```bash
-export EZMODO_API_KEY="your_api_key_here"
+export EZMODO_API_KEY="ezm_sk_your_key_here"
 export EZMODO_API_URL="http://localhost:8787/api"  # Local Go API
 npm run dev
 ```
@@ -248,21 +289,50 @@ When working with the MCP tools:
 
 ## Troubleshooting
 
-### "Missing Authorization header"
-- Ensure `EZMODO_API_KEY` is set in your configuration
+### "Not authenticated with EzModo"
+Nobody has signed in and no `EZMODO_API_KEY` is set. Call `authenticate`, open
+the URL it returns, then retry. Tool calls return this as guidance rather than a
+bare error, so the agent can act on it.
+
+### A 403 after signing in successfully
+Signing in worked; the account just does not belong to any EzModo organization
+yet, so there is nothing for tools to return. Signing in again will not change
+it — no credential substitutes for belonging to a workspace.
+
+Tool calls answer this one themselves: the result carries an `onboardingUrl`,
+and opening it lets you create a personal workspace, create a team, or ask to
+join an organization your verified email already matches. If you expected to be
+a member of one already, you are probably signed in as a different identity than
+you think — check which email that page shows, and ask an administrator to
+invite that exact address.
+
+### "This email address already belongs to a different EzModo account"
+Sign-in worked, but no account could be created for the identity you signed in
+with, because that address is already registered under a different one — most
+often a password account and a Google/Microsoft/GitHub/Apple sign-in for the
+same person. Creating a workspace will not help; the same collision happens
+there. Sign in the way you originally did, or contact support to have the two
+linked.
+
+### Sign-in never completes
+The flow needs a browser — this client cannot take a username and password
+directly, because skipping the browser would skip the consent screen. If no
+browser can open (over SSH, or in a container), the URL is still in the tool
+result; open it anywhere and approve. Or set `EZMODO_API_KEY` instead, which is
+the right answer for a headless machine.
 
 ### "Invalid or revoked API key"
-- Regenerate your API key in ezmodo settings
-- Ensure the key hasn't expired or been revoked
+Regenerate the key in ezmodo settings. Check it has not been revoked, and that
+it has not passed an expiry date if you set one.
 
 ### "Failed to connect to API"
 - Check your `EZMODO_API_URL` configuration
 - Verify your internet connection
 
-### Claude Desktop doesn't see the server
-- Restart Claude Desktop after updating config
+### The client doesn't see the server
+- Restart it after updating config — MCP servers are read at startup
 - Check the config file path is correct
-- Verify JSON syntax in `claude_desktop_config.json`
+- Verify the JSON syntax
 
 ## Development
 

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

@@ -21,6 +21,24 @@ 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 API's code for "signed in, but in no organization" (#2639).
+ *
+ * Must match middleware.CodeNoOrganization in
+ * api/internal/api/middleware/oidc_mcp_auth.go. A code rather than a message
+ * match, because the message is prose someone will improve.
+ */
+export const NO_ORGANIZATION = 'NO_ORGANIZATION';
+
+/**
+ * The API's code for "this email already belongs to another identity" (#2652).
+ *
+ * Must match middleware.CodeEmailAlreadyRegistered. Kept separate from
+ * NO_ORGANIZATION because the answers point opposite ways: that one sends you
+ * to onboarding, and onboarding is exactly where this one fails again.
+ */
+export const EMAIL_ALREADY_REGISTERED = 'EMAIL_ALREADY_REGISTERED';
+
 /**
  * The two things a user cannot guess, and will otherwise hit as bare failures.
  *
@@ -34,8 +52,9 @@ const CAVEATS = [
     '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.',
+    '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 ' +
+    'returns an `onboardingUrl` to finish setting up a workspace.',
 ];
 
 /**
@@ -51,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:
@@ -65,3 +91,92 @@ export function signInRequired({ authUrl, reason } = {}) {
     notes: CAVEATS,
   };
 }
+
+/**
+ * The payload returned when the caller is signed in but belongs to no
+ * organization (#2639).
+ *
+ * Why this is a separate answer from `signInRequired`, and not a widening of
+ * it: sign-in already worked. Sending this person back through a browser flow
+ * produces the identical token and the identical failure, which is precisely
+ * why #2632 kept 403 out of that funnel. What they need is the OTHER half of
+ * onboarding — a workspace — and EzModo already has a surface for it.
+ *
+ * SO THIS DOES NOT INVENT A MECHANISM. The web app routes a signed-in user
+ * with no organizations to /onboarding, which offers a personal workspace, a
+ * new team, or /join — workspace discovery, which lists organizations matching
+ * a verified email domain and joins none of them without a click. Matching an
+ * organization here instead would be a second, quieter copy of that consent
+ * decision, and the quiet copy is the one that gets it wrong.
+ *
+ * Returned on BOTH surfaces, unlike the sign-in prompt. Over the connector
+ * Claude owns the OAuth, so sign-in advice from here would be wrong — but the
+ * missing workspace is ours either way, and a claude.ai user hits it exactly
+ * as a local one does.
+ *
+ * @param {object} options
+ * @param {string} [options.reason] What the API said, in one line.
+ */
+export function organizationRequired({ reason } = {}) {
+  return {
+    authenticated: true,
+    organization: null,
+    reason:
+      reason ||
+      'This account is signed in but does not belong to any EzModo organization.',
+    action_required:
+      'Open the URL below and finish setting up a workspace, then retry the call. ' +
+      'You can create a personal workspace, create a team, or ask to join an ' +
+      'organization your verified email already matches.',
+    onboardingUrl: `${CONFIG.webUrl}/onboarding`,
+    notes: [
+      'Sign-in itself succeeded. Signing in again will not change this, and ' +
+        'no credential — OAuth token or API key — can substitute for belonging ' +
+        'to an organization.',
+      'If you expected to already be a member of one, you are probably signed ' +
+        `in as a different identity than you think. Check which email ${CONFIG.webUrl}/onboarding ` +
+        'shows, and ask an administrator to invite that exact address.',
+    ],
+  };
+}
+
+/**
+ * The payload returned when sign-in succeeded but no account could be created
+ * for it, because the email already belongs to a different EzModo identity
+ * (#2652).
+ *
+ * The reason this is not folded into `organizationRequired`: both used to look
+ * identical from outside — a signed-in caller getting nothing back — and the
+ * fix for one is a dead end for the other. Creating a workspace runs the same
+ * insert against the same unique index and fails the same way. Telling someone
+ * to go do that is worse than telling them nothing, because they will believe
+ * it and try.
+ *
+ * There is deliberately no self-service action here. Merging two identities
+ * onto one account is exactly the operation that must not be automated from an
+ * unauthenticated-by-the-other-party direction, so the honest answer is the
+ * original sign-in method, or a human.
+ *
+ * @param {object} options
+ * @param {string} [options.reason] What the API said, in one line.
+ */
+export function emailAlreadyRegistered({ reason } = {}) {
+  return {
+    authenticated: true,
+    accountProvisioned: false,
+    reason:
+      reason ||
+      'This email address already belongs to a different EzModo account, so no ' +
+        'account could be created for the identity you signed in with.',
+    action_required:
+      'Sign in the way you originally did — a password, or whichever of Google, ' +
+        'Microsoft, GitHub or Apple you used first. If you need the two linked, ' +
+        'contact support.',
+    notes: [
+      'Creating a workspace will NOT fix this, and neither will signing in ' +
+        'again through the same provider. Nothing is wrong with the sign-in; ' +
+        'the account simply could not be created.',
+      `You can check which address is in use at ${CONFIG.webUrl}/settings.`,
+    ],
+  };
+}

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

@@ -26,8 +26,17 @@ 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 {
+  EMAIL_ALREADY_REGISTERED,
+  NOT_AUTHENTICATED,
+  NO_ORGANIZATION,
+  emailAlreadyRegistered,
+  organizationRequired,
+  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]
@@ -47,13 +56,34 @@ import { getInstructions } from './instructions.js';
  *
  * 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.
+ * through a sign-in that cannot fix it is worse than saying nothing. That case
+ * gets its own answer below — saying nothing was the placeholder, not the plan.
  */
 function isAuthFailure(error) {
   return error?.code === NOT_AUTHENTICATED || error?.status === 401;
 }
 
-export function createServer({ surface = 'local' } = {}) {
+/**
+ * Whether a failure means "signed in, but in no organization" (#2639).
+ *
+ * Keyed on the API's code, never on the message: the API owns the wording and
+ * will improve it, and a prose match that silently stops matching degrades to
+ * the bare 403 this exists to replace — the failure would be invisible, since
+ * the call still fails either way, just uselessly.
+ */
+function isNoOrganization(error) {
+  return error?.code === NO_ORGANIZATION;
+}
+
+/**
+ * Whether a failure means "signed in, but this email is already spoken for"
+ * (#2652). Same keying, and the same reason for it.
+ */
+function isEmailAlreadyRegistered(error) {
+  return error?.code === EMAIL_ALREADY_REGISTERED;
+}
+
+export function createServer({ surface = 'local', startSignIn = defaultStartSignIn } = {}) {
   const log = getLogger();
 
   // Filtered ONCE here rather than at each call site, so listing and dispatch
@@ -116,9 +146,60 @@ 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)) {
+        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
+      // OAuth; a missing workspace is ours either way, and a claude.ai user
+      // hits it exactly as a local one does.
+      if (isNoOrganization(error)) {
+        return {
+          content: [
+            { type: 'text', text: JSON.stringify(organizationRequired({ reason: errMsg }), null, 2) },
+          ],
+          isError: true,
+        };
+      }
+      // Checked separately from the branch above, never merged into it: these
+      // two look alike from outside and their answers point opposite ways.
+      if (isEmailAlreadyRegistered(error)) {
         return {
-          content: [{ type: 'text', text: JSON.stringify(signInRequired({ reason: errMsg }), null, 2) }],
+          content: [
+            { type: 'text', text: JSON.stringify(emailAlreadyRegistered({ reason: errMsg }), null, 2) },
+          ],
           isError: true,
         };
       }

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/http-client.js

@@ -163,6 +163,12 @@ export async function callZephlyAPI(endpoint, data) {
     // status and retryable let callers back off on a 503 instead of giving up
     // the way a 404 tells them to.
     thrown.status = response.status;
+    // A machine-readable code, when the API sent one. Carried so a caller can
+    // branch on the KIND of failure rather than on its prose — the no-organization
+    // 403 (#2639) is answered with specific guidance, and every other 403 is not.
+    if (typeof error.code === 'string' && error.code) {
+      thrown.code = error.code;
+    }
     if (typeof error.retryable === 'boolean') {
       thrown.retryable = error.retryable;
     }

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.0';
+export const MCP_VERSION = '0.14.2';

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "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: {