@ezmodo/mcp-server 0.14.0 → 0.14.1

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", "@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", "@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/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 ' +
+    'says how to fix it; see `organizationRequired` below.',
 ];
 
 /**
@@ -65,3 +84,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/create-server.js

@@ -26,7 +26,14 @@ 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';
 
 /**
@@ -47,12 +54,33 @@ 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;
 }
 
+/**
+ * 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' } = {}) {
   const log = getLogger();
 
@@ -122,6 +150,28 @@ export function createServer({ surface = 'local' } = {}) {
           isError: true,
         };
       }
+      // 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(emailAlreadyRegistered({ 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 {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",