@ezmodo/mcp-server 0.13.3 → 0.13.5

package/http.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * HTTP entry point — the MCP tool surface over Streamable HTTP (#2599).
+ *
+ * This is what a remote connector talks to. The stdio entry point (index.js)
+ * is unchanged and stays the local path; both build the same server through
+ * lib/create-server.js, so the tool surface cannot differ between them.
+ *
+ * ── Stateless, and why ────────────────────────────────────────────────────────
+ * A fresh Server and transport are built per request, with
+ * `sessionIdGenerator: undefined`. The alternative — stateful sessions held in
+ * memory — cannot survive the deployment target: Cloud Run runs several
+ * instances with no session affinity, so a client's second request routinely
+ * lands on an instance that has never heard of its session and is rejected with
+ * a 404. Scale-to-zero would drop every session on the floor as well.
+ *
+ * Building per request is cheap here precisely because nothing in the server
+ * holds state: every handler is a function of its arguments plus the
+ * credential on the request.
+ *
+ * The cost is that the server cannot initiate messages to the client, so GET
+ * (the SSE upgrade) is answered 405. Today nothing is lost — this server sends
+ * no notifications and requests no sampling. If that changes, the fix is an
+ * external event store, not in-memory sessions.
+ *
+ * ── Authentication ───────────────────────────────────────────────────────────
+ * The credential comes from the request's Authorization header and is bound to
+ * that request only, via lib/request-context.js. Nothing is read from the
+ * environment, and no credential outlives the request that carried it.
+ *
+ * Today the bearer token is an EzModo API key. OAuth 2.1 lands in #2600/#2601;
+ * the 401 below already carries a WWW-Authenticate header so the discovery
+ * handshake has somewhere to attach.
+ */
+
+import { createServer as createHttpServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+import { createServer } from './lib/create-server.js';
+import { withRequestContext } from './lib/request-context.js';
+import { initLogger, getLogger } from './lib/logger.js';
+import { MCP_VERSION } from './lib/version.js';
+import { CONFIG } from './config/index.js';
+import { getApiUrl } from './lib/env.js';
+
+initLogger();
+const log = getLogger();
+
+const PORT = Number(process.env.PORT || 8080);
+const MCP_PATH = process.env.MCP_HTTP_PATH || '/mcp';
+
+// OAuth discovery (#2601). MCP_PUBLIC_URL is this server's public identity —
+// the "resource" in RFC 9728 terms — and must be the URL a client actually
+// dials, because a resource identifier that does not match what was requested
+// is how a token gets accepted for the wrong audience.
+const PUBLIC_URL = (process.env.MCP_PUBLIC_URL || `http://localhost:${PORT}${MCP_PATH}`).replace(/\/+$/, '');
+const KEYCLOAK_URL = (process.env.KEYCLOAK_URL || '').replace(/\/+$/, '');
+const KEYCLOAK_REALM = process.env.KEYCLOAK_REALM || 'ezmodo';
+const AUTH_SERVER = KEYCLOAK_URL ? `${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}` : '';
+
+// RFC 9728 forms the metadata URL by inserting /.well-known/... between the
+// host and the resource's path — so a resource at https://host/mcp publishes
+// at https://host/.well-known/oauth-protected-resource/mcp, NOT at the root.
+// Getting this wrong costs nothing for a client that follows the URL in the
+// 401, and everything for one that derives it instead, which the spec permits.
+const WELL_KNOWN = '/.well-known/oauth-protected-resource';
+const RESOURCE_PATH = new URL(PUBLIC_URL).pathname.replace(/\/+$/, '');
+const METADATA_PATH = `${WELL_KNOWN}${RESOURCE_PATH}`;
+const METADATA_URL = new URL(METADATA_PATH, PUBLIC_URL).toString();
+
+// Every path a client might reasonably ask for. The spec-derived one is what
+// gets advertised; the others are served because being generous here is free
+// and a failed discovery is opaque to debug from the client side.
+const METADATA_PATHS = new Set([METADATA_PATH, WELL_KNOWN, `${MCP_PATH}${WELL_KNOWN}`]);
+
+// The three scopes a person sees on the consent screen. Deliberately not the
+// ~33 the API enforces: a consent screen with thirty-three checkboxes is not
+// informed consent. The API expands these — see
+// api/internal/api/middleware/mcp_scopes.go.
+const CONSENT_SCOPES = ['ezmodo:read', 'ezmodo:write', 'ezmodo:delete'];
+
+/**
+ * RFC 9728 protected-resource metadata: what this resource is, and who issues
+ * tokens for it. A connector fetches this after a 401 to discover where to send
+ * the user for authorization.
+ */
+export function protectedResourceMetadata() {
+  return {
+    resource: PUBLIC_URL,
+    authorization_servers: AUTH_SERVER ? [AUTH_SERVER] : [],
+    scopes_supported: CONSENT_SCOPES,
+    bearer_methods_supported: ['header'],
+    resource_documentation: 'https://ezmodo.com/help/connectors',
+  };
+}
+
+/**
+ * The WWW-Authenticate challenge. `resource_metadata` is the whole point: it
+ * is how a client that has never seen this server finds the authorization
+ * server without being told out of band.
+ */
+function authenticateChallenge(error, description) {
+  const parts = ['Bearer realm="ezmodo-mcp"', `resource_metadata="${METADATA_URL}"`];
+  if (error) parts.push(`error="${error}"`);
+  if (description) parts.push(`error_description="${description}"`);
+  return parts.join(', ');
+}
+
+/** Bearer token from the Authorization header, or null. */
+export function bearerToken(headerValue) {
+  if (typeof headerValue !== 'string') return null;
+  const match = /^Bearer\s+(.+)$/i.exec(headerValue.trim());
+  const token = match?.[1]?.trim();
+  return token ? token : null;
+}
+
+function sendJson(res, status, body, extraHeaders = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+    ...extraHeaders,
+  });
+  res.end(payload);
+}
+
+/** A JSON-RPC error shaped so an MCP client can read it, not just a bare HTTP code. */
+function rpcError(res, status, code, message, extraHeaders) {
+  sendJson(res, status, { jsonrpc: '2.0', error: { code, message }, id: null }, extraHeaders);
+}
+
+async function readBody(req, limitBytes = 8 * 1024 * 1024) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    // Bounded on purpose: this endpoint is reachable by anyone who can reach
+    // the service, so an unbounded read is a trivial way to exhaust memory.
+    if (size > limitBytes) {
+      const err = new Error('Request body too large');
+      err.statusCode = 413;
+      throw err;
+    }
+    chunks.push(chunk);
+  }
+  if (!chunks.length) return undefined;
+  return JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+}
+
+async function handleMcpPost(req, res, requestId) {
+  const token = bearerToken(req.headers.authorization);
+  if (!token) {
+    log.warn('MCP request without credentials', { requestId });
+    // The WWW-Authenticate header is where OAuth discovery attaches in #2601;
+    // it costs nothing now and means clients already look in the right place.
+    return rpcError(res, 401, -32001, 'Missing or malformed Authorization header. Expected: Bearer <token>', {
+      'WWW-Authenticate': authenticateChallenge('invalid_request', 'Authorization header required'),
+    });
+  }
+
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (error) {
+    const status = error.statusCode === 413 ? 413 : 400;
+    log.warn('Unreadable MCP request body', { requestId, error: error.message });
+    return rpcError(res, status, -32700, `Could not parse request body: ${error.message}`);
+  }
+
+  // One server and transport per request — see the stateless note at the top.
+  // 'remote': excludes tools that operate on a local checkout, which do not
+  // exist here and whose git helpers shell out with caller-supplied arguments
+  // (#2614).
+  const server = createServer({ surface: 'remote' });
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+  // Closing on response end matters: without it every request leaks a transport
+  // and its server, and the leak only shows up under sustained load.
+  res.on('close', () => {
+    transport.close().catch(() => {});
+    server.close().catch(() => {});
+  });
+
+  await server.connect(transport);
+  await withRequestContext({ apiKey: token }, () => transport.handleRequest(req, res, body));
+}
+
+const httpServer = createHttpServer(async (req, res) => {
+  const requestId = randomUUID();
+  const started = Date.now();
+  const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+  res.on('finish', () => {
+    log.info('http request', {
+      requestId,
+      method: req.method,
+      path: url.pathname,
+      status: res.statusCode,
+      durationMs: Date.now() - started,
+    });
+  });
+
+  try {
+    // Health check. Deliberately does NOT touch the EzModo API: this answers
+    // "is this process serving?", and a health check that fails when a
+    // dependency is briefly unavailable gets the container killed and makes an
+    // outage worse.
+    // Served unauthenticated and before anything else: discovery is what a
+    // client reads BECAUSE it has no credential yet, so requiring one would
+    // make the handshake unresolvable.
+    if (METADATA_PATHS.has(url.pathname)) {
+      return sendJson(res, 200, protectedResourceMetadata(), {
+        'Cache-Control': 'public, max-age=3600',
+      });
+    }
+
+    if (url.pathname === '/health' || url.pathname === '/healthz') {
+      return sendJson(res, 200, { status: 'ok', version: MCP_VERSION, environment: CONFIG.environment });
+    }
+
+    if (url.pathname !== MCP_PATH) {
+      return rpcError(res, 404, -32601, `Not found. The MCP endpoint is ${MCP_PATH}`);
+    }
+
+    if (req.method === 'POST') {
+      return await handleMcpPost(req, res, requestId);
+    }
+
+    // GET is the SSE upgrade for server-initiated messages, which stateless
+    // mode cannot serve. Said plainly rather than by a bare 405, because
+    // "method not allowed" on a spec-defined method reads as a bug.
+    if (req.method === 'GET') {
+      return rpcError(res, 405, -32000,
+        'This server runs stateless; server-initiated SSE streams are not supported. Use POST.',
+        { Allow: 'POST' });
+    }
+
+    return rpcError(res, 405, -32000, `${req.method} is not supported on ${MCP_PATH}`, { Allow: 'POST' });
+  } catch (error) {
+    log.error('Unhandled error serving request', {
+      requestId,
+      error: error?.message || String(error),
+    });
+    if (!res.headersSent) {
+      rpcError(res, 500, -32603, 'Internal server error');
+    } else {
+      res.end();
+    }
+  }
+});
+
+httpServer.listen(PORT, () => {
+  log.info('MCP server running over HTTP', { port: PORT, path: MCP_PATH, version: MCP_VERSION });
+  console.error(`✅ ezmodo MCP Server (HTTP) on :${PORT}${MCP_PATH}`);
+  // The RESOLVED url, not CONFIG.apiUrl: EZMODO_API_URL overrides it per call,
+  // so printing the build-time default tells an operator pointing this at a
+  // local stack the opposite of what is happening.
+  console.error(`   Environment: ${CONFIG.environment}   API URL: ${getApiUrl() || CONFIG.apiUrl}`);
+  console.error(`   Resource: ${PUBLIC_URL}`);
+  console.error(`   Metadata: ${METADATA_URL}`);
+  // Say so loudly rather than serving a metadata document with an empty
+  // authorization_servers array, which fails later and further away.
+  console.error(
+    AUTH_SERVER
+      ? `   Authorization server: ${AUTH_SERVER}`
+      : '   ⚠️  KEYCLOAK_URL is unset — OAuth discovery will advertise no authorization server.'
+  );
+});
+
+// Cloud Run sends SIGTERM before reclaiming an instance. Closing gracefully
+// lets in-flight tool calls finish instead of being cut off mid-request.
+for (const signal of ['SIGTERM', 'SIGINT']) {
+  process.on(signal, () => {
+    log.info('Shutting down', { signal });
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 10_000).unref();
+  });
+}

package/index.js

@@ -7,47 +7,62 @@
  * projects, tasks, and documentation via HTTP API.
  */
 
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
 
 // Import configuration
 import { CONFIG } from './config/index.js';
 
-// Import tool definitions and handlers
-import { TOOLS } from './tools/index.js';
-import { HANDLERS } from './handlers/index.js';
-
-// Import prompts
-import { PROMPTS, getPromptContent } from './prompts/index.js';
-
-import { MCP_VERSION } from './lib/version.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';
 
 // ============================================================
 // Configuration Validation
 // ============================================================
 
-const apiKey = getApiKey();
-
 // Initialize logger early (before any logging)
 initLogger();
 const log = getLogger();
 
+let apiKey = getApiKey();
+let apiKeySource = 'EZMODO_API_KEY';
+
+// Fall back to the credential `ezmodo auth login` already stored (#2611).
+//
+// 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.
+//
+// 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('Missing required environment variable: EZMODO_API_KEY', {
+  log.error('No API key: EZMODO_API_KEY is unset and no ezmodo CLI credential was found', {
     settingsUrl: CONFIG.settingsUrl,
   });
-  console.error('ERROR: Missing required environment variable:');
-  console.error('- EZMODO_API_KEY (or legacy ZEPHLY_API_KEY)');
-  console.error('\nPlease set your ezmodo API key to use this MCP server.');
-  console.error(`Generate one at: ${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)');
@@ -63,103 +78,25 @@ log.info('MCP server starting', {
   environment: CONFIG.environment,
   apiUrl: CONFIG.apiUrl,
   apiKeyPrefix: apiKey.substring(0, 12),
+  apiKeySource,
 });
 console.error('🔧 ezmodo MCP Server Configuration:');
 console.error(`   Environment: ${CONFIG.environment} (build-time)`);
 console.error(`   API URL: ${CONFIG.apiUrl}`);
-console.error(`   API Key: ${apiKey.substring(0, 12)}...`);
+// 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})`);
 console.error('');
 
 // ============================================================
-// MCP Server Setup
+// Start Server (stdio)
 // ============================================================
+//
+// This file is the STDIO entry point. The HTTP entry point is http.js; both
+// build the same server through lib/create-server.js, so the tool surface
+// cannot differ between them.
 
-const server = new Server(
-  {
-    name: 'ezmodo-mcp-server',
-    version: MCP_VERSION,
-  },
-  {
-    capabilities: {
-      tools: {},
-      prompts: {},
-    },
-  }
-);
-
-// Register tool handlers
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: TOOLS,
-}));
-
-// Register tool call handler
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  // Get handler function for this tool
-  const handler = HANDLERS[name];
-
-  if (!handler) {
-    throw new Error(`Unknown tool: ${name}`);
-  }
-
-  const start = Date.now();
-  try {
-    const result = await handler(args || {});
-    log.debug('Tool call succeeded', { tool: name, durationMs: Date.now() - start });
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(result, null, 2),
-        },
-      ],
-    };
-  } catch (error) {
-    const errMsg = error.message || String(error);
-    log.error('Tool call failed', { tool: name, error: errMsg, durationMs: Date.now() - start });
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify({
-            error: error.message || String(error),
-          }, null, 2),
-        },
-      ],
-      isError: true,
-    };
-  }
-});
-
-// Register prompt handlers
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-  prompts: PROMPTS,
-}));
-
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-  const content = getPromptContent(request.params.name);
-
-  if (!content) {
-    throw new Error(`Unknown prompt: ${request.params.name}`);
-  }
-
-  return {
-    messages: [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: content,
-        },
-      },
-    ],
-  };
-});
-
-// ============================================================
-// Start Server
-// ============================================================
+const server = createServer();
 
 async function main() {
   const transport = new StdioServerTransport();

package/lib/cli-credential.js

@@ -0,0 +1,103 @@
+/**
+ * Read the API key the `ezmodo` CLI already stored, when EZMODO_API_KEY is not
+ * set.
+ *
+ * Why this exists: the Claude Code plugin launches this server through npx and
+ * passes `${EZMODO_API_KEY:-}` from the environment. A user who has run
+ * `ezmodo auth login` has a perfectly good key on disk and no idea they must
+ * also export it, so their first run dies and Claude Code reports
+ * `CONNECTION_CLOSED` — the server's own clear message goes to a stderr log
+ * nobody opens (#2611).
+ *
+ * This is a FALLBACK, never a requirement. The CLI does not have to be
+ * installed, nothing here throws, and an explicit EZMODO_API_KEY always wins:
+ * an explicit credential must beat an implicit one, or overriding the key for
+ * one project becomes impossible to reason about.
+ *
+ * It deliberately re-implements the CLI's read rather than importing it — this
+ * package is published to npm and must not depend on the CLI being present.
+ * The formats it reads are owned by cli/src/lib/auth-store.ts and
+ * cli/src/lib/user-paths.ts; if those move, this goes stale and simply stops
+ * finding anything, which is the safe direction to fail in.
+ */
+
+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')];
+}
+
+/** The Linux/Windows path: a 0600 JSON file written by `ezmodo auth login`. */
+function fromCredentialsFile() {
+  for (const dir of configDirs()) {
+    const path = join(dir, 'credentials');
+    if (!existsSync(path)) continue;
+    try {
+      const key = JSON.parse(readFileSync(path, 'utf-8'))?.apiKey;
+      if (typeof key === 'string' && key.trim()) return key.trim();
+    } catch {
+      // Unreadable or malformed — try the next location, then give up.
+    }
+  }
+  return null;
+}
+
+/**
+ * The macOS path: the CLI stores in the login Keychain via the `security`
+ * binary, so there is no file to read.
+ *
+ * Bounded by a timeout on purpose. Keychain items carry an ACL, and a read the
+ * ACL does not allow can raise a GUI prompt — which, from a server started
+ * headlessly by an editor, would be a worse failure than the one this whole
+ * module exists to fix. The timeout means the worst case is a dialog that
+ * disappears within two seconds and a fall through to "no key found", i.e.
+ * exactly today's behaviour.
+ */
+function fromMacKeychain() {
+  if (process.platform !== 'darwin') return null;
+  for (const service of ['ezmodo-cli', 'zephly-cli']) {
+    try {
+      const key = execFileSync(
+        'security',
+        ['find-generic-password', '-s', service, '-a', 'api-key', '-w'],
+        { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
+      ).trim();
+      if (key) return key;
+    } 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.
+    }
+  }
+  return null;
+}
+
+/**
+ * The CLI's stored key, or null. Never throws.
+ *
+ * Returns `{ key, source }` so the caller can tell the user WHERE the
+ * credential came from. A server that silently authenticates as someone the
+ * user did not choose is worse than one that fails.
+ */
+export function readCliCredential() {
+  try {
+    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)' };
+  } catch {
+    // Belt and braces. Nothing above should throw, and if something does, a
+    // missing fallback must not take down the server.
+  }
+  return null;
+}

package/lib/create-server.js

@@ -0,0 +1,108 @@
+/**
+ * Builds a configured MCP `Server` — tools, prompts and their handlers.
+ *
+ * Extracted from index.js so stdio and HTTP share ONE definition of the tool
+ * surface (#2599). Two entry points that each register their own handlers is
+ * how a tool ends up working on one transport and not the other, and the gap
+ * is invisible until a user reports it.
+ *
+ * A fresh Server per call, deliberately. The HTTP transport runs stateless and
+ * builds one per request; that is only safe because nothing here holds state
+ * between calls — every handler is a function of its arguments plus the
+ * credential in the request context.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { TOOLS } from '../tools/index.js';
+import { HANDLERS } from '../handlers/index.js';
+import { PROMPTS, getPromptContent } from '../prompts/index.js';
+import { MCP_VERSION } from './version.js';
+import { getLogger } from './logger.js';
+import { isRemoteSafe } from './remote-tools.js';
+
+/**
+ * @param {object} [options]
+ * @param {'local'|'remote'} [options.surface] Which tool surface to serve.
+ *   'local' (the default) is the full set, for stdio on a user's machine.
+ *   '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.
+ */
+export function createServer({ surface = 'local' } = {}) {
+  const log = getLogger();
+
+  // Filtered ONCE here rather than at each call site, so listing and dispatch
+  // cannot disagree. They must agree: filtering only tools/list would leave
+  // every excluded handler dispatchable by a client that guesses the name,
+  // which is the failure this whole module exists to prevent.
+  const tools = surface === 'remote' ? TOOLS.filter((tool) => isRemoteSafe(tool.name)) : TOOLS;
+  const available = new Set(tools.map((tool) => tool.name));
+
+  const server = new Server(
+    { name: 'ezmodo-mcp-server', version: MCP_VERSION },
+    { capabilities: { tools: {}, prompts: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    // Checked before the handler lookup: a tool excluded from this surface is
+    // refused even though HANDLERS still contains it.
+    if (!available.has(name)) {
+      const handler = HANDLERS[name];
+      if (handler) {
+        log.warn('Refused a tool not served on this surface', { tool: name, surface });
+        throw new Error(
+          `Tool "${name}" is not available over this connection. It operates on a local ` +
+            'checkout and is served only by the local (stdio) MCP server.'
+        );
+      }
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    const handler = HANDLERS[name];
+    if (!handler) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    const start = Date.now();
+    try {
+      const result = await handler(args || {});
+      log.debug('Tool call succeeded', { tool: name, durationMs: Date.now() - start });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      const errMsg = error.message || String(error);
+      log.error('Tool call failed', { tool: name, error: errMsg, durationMs: Date.now() - start });
+      // 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 {
+        content: [{ type: 'text', text: JSON.stringify({ error: errMsg }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const content = getPromptContent(request.params.name);
+    if (!content) {
+      throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return {
+      messages: [{ role: 'user', content: { type: 'text', text: content } }],
+    };
+  });
+
+  return server;
+}

package/lib/http-client.js

@@ -9,7 +9,12 @@ import { ENDPOINT_MAP } from '../config/endpoint-map.js';
 import { CONFIG } from '../config/index.js';
 import { MCP_VERSION } from './version.js';
 import { getLogger } from './logger.js';
-import { getApiKey, getApiUrl } from './env.js';
+import { getApiUrl } from './env.js';
+// Not getApiKey() directly: over HTTP one process serves many callers, so the
+// credential belongs to the request in flight rather than the process (#2599).
+// Over stdio there is no request context and this resolves to the environment,
+// exactly as before.
+import { resolveApiKey } from './request-context.js';
 
 // API base URL is resolved per-request (see callZephlyAPI): getApiUrl() honors
 // the EZMODO_API_URL / ZEPHLY_API_URL override; CONFIG.apiUrl is the build-time
@@ -78,7 +83,7 @@ export async function callZephlyAPI(endpoint, data) {
   let body = null;
 
   const headers = {
-    'Authorization': `Bearer ${getApiKey()}`,
+    'Authorization': `Bearer ${resolveApiKey()}`,
     'Content-Type': 'application/json',
     'User-Agent': `ezmodo-mcp-server/${MCP_VERSION}`,
     'X-MCP-API-Version': 'v1',

package/lib/remote-tools.js

@@ -0,0 +1,151 @@
+/**
+ * Which tools may be served over the REMOTE transport (#2614).
+ *
+ * The HTTP entry point and the stdio entry point deliberately build the same
+ * server (lib/create-server.js) so their tool surfaces cannot drift. That is
+ * right for almost everything — and wrong for the handful of tools that are
+ * not network operations at all.
+ *
+ * `detect_git_repository`, `manage_worktree`, `rebuild_manifest` and friends
+ * read and write the LOCAL machine: the working directory, `.ezmodo/`, the git
+ * repository. Over stdio that is the whole point — the server runs inside the
+ * user's checkout, at their request, as them. On a hosted server there is no
+ * checkout, so at best they fail confusingly.
+ *
+ * At worst they are dangerous. lib/git-helpers.js `execGit` passes its command
+ * to `execSync` — a shell — and callers interpolate tool arguments into it:
+ *
+ *     execGit(`git branch ${branchName} ${baseBranch}`, repoPath)
+ *
+ * On a user's own machine the blast radius is their own shell, which is why
+ * this has been tolerable. Reachable over the internet it is arbitrary command
+ * execution in the container. So these tools are not hardened for remote use —
+ * they are not served remotely at all, because they have no meaning there and
+ * hardening would leave a shell-executing surface exposed for no benefit.
+ *
+ * ── The list is an ALLOWLIST, deliberately ───────────────────────────────────
+ *
+ * A denylist would mean every tool added from now on is exposed remotely by
+ * default, and the mistake would be invisible: the tool simply works, until one
+ * of them turns out to touch the filesystem. Listing what is safe means a new
+ * tool is refused remotely until someone decides otherwise, and
+ * remote-tools.test.js fails loudly when a tool is unclassified rather than
+ * letting it through.
+ *
+ * Note some tools do local work as a SIDE EFFECT and are still fine here:
+ * manage_task writes `.ezmodo/active-session.json`, and lib/active-session.js
+ * already skips that when no config directory exists — which is exactly the
+ * case in a container. Likewise get_context and resolve_concepts read a local
+ * manifest when there is one and fall back to the API when there is not.
+ */
+
+/** Tools that operate on the local machine and are never served remotely. */
+export const LOCAL_ONLY_TOOLS = Object.freeze([
+  'detect_git_repository',
+  'get_current_project_context',
+  'initialize_project_context',
+  'list_project_worktrees',
+  'manage_worktree',
+  'rebuild_manifest',
+]);
+
+/** Tools safe to serve over the remote transport. */
+export const REMOTE_SAFE_TOOLS = Object.freeze([
+  'accept_agent_suggestion',
+  'configure_agent',
+  'create_tasks',
+  'delete_attachment',
+  'estimate_task',
+  'evaluate_feature_flag',
+  'get_access',
+  'get_ai_insights',
+  'get_attachment_url',
+  'get_catalog',
+  'get_catalog_diff',
+  'get_context',
+  'get_decision',
+  'get_design',
+  'get_design_system',
+  'get_document',
+  'get_document_template',
+  'get_epic',
+  'get_feature',
+  'get_feature_flag',
+  'get_goal',
+  'get_graph',
+  'get_manifest_schema',
+  'get_milestone',
+  'get_org_areas',
+  'get_organization',
+  'get_project',
+  'get_project_changes',
+  'get_project_story',
+  'get_task',
+  'get_testing_summary',
+  'infer_dependencies',
+  'list_agent_suggestions',
+  'list_attachments',
+  'list_catalog_items',
+  'list_catalogs',
+  'list_components',
+  'list_designs',
+  'list_epics',
+  'list_facts',
+  'list_feature_flags',
+  'list_folders',
+  'list_links',
+  'list_notifications',
+  'list_org_documents',
+  'list_repositories',
+  'list_tags',
+  'list_test_cases',
+  'list_test_suites',
+  'list_todos',
+  'list_watched',
+  'manage_access',
+  'manage_catalog',
+  'manage_component',
+  'manage_decision',
+  'manage_design',
+  'manage_document',
+  'manage_document_template',
+  'manage_environment',
+  'manage_epic',
+  'manage_fact',
+  'manage_feature',
+  'manage_feature_flag',
+  'manage_folder',
+  'manage_goal',
+  'manage_link',
+  'manage_milestone',
+  'manage_project',
+  'manage_pull_request',
+  'manage_recurring_task',
+  'manage_tag',
+  'manage_task',
+  'manage_team',
+  'manage_test_case',
+  'manage_test_suite',
+  'manage_todo',
+  'manage_watch',
+  'manage_work_template',
+  'preview_links',
+  'reject_agent_suggestion',
+  'report_untracked_work',
+  'resolve_concepts',
+  'resolve_link_suggestions',
+  'resolve_links',
+  'run_agent_now',
+  'search_epics',
+  'search_features',
+  'search_tasks',
+  'update_manifest_entries',
+  'validate_manifest',
+]);
+
+const remoteSafe = new Set(REMOTE_SAFE_TOOLS);
+
+/** Whether a tool may be served over the remote transport. */
+export function isRemoteSafe(toolName) {
+  return remoteSafe.has(toolName);
+}

package/lib/request-context.js

@@ -0,0 +1,53 @@
+/**
+ * Per-request credential context.
+ *
+ * Over stdio the server belongs to one user for its whole life, so the API key
+ * can live in the environment and `lib/http-client.js` can read it whenever it
+ * likes. Over HTTP that assumption is gone: one process serves many callers,
+ * each with their own credential, and requests interleave (#2599).
+ *
+ * AsyncLocalStorage is what makes that a five-line change instead of a
+ * signature change through every handler. The transport runs each request
+ * inside `withRequestContext`, and `resolveApiKey()` picks up whatever that
+ * request carried — through every await, without any handler knowing it exists.
+ *
+ * The environment remains the fallback, and that is what keeps stdio working
+ * untouched: no context, no behaviour change.
+ *
+ * The safety property worth stating: a leaked context is a request answered
+ * with SOMEONE ELSE'S credential. So the store is only ever written by
+ * withRequestContext, is never mutated in place, and nothing exported here can
+ * set it for longer than one callback.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { getApiKey } from './env.js';
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `context` bound to it and everything it awaits.
+ *
+ * @param {{ apiKey?: string }} context
+ * @param {() => Promise<T>|T} fn
+ * @returns {Promise<T>|T}
+ * @template T
+ */
+export function withRequestContext(context, fn) {
+  return storage.run(Object.freeze({ ...context }), fn);
+}
+
+/** The current request's context, or undefined outside one. */
+export function getRequestContext() {
+  return storage.getStore();
+}
+
+/**
+ * The credential for the request in flight.
+ *
+ * Request context wins over the environment. Over HTTP that is the whole
+ * point; over stdio there is no context and this is exactly getApiKey().
+ */
+export function resolveApiKey() {
+  return storage.getStore()?.apiKey || getApiKey();
+}

package/lib/version.js

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

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",
   "bin": {
     "ezmodo-mcp-server": "./index.js",
-    "zephly-mcp-server": "./index.js"
+    "zephly-mcp-server": "./index.js",
+    "ezmodo-mcp-server-http": "./http.js"
   },
   "scripts": {
     "dev": "BUILD_ENV=development node index.js",
     "start": "node index.js",
+    "start:http": "node http.js",
+    "dev:http": "BUILD_ENV=development node http.js",
     "build:production": "BUILD_ENV=production node --input-type=module -e 'console.log(\"Production build configured\")'",
     "build:staging": "BUILD_ENV=staging node --input-type=module -e 'console.log(\"Staging build configured\")'",
     "build:development": "BUILD_ENV=development node --input-type=module -e 'console.log(\"Development build configured\")'",
@@ -34,6 +37,7 @@
   },
   "files": [
     "index.js",
+    "http.js",
     "config/",
     "handlers/",
     "lib/",
@@ -41,10 +45,10 @@
     "tools/",
     "README.md"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/EasyModeOnly/ezmodo.git",
-    "directory": "mcp-server"
+  "homepage": "https://ezmodo.com/docs/emo/ezmodo/help/cli-mcp",
+  "bugs": {
+    "url": "https://ezmodo.com/support",
+    "email": "help@ezmodo.com"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",