@idea-base/mcp-server 1.2.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idea-base/mcp-server",
-  "version": "1.2.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'],
     },
@@ -594,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),
         },
       ],
     };
@@ -621,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({
@@ -630,6 +907,10 @@ const toolHandlers = {
         acceptance_criteria,
         estimated_minutes,
         priority,
+        start_date,
+        due_date,
+        assignee_user_id,
+        parent_task_id,
       }),
     });
     return {
@@ -642,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',
@@ -664,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: [
@@ -698,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 {
@@ -880,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 {
@@ -967,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,
@@ -994,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);
 });