@ezmodo/mcp-server 0.13.0

package/lib/http-client.js

@@ -0,0 +1,164 @@
+/**
+ * HTTP Client for EzModo API
+ * Handles API requests, encoding, and response unwrapping
+ */
+
+import fetch from 'node-fetch';
+import zlib from 'zlib';
+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';
+
+// 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
+// default. Resolving per-call (not at module load) keeps it correct regardless
+// of when the env var is set, and lets a desktop/self-hosted runner point the
+// MCP server at a non-production API.
+
+/**
+ * Bodies larger than this (bytes, uncompressed JSON) are gzip-compressed and
+ * sent with Content-Encoding: gzip instead of the base64 WAF wrapper. gzip both
+ * shrinks the payload (~10-20x for schema/manifest JSON, vs base64's +33%
+ * inflation) and is WAF-safe (binary body, not pattern-matchable), so large
+ * uploads like DB schema snapshots stay well under Cloud Run's 32 MB request
+ * limit. The Go API's MCP routes decompress gzip request bodies transparently.
+ */
+const GZIP_THRESHOLD_BYTES = 64 * 1024;
+
+/**
+ * Encode string to base64
+ */
+function encodeBase64(str) {
+  return Buffer.from(str, 'utf-8').toString('base64');
+}
+
+/**
+ * Encode entire request body to prevent WAF blocking
+ * Wraps the entire payload in a base64-encoded container
+ *
+ * This is simpler and more reliable than field-by-field encoding:
+ * - No maintenance of field lists
+ * - Bulletproof against all WAF rules
+ * - Works for any future fields automatically
+ */
+function encodeBodyForWAF(data) {
+  if (data === null || data === undefined || Object.keys(data).length === 0) {
+    return data;
+  }
+
+  // Encode the entire body as a single base64 string
+  const jsonString = JSON.stringify(data);
+  return {
+    __base64_body: true,
+    value: encodeBase64(jsonString)
+  };
+}
+
+/**
+ * Call Zephly API endpoint
+ * @param {string} endpoint - Endpoint name (e.g., 'mcpCreateTask')
+ * @param {object} data - Request data
+ * @returns {Promise<any>} - API response (unwrapped from Go API structure)
+ */
+export async function callZephlyAPI(endpoint, data) {
+  // Get endpoint mapping (route + HTTP method)
+  const mapping = ENDPOINT_MAP[endpoint];
+
+  if (!mapping) {
+    throw new Error(`Unknown endpoint: ${endpoint}. Please update ENDPOINT_MAP.`);
+  }
+
+  const { route, method } = mapping;
+
+  // Build URL - for GET and DELETE requests with data, append as query params
+  const apiUrl = getApiUrl() || CONFIG.apiUrl;
+  let url = `${apiUrl}/${route}`;
+  let body = null;
+
+  const headers = {
+    'Authorization': `Bearer ${getApiKey()}`,
+    'Content-Type': 'application/json',
+    'User-Agent': `ezmodo-mcp-server/${MCP_VERSION}`,
+    'X-MCP-API-Version': 'v1',
+  };
+
+  if ((method === 'GET' || method === 'DELETE') && data && Object.keys(data).length > 0) {
+    // Convert data object to query parameters for GET and DELETE
+    // DELETE requests typically don't have a body and the Go API expects query params
+    const params = new URLSearchParams();
+    Object.entries(data).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        params.append(key, String(value));
+      }
+    });
+    url += `?${params.toString()}`;
+  } else if (method !== 'GET' && method !== 'DELETE') {
+    // For POST/PUT, send data in body.
+    const isEmpty = data === null || data === undefined || Object.keys(data).length === 0;
+    const rawJson = JSON.stringify(data);
+    if (!isEmpty && Buffer.byteLength(rawJson, 'utf-8') > GZIP_THRESHOLD_BYTES) {
+      // Large body: gzip the raw JSON. Smaller than base64 and WAF-safe (binary),
+      // so big uploads (e.g. DB schema snapshots) don't inflate or time out.
+      body = zlib.gzipSync(Buffer.from(rawJson, 'utf-8'));
+      headers['Content-Encoding'] = 'gzip';
+    } else {
+      // Small body: base64-wrap the entire body to prevent WAF blocking.
+      body = JSON.stringify(encodeBodyForWAF(data));
+    }
+  }
+
+  const log = getLogger();
+  log.debug('API request', { endpoint, method, route, url });
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body,
+  });
+
+  log.debug('API response', { endpoint, status: response.status });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    log.error('API error', { endpoint, status: response.status, body: errorText });
+
+    let error;
+    try {
+      error = JSON.parse(errorText);
+    } catch {
+      error = { error: response.statusText };
+    }
+
+    // Keep the API's own diagnosis on the error rather than flattening the
+    // response to its headline. During E-228 #2252 the API was already sending
+    // the true cause in `details` ("failed to load task_knowledge: database
+    // capacity temporarily exhausted") while this line threw only
+    // "Task not found" — so the one caller that could have acted on it, the
+    // agent, was told the task did not exist.
+    const headline =
+      error.error || error.message || `HTTP ${response.status}: ${response.statusText}`;
+    const detail = typeof error.details === 'string' ? error.details : null;
+
+    const thrown = new Error(detail && detail !== headline ? `${headline}: ${detail}` : headline);
+    // 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;
+    if (typeof error.retryable === 'boolean') {
+      thrown.retryable = error.retryable;
+    }
+    throw thrown;
+  }
+
+  const result = await response.json();
+  log.debug('API success', { endpoint });
+
+  // Go API returns {success, data, metadata}, Cloud Functions return data directly
+  // For backward compatibility, unwrap Go API responses if they have the expected structure
+  if (result.success === true && result.data !== undefined) {
+    return result.data;
+  }
+
+  return result;
+}

package/lib/links-at-create.js

@@ -0,0 +1,94 @@
+/**
+ * Links at create time (E-225).
+ *
+ * Creation tools accept a `links: [{targetType, targetId, linkType?}]` param so
+ * an entity is born connected to the feature/goal/flag/document it belongs to.
+ * This is the shared apply step every create handler calls after the entity
+ * exists and its id is known.
+ *
+ * The invariant: NEVER THROWS. A link failure must not fail the entity create —
+ * the entity is the user's work, the link is metadata. Failures come back in
+ * `failed` so the agent (and the response) can see them. This mirrors
+ * `applyAutoTags` in handlers/tasks.js.
+ *
+ * Links are applied ONE PER REQUEST, deliberately. This shipped anticipating a
+ * `POST mcp/v1/links/batch` that was never implemented on the Go API, so every
+ * create-with-links paid a 404 before falling back to exactly this loop — an
+ * optimization that only ever cost a round trip. Real callers pass a handful of
+ * links (the desktop LinkGate and the MCP create tools: typically one to five),
+ * which is not enough to earn a second write surface. If some caller ever
+ * arrives with dozens, batching is worth revisiting; until then this is the
+ * whole story.
+ */
+
+import { callZephlyAPI } from './http-client.js';
+import { getLogger } from './logger.js';
+
+const DEFAULT_LINK_TYPE = 'relates_to';
+
+/** Normalize + drop malformed entries. Returns [] when there is nothing to do. */
+function normalize(links) {
+  if (!Array.isArray(links)) return [];
+  return links
+    .filter((l) => l && l.targetType && l.targetId)
+    .map((l) => ({
+      targetType: l.targetType,
+      targetId: l.targetId,
+      linkType: l.linkType || DEFAULT_LINK_TYPE,
+    }));
+}
+
+/**
+ * Attach `links` to a just-created entity.
+ *
+ * @param {object} params
+ * @param {string} params.sourceType - Linkable type of the created entity.
+ * @param {string} params.sourceId   - ID of the created entity.
+ * @param {Array}  params.links      - [{targetType, targetId, linkType?}]
+ * @returns {Promise<{applied: Array, failed: Array}>} never rejects
+ */
+export async function applyLinks({ sourceType, sourceId, links }) {
+  const items = normalize(links);
+  if (!sourceType || !sourceId || items.length === 0) {
+    return { applied: [], failed: [] };
+  }
+
+  const applied = [];
+  const failed = [];
+  for (const item of items) {
+    try {
+      await callZephlyAPI('mcpAddLink', {
+        sourceType,
+        sourceId,
+        targetType: item.targetType,
+        targetId: item.targetId,
+        linkType: item.linkType,
+      });
+      applied.push(item);
+    } catch (err) {
+      getLogger().warn('Link failed', {
+        sourceType,
+        sourceId,
+        targetType: item.targetType,
+        targetId: item.targetId,
+        error: err.message,
+      });
+      failed.push({ ...item, error: err.message });
+    }
+  }
+  return { applied, failed };
+}
+
+/**
+ * Convenience wrapper for create handlers: applies the links and stamps the
+ * outcome onto the create result as `result.links`. No-op (and no property
+ * added) when there is nothing to link or the id could not be resolved.
+ */
+export async function attachLinks(result, { sourceType, sourceId, links }) {
+  const items = normalize(links);
+  if (items.length === 0 || !sourceId || !result || typeof result !== 'object') {
+    return result;
+  }
+  result.links = await applyLinks({ sourceType, sourceId, links: items });
+  return result;
+}

package/lib/local-cache.js

@@ -0,0 +1,140 @@
+/**
+ * Local Cache Utility
+ * Reads and writes the project config.json cache for tags and components.
+ * Looks in `.ezmodo/` first, falls back to legacy `.zephly/`.
+ * Used by MCP handlers to avoid unnecessary API calls for frequently-read data.
+ */
+
+import fs from 'fs/promises';
+import { findRepoConfigPath } from './repo-config-dir.js';
+
+// In-memory cache of the config file path (avoids walking directories repeatedly)
+let _cachedConfigPath = null;
+
+/**
+ * Check if cached data is still fresh.
+ * Returns true if lastUpdatedAt is within ttlDays (default 1).
+ * Returns false for missing/malformed timestamps.
+ */
+export function isCacheFresh(lastUpdatedAt, ttlDays = 1) {
+  if (!lastUpdatedAt) return false;
+  try {
+    const updated = new Date(lastUpdatedAt);
+    if (isNaN(updated.getTime())) return false;
+    const ageMs = Date.now() - updated.getTime();
+    return ageMs < ttlDays * 24 * 60 * 60 * 1000;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up the directory tree to find the project config.json. Tries
+ * `.ezmodo/config.json` first, falls back to legacy `.zephly/config.json`.
+ * Caches the result in memory for subsequent calls.
+ * @returns {Promise<string|null>} Absolute path to config.json, or null if not found
+ */
+export async function findConfigPath(startDir = process.cwd()) {
+  // Try in-memory cached path first
+  if (_cachedConfigPath) {
+    try {
+      await fs.access(_cachedConfigPath);
+      return _cachedConfigPath;
+    } catch {
+      _cachedConfigPath = null;
+    }
+  }
+
+  const configPath = await findRepoConfigPath(startDir);
+  if (configPath) _cachedConfigPath = configPath;
+  return configPath;
+}
+
+/**
+ * Read and parse the project config.json file (current `.ezmodo/` location
+ * or legacy `.zephly/` fallback).
+ * @returns {Promise<object|null>} Parsed config, or null if not found/invalid
+ */
+export async function readConfig() {
+  const configPath = await findConfigPath();
+  if (!configPath) return null;
+  try {
+    const content = await fs.readFile(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the config object back to the currently-resolved project config path
+ * (either `.ezmodo/config.json` or, for legacy checkouts, `.zephly/config.json`).
+ * Writes never relocate the file — use `ezmodo migrate-config` for that.
+ * @returns {Promise<boolean>} true if written successfully
+ */
+export async function writeConfig(config) {
+  const configPath = await findConfigPath();
+  if (!configPath) return false;
+  try {
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get cached tags if the cache is fresh.
+ * @returns {Promise<Array|null>} Cached tags array, or null if stale/missing
+ */
+export async function getCachedTags() {
+  const config = await readConfig();
+  if (!config) return null;
+  if (!isCacheFresh(config.lastUpdatedAt)) return null;
+  return config.tags || null;
+}
+
+/**
+ * Get cached components for a specific project if the cache is fresh.
+ * @param {string} projectId - Only return components if they match this project
+ * @returns {Promise<Array|null>} Cached components array, or null if stale/missing/wrong project
+ */
+export async function getCachedComponents(projectId) {
+  const config = await readConfig();
+  if (!config) return null;
+  if (!isCacheFresh(config.lastUpdatedAt)) return null;
+  // Only return if the cached config belongs to this project
+  if (config.projectId !== projectId) return null;
+  return config.components || null;
+}
+
+/**
+ * Update specific sections in the config cache. Non-fatal on failure.
+ * @param {object} updates - Key-value pairs to merge into config (e.g., { tags: [...], components: [...] })
+ */
+export async function updateCacheSections(updates) {
+  try {
+    const config = await readConfig();
+    if (!config) return;
+    Object.assign(config, updates);
+    await writeConfig(config);
+  } catch {
+    // Non-fatal — cache update failed, will refresh next time
+  }
+}
+
+/**
+ * Invalidate a specific cache section by removing it from config.
+ * The next read will return null, triggering a fresh API call.
+ * @param {string} section - 'tags' or 'components'
+ */
+export async function invalidateCacheSection(section) {
+  try {
+    const config = await readConfig();
+    if (!config) return;
+    delete config[section];
+    await writeConfig(config);
+  } catch {
+    // Non-fatal
+  }
+}

package/lib/logger.js

@@ -0,0 +1,109 @@
+/**
+ * MCP Server Logger - Structured JSON Lines logging to disk
+ *
+ * Writes to ~/.zephly/logs/zephly-YYYY-MM-DD.log
+ * Daily rotation, 7-day auto-cleanup on init
+ * Async fire-and-forget writes so logging never blocks tool execution
+ */
+
+import { mkdir, appendFile, readdir, unlink } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const RETENTION_DAYS = 7;
+const DATE_PATTERN = /^zephly-(\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`);
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.source='mcp']
+ * @param {boolean} [options.verbose=false]
+ * @param {string} [options.logsDir]
+ */
+export function createLogger(options = {}) {
+  const {
+    source = 'mcp',
+    verbose = false,
+    logsDir = join(homedir(), '.zephly', 'logs'),
+  } = options;
+
+  // Ensure logs directory exists (fire-and-forget)
+  let dirReady = mkdir(logsDir, { recursive: true }).catch(() => {});
+
+  function write(level, msg, data) {
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      source,
+      msg,
+      ...data,
+    };
+
+    // Fire-and-forget write — wait for dir, then append
+    dirReady.then(() => {
+      const filePath = getLogFilePath(logsDir);
+      return appendFile(filePath, JSON.stringify(entry) + '\n');
+    }).catch(() => {});
+
+    // stderr routing: warn/error always go to stderr; debug/info only if verbose
+    if (level === 'warn' || level === 'error') {
+      console.error(`[${source}] ${msg}`);
+    } else if (verbose) {
+      console.error(`[${source}] ${msg}`);
+    }
+  }
+
+  async function cleanup() {
+    try {
+      await dirReady;
+      const files = await readdir(logsDir);
+      const now = Date.now();
+      const maxAge = RETENTION_DAYS * 24 * 60 * 60 * 1000;
+
+      for (const file of files) {
+        const match = file.match(DATE_PATTERN);
+        if (!match) continue;
+
+        const fileDate = new Date(match[1]);
+        if (isNaN(fileDate.getTime())) continue;
+
+        if (now - fileDate.getTime() > maxAge) {
+          await unlink(join(logsDir, file)).catch(() => {});
+        }
+      }
+    } catch {
+      // Ignore cleanup failures
+    }
+  }
+
+  return {
+    debug: (msg, data) => write('debug', msg, data),
+    info: (msg, data) => write('info', msg, data),
+    warn: (msg, data) => write('warn', msg, data),
+    error: (msg, data) => write('error', msg, data),
+    cleanup,
+  };
+}
+
+// Singleton
+let _logger = null;
+
+export function initLogger(verbose = false, logsDir) {
+  _logger = createLogger({ source: 'mcp', verbose, logsDir });
+  _logger.cleanup();
+  return _logger;
+}
+
+export function getLogger() {
+  if (!_logger) {
+    _logger = createLogger({ source: 'mcp' });
+  }
+  return _logger;
+}

package/lib/manifest-loader.js

@@ -0,0 +1,182 @@
+/**
+ * Context Manifest Loader
+ * Loads and caches the project manifest/manifest.json file for MCP tools.
+ * Reads from `.ezmodo/manifest/` with a `.zephly/manifest/` fallback.
+ * Provides a singleton cache with reload mechanism for rebuild_manifest.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { findConfigPath, readConfig } from './local-cache.js';
+import { getLogger } from './logger.js';
+import {
+  CURRENT_REPO_CONFIG_DIR,
+  LEGACY_REPO_CONFIG_DIR,
+} from './repo-config-dir.js';
+
+// Singleton cache
+let _manifest = null;
+let _manifestPath = null;
+let _loadedAt = null;
+
+/**
+ * Find the project root by walking up from the resolved config.json path.
+ * Falls back to process.cwd() if config not found.
+ * @returns {Promise<string>} Absolute path to project root
+ */
+async function findProjectRoot() {
+  const configPath = await findConfigPath();
+  if (configPath) {
+    // <root>/<config-dir>/config.json → project root
+    return path.dirname(path.dirname(configPath));
+  }
+  return process.cwd();
+}
+
+/**
+ * Find the manifest.json file path. Probes `.ezmodo/manifest/manifest.json`
+ * first, then legacy `.zephly/manifest/manifest.json`.
+ * @returns {Promise<string|null>} Absolute path to manifest.json, or null
+ */
+async function findManifestPath() {
+  if (_manifestPath) {
+    try {
+      await fs.access(_manifestPath);
+      return _manifestPath;
+    } catch {
+      _manifestPath = null;
+    }
+  }
+
+  const projectRoot = await findProjectRoot();
+  for (const dirName of [CURRENT_REPO_CONFIG_DIR, LEGACY_REPO_CONFIG_DIR]) {
+    const manifestPath = path.join(projectRoot, dirName, 'manifest', 'manifest.json');
+    try {
+      await fs.access(manifestPath);
+      _manifestPath = manifestPath;
+      return manifestPath;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Load and parse the context manifest.
+ * Uses singleton cache — subsequent calls return cached version.
+ * Call reloadManifest() to force a refresh.
+ *
+ * @returns {Promise<object|null>} Parsed manifest object, or null if not found/invalid
+ */
+export async function loadManifest() {
+  if (_manifest) return _manifest;
+
+  const manifestPath = await findManifestPath();
+  if (!manifestPath) return null;
+
+  try {
+    const content = await fs.readFile(manifestPath, 'utf-8');
+    _manifest = JSON.parse(content);
+    _loadedAt = new Date().toISOString();
+    return _manifest;
+  } catch (err) {
+    getLogger().warn('Failed to load context manifest', { error: err.message });
+    return null;
+  }
+}
+
+/**
+ * Force reload the manifest from disk.
+ * Clears the singleton cache and reloads.
+ *
+ * @returns {Promise<object|null>} Freshly loaded manifest, or null
+ */
+export async function reloadManifest() {
+  _manifest = null;
+  _manifestPath = null;
+  _loadedAt = null;
+  return loadManifest();
+}
+
+/**
+ * Save the in-memory manifest back to disk.
+ * Updates metadata.entryCount and writes to the same path it was loaded from.
+ *
+ * @returns {Promise<boolean>} true if saved successfully
+ */
+export async function saveManifest() {
+  if (!_manifest || !_manifestPath) return false;
+
+  try {
+    _manifest.metadata.entryCount = _manifest.entries.length;
+    await fs.writeFile(_manifestPath, JSON.stringify(_manifest, null, 2) + '\n', 'utf-8');
+    return true;
+  } catch (err) {
+    getLogger().warn('Failed to save context manifest', { error: err.message });
+    return false;
+  }
+}
+
+/**
+ * Get metadata about the current manifest cache state.
+ * @returns {object} Cache info including loadedAt timestamp and entry count
+ */
+export function getManifestCacheInfo() {
+  return {
+    loaded: _manifest !== null,
+    loadedAt: _loadedAt,
+    entryCount: _manifest?.metadata?.entryCount || 0,
+    version: _manifest?.metadata?.version || null,
+    generatedAt: _manifest?.metadata?.generatedAt || null,
+    manifestPath: _manifestPath,
+  };
+}
+
+/**
+ * Check if a local manifest file is available on the filesystem.
+ * @returns {Promise<boolean>}
+ */
+export async function isLocalManifestAvailable() {
+  if (_manifest) return true;
+  const manifestPath = await findManifestPath();
+  return manifestPath !== null;
+}
+
+/**
+ * Determine the manifest data source: local filesystem or remote API.
+ * Returns { source: 'local', manifest } or { source: 'remote', projectId }.
+ *
+ * The local manifest describes the working tree it sits in, and therefore
+ * answers for exactly ONE project: the one in this repo's config.json. When a
+ * caller names a DIFFERENT project it must go remote — an agent working in repo
+ * A can legitimately ask for context in project B, and serving A's files as B's
+ * context is worse than serving none: the answer looks authoritative and is
+ * entirely about the wrong codebase.
+ *
+ * @param {string} [projectIdOverride] - Optional explicit projectId (from tool args)
+ * @returns {Promise<{source: 'local', manifest: object} | {source: 'remote', projectId: string}>}
+ */
+export async function getManifestSource(projectIdOverride) {
+  const localProjectId = (await readConfig())?.projectId;
+  const localAnswersForRequest = !projectIdOverride || projectIdOverride === localProjectId;
+
+  if (localAnswersForRequest) {
+    const localManifest = await loadManifest();
+    if (localManifest) {
+      return { source: 'local', manifest: localManifest };
+    }
+  }
+
+  // No usable local manifest — need a projectId for remote.
+  const projectId = projectIdOverride || localProjectId;
+  if (projectId) {
+    return { source: 'remote', projectId };
+  }
+
+  throw new Error(
+    'No local manifest found and no project configured for remote access. ' +
+    'Either run "npm run manifest:regen" to generate .context/manifest.json locally, ' +
+    'or run initialize_project_context to configure a project for remote API access.'
+  );
+}