@idea-base/mcp-server 1.1.0 → 1.3.0

package/README.md

@@ -72,12 +72,12 @@ Ask Claude to manage your projects:
 
 | Tool | Description |
 |------|-------------|
-| `list_tasks` | List tasks for a project (filter by status) |
+| `list_tasks` | List tasks for a project (filter by status). Compact rows by default (`verbose:true` for full rows) |
 | `get_task` | Get task details, acceptance criteria, and time entries |
-| `create_task` | Create a task with title, description, estimate |
-| `update_task` | Update task details |
-| `update_task_status` | Change task status (todo/in_progress/done) |
-| `search_tasks` | Search tasks across all projects |
+| `create_task` | Create a task with title, description, estimate, priority, start/due dates, assignee; `parent_task_id` makes it a subtask |
+| `update_task` | Update task details, priority, start/due dates, assignee; `blocked_by: [ids]` replaces its dependencies |
+| `update_task_status` | Change task status (todo/in_progress/blocked/done) |
+| `search_tasks` | Search tasks across all projects, ranked title-first then description then recency. Compact rows by default; filter by `project_id`/`product_id`/`customer_id`/`status`; `verbose:true` for full rows |
 | `quick_log` | Create + complete + log time in one step |
 
 ### Time Tracking
@@ -85,8 +85,18 @@ Ask Claude to manage your projects:
 | Tool | Description |
 |------|-------------|
 | `log_time` | Log time against a task with notes |
-| `start_working` | Mark yourself as actively working on a task |
-| `stop_working` | Stop active work on a task |
+| `start_working` | Mark yourself as actively working on a task (surfaces the saved resume context + recent work notes so a cold session re-orients) |
+| `stop_working` | Stop active work on a task (optionally capture a `note` and/or `resume_context` on the way out) |
+
+### Activity & Audit Trail
+
+For AI agents, these leave a durable trail of *what was done and why* on each task — so a future session (or a human reviewer) can see the reasoning, not just the final state.
+
+| Tool | Description |
+|------|-------------|
+| `add_work_note` | Append a timestamped progress note to a task's activity log (append-only journal) |
+| `add_comment` | Add a comment to a task's discussion thread (customer-visible by default) |
+| `set_resume_context` | Overwrite the task's pinned "where I left off" block, read first on `start_working` |
 
 ### Products
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idea-base/mcp-server",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP Server for IDEA Base - AI-powered project management. Integrates with Claude Code, Cursor, and Windsurf.",
   "main": "src/index.js",
   "type": "module",
@@ -37,14 +37,14 @@
     "url": "https://github.com/IDEAManagement/idea-base-mcp/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "files": [
-    "src/",
+    "src/index.js",
     "README.md",
     "LICENSE"
   ]

package/src/index.js

@@ -15,33 +15,244 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
-// Configuration from environment
-const API_BASE_URL = process.env.IDEA_BASE_API_URL || 'https://app.idea-base.us/api';
-const API_KEY = process.env.IDEA_BASE_API_KEY;
+// ---------------------------------------------------------------------------
+// Configuration
+//
+// The API key comes from the environment and nowhere else: it is never a tool
+// argument, never logged, and never allowed into an error message or a tool
+// result (see redact() below). The base URL is a constant unless the operator
+// deliberately overrides it, and an override must still be https.
+// ---------------------------------------------------------------------------
+const DEFAULT_API_BASE_URL = 'https://app.idea-base.us/api';
+
+function resolveBaseUrl() {
+  const override = (process.env.IDEA_BASE_API_URL || '').trim();
+  if (!override) return DEFAULT_API_BASE_URL;
+
+  let parsed;
+  try {
+    parsed = new URL(override);
+  } catch {
+    console.error('Error: IDEA_BASE_API_URL is not a valid URL');
+    process.exit(1);
+  }
+  if (parsed.protocol !== 'https:') {
+    console.error('Error: IDEA_BASE_API_URL must use https');
+    process.exit(1);
+  }
+  if (parsed.username || parsed.password) {
+    console.error('Error: IDEA_BASE_API_URL must not embed credentials');
+    process.exit(1);
+  }
+  // Announce a non-default host once at startup so a poisoned environment is
+  // visible in the client log rather than silently exfiltrating the API key.
+  console.error(`IDEA Base MCP: API host overridden to ${parsed.host} via IDEA_BASE_API_URL`);
+  return override.replace(/\/+$/, '');
+}
+
+const API_BASE_URL = resolveBaseUrl();
+const API_KEY = (process.env.IDEA_BASE_API_KEY || '').trim();
 
 if (!API_KEY) {
   console.error('Error: IDEA_BASE_API_KEY environment variable is required');
   process.exit(1);
 }
 
-// API helper function
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_CHARS = 300;
+
+// Belt-and-braces: nothing we emit should ever contain the key, but a stray
+// stack frame or an echoing upstream must not be the thing that proves it.
+function redact(text) {
+  if (typeof text !== 'string') return '';
+  return API_KEY ? text.split(API_KEY).join('[redacted]') : text;
+}
+
+// ---------------------------------------------------------------------------
+// Argument validation
+//
+// Tool arguments arrive from a model and must never be able to steer the host
+// or the path. Every argument is checked against the tool's own inputSchema
+// before a handler runs: unknown keys are dropped, ids must be positive
+// integers, enums must match, strings are length-capped.
+// ---------------------------------------------------------------------------
+const MAX_STRING_LEN = 20000;
+const STRING_LIMITS = { query: 500, date: 32, start_date: 32, due_date: 32 };
+
+function validateArgs(toolName, schema, rawArgs) {
+  const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {};
+  const props = schema?.properties || {};
+  const clean = {};
+
+  for (const name of schema?.required || []) {
+    if (args[name] === undefined || args[name] === null || args[name] === '') {
+      throw new Error(`${toolName}: "${name}" is required`);
+    }
+  }
+
+  for (const [name, value] of Object.entries(args)) {
+    const spec = props[name];
+    if (!spec) continue; // drop anything the tool does not declare
+    if (value === undefined || value === null) continue;
+    clean[name] = coerce(toolName, name, spec, value);
+  }
+
+  return clean;
+}
+
+function coerce(toolName, name, spec, value) {
+  const label = `${toolName}: "${name}"`;
+
+  if (spec.type === 'number' || spec.type === 'integer') {
+    const n = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(n)) throw new Error(`${label} must be a number`);
+    if (name === 'id' || name.endsWith('_id')) {
+      if (!Number.isInteger(n) || n <= 0 || n > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`${label} must be a positive integer id`);
+      }
+    }
+    return n;
+  }
+
+  if (spec.type === 'boolean') return Boolean(value);
+
+  if (spec.type === 'array') {
+    if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+    if (value.length > 500) throw new Error(`${label} has too many entries (max 500)`);
+    return value.map((item, i) => coerce(toolName, `${name}[${i}]`, spec.items || {}, item));
+  }
+
+  // string (and anything unspecified)
+  const str = typeof value === 'string' ? value : String(value);
+  if (spec.enum && !spec.enum.includes(str)) {
+    throw new Error(`${label} must be one of: ${spec.enum.join(', ')}`);
+  }
+  const max = STRING_LIMITS[name] ?? MAX_STRING_LEN;
+  if (str.length > max) throw new Error(`${label} is too long (max ${max} characters)`);
+  return str;
+}
+
+// ---------------------------------------------------------------------------
+// API helper
+// ---------------------------------------------------------------------------
+async function readCapped(response) {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    throw new Error('API response exceeded the 5 MB size cap');
+  }
+  const reader = response.body?.getReader?.();
+  if (!reader) return '';
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw new Error('API response exceeded the 5 MB size cap');
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// The API serves an HTML shell for some unknown paths. Never let that body
+// reach the model — report the shape of what came back instead.
+function parseJsonBody(text, response) {
+  const contentType = (response.headers.get('content-type') || '').split(';')[0].trim();
+  if (!contentType.includes('json')) {
+    throw new Error(
+      `API returned ${response.status} as ${contentType || 'an unknown content type'} rather than JSON` +
+      ' (the endpoint may not exist)'
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`API returned ${response.status} with a malformed JSON body`);
+  }
+}
+
 async function apiRequest(endpoint, options = {}) {
   const url = `${API_BASE_URL}${endpoint}`;
-  const response = await fetch(url, {
-    ...options,
-    headers: {
-      'Authorization': `Bearer ${API_KEY}`,
-      'Content-Type': 'application/json',
-      ...options.headers,
-    },
-  });
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  let response;
+  try {
+    response = await fetch(url, {
+      ...options,
+      // A redirect could carry the Authorization header somewhere else. There
+      // is no legitimate redirect on this API, so refuse rather than follow.
+      redirect: 'error',
+      signal: controller.signal,
+      headers: {
+        'Authorization': `Bearer ${API_KEY}`,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        ...options.headers,
+      },
+    });
+  } catch (error) {
+    clearTimeout(timer);
+    if (error?.name === 'AbortError') {
+      throw new Error(`API request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);
+    }
+    throw new Error(`API request failed: ${redact(error?.message || 'network error')}`);
+  }
+
+  let text;
+  try {
+    text = await readCapped(response);
+  } finally {
+    clearTimeout(timer);
+  }
 
   if (!response.ok) {
-    const error = await response.json().catch(() => ({ error: response.statusText }));
-    throw new Error(error.error || `API error: ${response.status}`);
+    let message = `API error: ${response.status}`;
+    const contentType = (response.headers.get('content-type') || '');
+    if (contentType.includes('json')) {
+      try {
+        const body = JSON.parse(text);
+        if (typeof body?.error === 'string' && body.error) {
+          message = body.error.slice(0, MAX_ERROR_CHARS);
+        }
+      } catch {
+        // fall through to the generic status message
+      }
+    }
+    throw new Error(redact(message));
   }
 
-  return response.json();
+  return parseJsonBody(text, response);
+}
+
+// Build a short description snippet (first ~160 chars) for compact task rows
+// returned by list_tasks when the API response doesn't already provide one
+// (i.e. the plain /projects/:id/tasks endpoint, which is not the compacted
+// tasks/search endpoint).
+function snippetFor(description, maxLen = 160) {
+  if (!description) return '';
+  const trimmed = description.trim();
+  if (trimmed.length <= maxLen) return trimmed;
+  return trimmed.slice(0, maxLen).trim() + '…';
+}
+
+// Reduce a full task row (as returned by /projects/:id/tasks) down to the
+// compact shape used by list_tasks when verbose is not requested.
+function compactifyTask(task) {
+  return {
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    estimated_minutes: task.estimated_minutes,
+    time_spent: task.time_spent,
+    due_date: task.due_date,
+    snippet: snippetFor(task.description),
+  };
 }
 
 // Define available tools
@@ -133,7 +344,7 @@ const tools = [
   },
   {
     name: 'list_tasks',
-    description: 'List all tasks for a specific project. Returns task titles, status, estimates, and time logged.',
+    description: 'List all tasks for a specific project. Returns compact rows (id, title, status, priority, estimated_minutes, time_spent, due_date, snippet) by default to keep payloads small; pass verbose:true for full rows including description, acceptance_criteria, tags, and assignments.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -143,8 +354,12 @@ const tools = [
         },
         status: {
           type: 'string',
-          enum: ['todo', 'in_progress', 'done'],
-          description: 'Filter by task status. Omit for all tasks.',
+          enum: ['todo', 'in_progress', 'blocked', 'done'],
+          description: 'Filter by task status. Omit for all tasks. Note this filters the STORED status; a task can also be showing as blocked because of an unmet dependency (see effective_status on each row).',
+        },
+        verbose: {
+          type: 'boolean',
+          description: 'Return full task rows (description, acceptance_criteria, tags, assignments) instead of compact rows. Default false.',
         },
       },
       required: ['project_id'],
@@ -194,6 +409,22 @@ const tools = [
           type: 'number',
           description: 'Priority level (0-5, higher is more important)',
         },
+        start_date: {
+          type: 'string',
+          description: 'Date work is planned to start, as YYYY-MM-DD.',
+        },
+        due_date: {
+          type: 'string',
+          description: 'Date the task is due, as YYYY-MM-DD.',
+        },
+        assignee_user_id: {
+          type: 'string',
+          description: 'User ID to assign the task to. Must be a member of the same account. Omit to leave the task unassigned.',
+        },
+        parent_task_id: {
+          type: 'number',
+          description: 'Make this a SUBTASK of the given task. The parent must be in the same project, and a subtask cannot itself have subtasks (one level only). A parent with subtasks takes its status from them: any subtask in progress makes the parent in progress, and all subtasks done makes it ready to complete.',
+        },
       },
       required: ['project_id', 'title'],
     },
@@ -226,7 +457,28 @@ const tools = [
         },
         priority: {
           type: 'number',
-          description: 'New priority level',
+          description: 'New priority level (0-5, higher is more important)',
+        },
+        start_date: {
+          type: 'string',
+          description: 'New start date as YYYY-MM-DD. Pass an empty string to clear it.',
+        },
+        due_date: {
+          type: 'string',
+          description: 'New due date as YYYY-MM-DD. Pass an empty string to clear it.',
+        },
+        assignee_user_id: {
+          type: 'string',
+          description: 'User ID to assign the task to, replacing any existing assignee. Must be a member of the same account. Pass an empty string to unassign.',
+        },
+        blocked_by: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'REPLACES the full set of tasks this task is blocked by. Pass [] to clear all of them. Every id must be a task in the same product; a circular chain (A blocked by B blocked by A) is rejected. While any of these is not done, the task shows as blocked whatever its stored status says.',
+        },
+        blocked_reason: {
+          type: 'string',
+          description: 'Free-text reason shown next to a manually-set Blocked status ("waiting on the client"). Cleared automatically when the task leaves the blocked status.',
         },
       },
       required: ['task_id'],
@@ -234,7 +486,7 @@ const tools = [
   },
   {
     name: 'update_task_status',
-    description: 'Change the status of a task (todo, in_progress, done). This triggers a real-time notification to users viewing the project.',
+    description: 'Change the status of a task (todo, in_progress, blocked, done). This triggers a real-time notification to users viewing the project. Note that a task with subtasks or dependencies also has a DERIVED status which can differ from the one set here — see effective_status / status_reason on get_task.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -244,8 +496,12 @@ const tools = [
         },
         status: {
           type: 'string',
-          enum: ['todo', 'in_progress', 'done'],
-          description: 'New status for the task',
+          enum: ['todo', 'in_progress', 'blocked', 'done'],
+          description: 'New status for the task. "ready_to_complete" is NOT settable — it is derived when every subtask is done.',
+        },
+        blocked_reason: {
+          type: 'string',
+          description: 'Why the task is blocked. Only meaningful with status "blocked"; cleared automatically on any other status.',
         },
       },
       required: ['task_id', 'status'],
@@ -279,7 +535,7 @@ const tools = [
   },
   {
     name: 'search_tasks',
-    description: 'Search for tasks across all projects by title or description.',
+    description: 'Search for tasks across all projects by title or description. Returns compact rows (id, title, status, priority, project_id, project_name, product_name, customer_name, estimated_minutes, time_logged, due_date, snippet) ranked with title matches first, then description matches, then recency. Pass verbose:true for full rows.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -289,9 +545,29 @@ const tools = [
         },
         status: {
           type: 'string',
-          enum: ['todo', 'in_progress', 'done'],
+          enum: ['todo', 'in_progress', 'blocked', 'done'],
           description: 'Filter results by status',
         },
+        project_id: {
+          type: 'number',
+          description: 'Restrict results to this project',
+        },
+        product_id: {
+          type: 'number',
+          description: 'Restrict results to this product',
+        },
+        customer_id: {
+          type: 'number',
+          description: 'Restrict results to this customer',
+        },
+        verbose: {
+          type: 'boolean',
+          description: 'Return full task rows instead of compact rows. Default false.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results to return. Default 20, capped at 100.',
+        },
       },
       required: ['query'],
     },
@@ -346,7 +622,7 @@ const tools = [
   },
   {
     name: 'stop_working',
-    description: 'Mark that you have stopped working on a task. Use this when taking a break or switching to another task.',
+    description: 'Mark that you have stopped working on a task (break or switching tasks). Optionally capture your state on the way out: pass `note` to append a work note and/or `resume_context` to overwrite the resume block, so the next session can pick up where you left off. Both are recorded as author_kind="ai".',
     inputSchema: {
       type: 'object',
       properties: {
@@ -354,10 +630,95 @@ const tools = [
           type: 'number',
           description: 'The ID of the task to stop working on',
         },
+        note: {
+          type: 'string',
+          description: 'Optional work note to append before stopping (what you did, what is next).',
+        },
+        resume_context: {
+          type: 'string',
+          description: 'Optional resume-context block to overwrite before stopping (current state / next steps / where to look).',
+        },
       },
       required: ['task_id'],
     },
   },
+  {
+    name: 'add_work_note',
+    description: 'Append a timestamped work note (status update) to a task\'s activity log. Use this to record progress so a future session can pick up where you left off (e.g. "finished auth handler, tests green, next: wire the callback"). Notes are append-only and never overwrite each other. Set author_kind="human" ONLY when you are relaying a note dictated by the human user; use "ai" (the default) when leaving your own status update.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to add a work note to',
+        },
+        note: {
+          type: 'string',
+          description: 'The work note / status update text',
+        },
+        author_kind: {
+          type: 'string',
+          enum: ['ai', 'human'],
+          description: 'Who authored this note: "ai" (default, your own update) or "human" (you are relaying something the user said).',
+        },
+        is_internal: {
+          type: 'boolean',
+          description: 'Whether the note is internal-only (hidden from customers). Defaults to true for work notes.',
+        },
+      },
+      required: ['task_id', 'note'],
+    },
+  },
+  {
+    name: 'add_comment',
+    description: 'Add a comment to a task\'s discussion thread. Unlike work notes (progress journal), comments are for communication and are customer-visible by default. Set author_kind="human" when relaying the user\'s words; use "ai" (default) for your own.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to comment on',
+        },
+        comment: {
+          type: 'string',
+          description: 'The comment text',
+        },
+        author_kind: {
+          type: 'string',
+          enum: ['ai', 'human'],
+          description: 'Who authored this comment: "ai" (default) or "human" (relaying the user).',
+        },
+        is_internal: {
+          type: 'boolean',
+          description: 'Whether the comment is internal-only (hidden from customers). Defaults to false.',
+        },
+      },
+      required: ['task_id', 'comment'],
+    },
+  },
+  {
+    name: 'set_resume_context',
+    description: 'Set (overwrite) the task\'s resume context — a single pinned block describing the current state, what is done, what is next, and where to look. This is read first when a work session restarts cold (e.g. via start_working) so you can re-orient immediately. Update it at the end of a work session. Set author_kind="human" only when relaying the user\'s words; default "ai".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to set resume context for',
+        },
+        context: {
+          type: 'string',
+          description: 'The resume-context text (markdown ok): current state / next steps / where to look.',
+        },
+        author_kind: {
+          type: 'string',
+          enum: ['ai', 'human'],
+          description: 'Who authored this context: "ai" (default) or "human".',
+        },
+      },
+      required: ['task_id', 'context'],
+    },
+  },
   // Products tools
   {
     name: 'list_products',
@@ -509,16 +870,17 @@ const toolHandlers = {
     };
   },
 
-  async list_tasks({ project_id, status }) {
+  async list_tasks({ project_id, status, verbose }) {
     let endpoint = `/projects/${project_id}/tasks`;
-    if (status) endpoint += `?status=${status}`;
+    if (status) endpoint += `?status=${encodeURIComponent(status)}`;
 
     const tasks = await apiRequest(endpoint);
+    const result = verbose ? tasks : (Array.isArray(tasks) ? tasks.map(compactifyTask) : tasks);
     return {
       content: [
         {
           type: 'text',
-          text: JSON.stringify(tasks, null, 2),
+          text: JSON.stringify(result, null, 2),
         },
       ],
     };
@@ -536,7 +898,7 @@ const toolHandlers = {
     };
   },
 
-  async create_task({ project_id, title, description, acceptance_criteria, estimated_minutes, priority }) {
+  async create_task({ project_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, parent_task_id }) {
     const task = await apiRequest(`/projects/${project_id}/tasks`, {
       method: 'POST',
       body: JSON.stringify({
@@ -545,6 +907,10 @@ const toolHandlers = {
         acceptance_criteria,
         estimated_minutes,
         priority,
+        start_date,
+        due_date,
+        assignee_user_id,
+        parent_task_id,
       }),
     });
     return {
@@ -557,13 +923,22 @@ const toolHandlers = {
     };
   },
 
-  async update_task({ task_id, title, description, acceptance_criteria, estimated_minutes, priority }) {
+  async update_task({ task_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, blocked_by, blocked_reason }) {
+    // Only forward what the caller actually named. An absent key leaves the
+    // field alone; an explicitly empty string is how a date or the assignee is
+    // cleared, and blocked_by is a REPLACE so an explicit [] must reach the
+    // API — which is why these are `!== undefined` rather than truthiness.
     const updates = {};
     if (title !== undefined) updates.title = title;
     if (description !== undefined) updates.description = description;
     if (acceptance_criteria !== undefined) updates.acceptance_criteria = acceptance_criteria;
     if (estimated_minutes !== undefined) updates.estimated_minutes = estimated_minutes;
     if (priority !== undefined) updates.priority = priority;
+    if (start_date !== undefined) updates.start_date = start_date;
+    if (due_date !== undefined) updates.due_date = due_date;
+    if (assignee_user_id !== undefined) updates.assignee_user_id = assignee_user_id;
+    if (blocked_by !== undefined) updates.blocked_by = blocked_by;
+    if (blocked_reason !== undefined) updates.blocked_reason = blocked_reason;
 
     const task = await apiRequest(`/tasks/${task_id}`, {
       method: 'PUT',
@@ -579,10 +954,10 @@ const toolHandlers = {
     };
   },
 
-  async update_task_status({ task_id, status }) {
+  async update_task_status({ task_id, status, blocked_reason }) {
     const task = await apiRequest(`/tasks/${task_id}/status`, {
       method: 'PUT',
-      body: JSON.stringify({ status }),
+      body: JSON.stringify({ status, blocked_reason }),
     });
     return {
       content: [
@@ -613,9 +988,14 @@ const toolHandlers = {
     };
   },
 
-  async search_tasks({ query, status }) {
+  async search_tasks({ query, status, project_id, product_id, customer_id, verbose, limit }) {
     let endpoint = `/tasks/search?q=${encodeURIComponent(query)}`;
-    if (status) endpoint += `&status=${status}`;
+    if (status) endpoint += `&status=${encodeURIComponent(status)}`;
+    if (project_id) endpoint += `&project_id=${encodeURIComponent(project_id)}`;
+    if (product_id) endpoint += `&product_id=${encodeURIComponent(product_id)}`;
+    if (customer_id) endpoint += `&customer_id=${encodeURIComponent(customer_id)}`;
+    if (verbose) endpoint += `&verbose=1`;
+    if (limit) endpoint += `&limit=${encodeURIComponent(limit)}`;
 
     const tasks = await apiRequest(endpoint);
     return {
@@ -677,26 +1057,116 @@ const toolHandlers = {
       body: JSON.stringify({ is_active: true }),
     });
 
+    // Orient a cold-starting session: surface the resume context + recent work notes.
+    let orientation = '';
+    try {
+      const task = await apiRequest(`/tasks/${task_id}`);
+      const lines = [];
+      if (task.resume_context) {
+        const by = task.resume_context_author_kind === 'ai' ? 'AI Agent' : 'human';
+        lines.push(`\n--- Resume context (last set by ${by}) ---\n${task.resume_context}`);
+      }
+      const notes = task.recent_work_notes || [];
+      if (notes.length) {
+        lines.push('\n--- Recent work notes (newest first) ---');
+        for (const n of notes) {
+          let text = '';
+          try { text = JSON.parse(n.event_data || '{}').note || ''; } catch {}
+          const who = n.author_kind === 'ai' ? 'AI' : (n.author_name || 'human');
+          lines.push(`• [${n.created_at}] (${who}) ${text}`);
+        }
+      }
+      if (lines.length) {
+        orientation = `\n\nHere is where you left off:\n${lines.join('\n')}`;
+      } else {
+        orientation = `\n\nNo resume context or work notes yet — consider leaving some with add_work_note / set_resume_context before you stop.`;
+      }
+    } catch {
+      // Non-fatal: assignment already succeeded.
+    }
+
     return {
       content: [
         {
           type: 'text',
-          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.`,
+          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.${orientation}`,
         },
       ],
     };
   },
 
-  async stop_working({ task_id }) {
+  async stop_working({ task_id, note, resume_context }) {
+    const captured = [];
+    if (note && note.trim()) {
+      await apiRequest(`/tasks/${task_id}/activity`, {
+        method: 'POST',
+        body: JSON.stringify({ note, author_kind: 'ai', is_internal: true }),
+      });
+      captured.push('work note');
+    }
+    if (resume_context !== undefined && resume_context !== null) {
+      await apiRequest(`/tasks/${task_id}`, {
+        method: 'PUT',
+        body: JSON.stringify({ resume_context, resume_context_author_kind: 'ai' }),
+      });
+      captured.push('resume context');
+    }
+
     await apiRequest(`/tasks/${task_id}/assignments?stop_only=true`, {
       method: 'DELETE',
     });
 
+    const capturedText = captured.length ? ` Saved ${captured.join(' and ')} for next time.` : '';
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Stopped working on task #${task_id}. You are still assigned to the task but no longer marked as actively working.${capturedText}`,
+        },
+      ],
+    };
+  },
+
+  async add_work_note({ task_id, note, author_kind = 'ai', is_internal = true }) {
+    const saved = await apiRequest(`/tasks/${task_id}/activity`, {
+      method: 'POST',
+      body: JSON.stringify({ note, author_kind, is_internal }),
+    });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Work note added to task #${task_id} (as ${author_kind === 'ai' ? 'AI Agent' : 'human'}). Note id: ${saved.id}.`,
+        },
+      ],
+    };
+  },
+
+  async add_comment({ task_id, comment, author_kind = 'ai', is_internal = false }) {
+    const saved = await apiRequest(`/tasks/${task_id}/comments`, {
+      method: 'POST',
+      body: JSON.stringify({ comment, author_kind, is_internal }),
+    });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Comment added to task #${task_id} (as ${author_kind === 'ai' ? 'AI Agent' : 'human'}). Comment id: ${saved.id}.`,
+        },
+      ],
+    };
+  },
+
+  async set_resume_context({ task_id, context, author_kind = 'ai' }) {
+    await apiRequest(`/tasks/${task_id}`, {
+      method: 'PUT',
+      body: JSON.stringify({ resume_context: context, resume_context_author_kind: author_kind }),
+    });
     return {
       content: [
         {
           type: 'text',
-          text: `Stopped working on task #${task_id}. You are still assigned to the task but no longer marked as actively working.`,
+          text: `Resume context updated for task #${task_id} (as ${author_kind === 'ai' ? 'AI Agent' : 'human'}). The next session that calls start_working will read this first.`,
         },
       ],
     };
@@ -705,7 +1175,7 @@ const toolHandlers = {
   // Products handlers
   async list_products({ status }) {
     let endpoint = '/products';
-    if (status) endpoint += `?status=${status}`;
+    if (status) endpoint += `?status=${encodeURIComponent(status)}`;
 
     const products = await apiRequest(endpoint);
     return {
@@ -792,18 +1262,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
   const handler = toolHandlers[name];
-  if (!handler) {
+  const tool = tools.find((t) => t.name === name);
+  if (!handler || !tool) {
     throw new Error(`Unknown tool: ${name}`);
   }
 
   try {
-    return await handler(args);
+    const safeArgs = validateArgs(name, tool.inputSchema, args);
+    return await handler(safeArgs);
   } catch (error) {
     return {
       content: [
         {
           type: 'text',
-          text: `Error: ${error.message}`,
+          text: `Error: ${redact(error?.message || 'unknown error')}`,
         },
       ],
       isError: true,
@@ -819,6 +1291,6 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error('Fatal error:', error);
+  console.error(`Fatal error: ${redact(error?.message || 'unknown error')}`);
   process.exit(1);
 });