@idea-base/mcp-server 2.1.0 → 2.3.0

package/README.md

@@ -66,7 +66,7 @@ Ask Claude to manage your projects:
 | `list_projects` | List all projects with task counts and progress |
 | `get_project` | Get project details and statistics |
 | `create_project` | Create a new project or sub-project |
-| `update_project` | Update project name, description, or status |
+| `update_project` | Update a project name, description, status, parent (re-parent, or `null` to detach) or product |
 
 ### Tasks
 
@@ -85,8 +85,24 @@ 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 (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) |
+| `start_working` | Open a timed work session on a task, and mark yourself actively working (surfaces the saved resume context + recent work notes so a cold session re-orients). Calling it twice never opens a second session — it resumes or reports the one you have |
+| `pause_working` | Pause the open session without ending it, with a required `reason` |
+| `resume_working` | Close the pause and carry on in the same session |
+| `stop_working` | Close the session with a UTC end instant and drop the active flag (optionally capture a `note` and/or `resume_context` on the way out). Fails if you have no open session |
+
+**Sessions are measured, and the pause reason decides the number.** `start_working`
+records a UTC start instant, `stop_working` a UTC end instant, and each pause in
+between records both its boundaries plus why work stopped:
+
+| `reason` | Effect on worked time |
+|---|---|
+| `waiting_on_human` | **Excluded.** A person has to act before you can continue |
+| `waiting_on_agent` | **Counted.** A sub-agent blocked on another *active* sub-agent is still working |
+| `other` | Counted |
+
+Only waiting on the human is not working. Use `pause_working` rather than
+`stop_working` whenever you intend to carry on — `stop_working` ends the session
+and the reason is lost.
 
 ### Activity & Audit Trail
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idea-base/mcp-server",
-  "version": "2.1.0",
+  "version": "2.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",

package/src/index.js

@@ -93,6 +93,18 @@ function redact(text) {
 const MAX_STRING_LEN = 20000;
 const STRING_LIMITS = { query: 500, date: 32, start_date: 32, due_date: 32 };
 
+// A schema type may be a UNION, e.g. ['number', 'null'] — the only way to say
+// "a number, or null meaning clear this". Both the null handling in
+// validateArgs and coerce's branch selection have to read that union rather
+// than compare `spec.type` with ===, or a nullable field silently behaves as a
+// string field and its null never reaches the handler at all.
+const typesOf = (spec) => {
+  const t = spec?.type;
+  return Array.isArray(t) ? t : (t ? [t] : []);
+};
+const allowsNull = (spec) => typesOf(spec).includes('null');
+const primaryType = (spec) => typesOf(spec).find((t) => t !== 'null');
+
 function validateArgs(toolName, schema, rawArgs) {
   const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {};
   const props = schema?.properties || {};
@@ -107,7 +119,16 @@ function validateArgs(toolName, schema, rawArgs) {
   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;
+    if (value === undefined) continue;
+    if (value === null) {
+      // null is dropped unless the tool DECLARES it meaningful. For
+      // update_project.parent_project_id it means "detach this project", and
+      // this unconditional drop is why un-parenting stayed impossible through
+      // this server: the field reached here and vanished, so the request body
+      // came out empty and the API answered "No fields to update".
+      if (allowsNull(spec)) clean[name] = null;
+      continue;
+    }
     clean[name] = coerce(toolName, name, spec, value);
   }
 
@@ -116,8 +137,9 @@ function validateArgs(toolName, schema, rawArgs) {
 
 function coerce(toolName, name, spec, value) {
   const label = `${toolName}: "${name}"`;
+  const type = primaryType(spec);
 
-  if (spec.type === 'number' || spec.type === 'integer') {
+  if (type === 'number' || 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')) {
@@ -128,9 +150,9 @@ function coerce(toolName, name, spec, value) {
     return n;
   }
 
-  if (spec.type === 'boolean') return Boolean(value);
+  if (type === 'boolean') return Boolean(value);
 
-  if (spec.type === 'array') {
+  if (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));
@@ -226,18 +248,33 @@ async function apiRequest(endpoint, options = {}) {
 
   if (!response.ok) {
     let message = `API error: ${response.status}`;
+    let code = null;
     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);
+          // `error` is the headline and `details` is what to do about it — a
+          // plan-limit or product-inheritance refusal is not actionable without
+          // the second half, which used to be dropped here.
+          const parts = [body.error];
+          if (typeof body?.details === 'string' && body.details) parts.push(body.details);
+          message = parts.join(' — ').slice(0, MAX_ERROR_CHARS);
         }
+        // Machine-readable discriminator, when the endpoint supplies one. A
+        // handler needs to tell "you have no open session" (a real answer the
+        // caller must see) apart from "that endpoint is not deployed yet"
+        // (an infrastructure fact it should degrade around), and string-matching
+        // a prose error message to decide that is how quiet bugs get written.
+        if (typeof body?.code === 'string' && body.code) code = body.code;
       } catch {
         // fall through to the generic status message
       }
     }
-    throw new Error(redact(message));
+    const error = new Error(redact(message));
+    error.status = response.status;
+    if (code) error.code = code;
+    throw error;
   }
 
   return parseJsonBody(text, response);
@@ -317,7 +354,7 @@ const tools = [
   },
   {
     name: 'update_project',
-    description: 'Update project details like name, description, or status.',
+    description: 'Update a project: its name, description, status, or where it sits in the hierarchy. Omitted fields are left exactly as they are. Set parent_project_id to re-parent the project, or to null to DETACH it into a top-level project; a detached project keeps the product it had inherited, so product_id is only needed to move it to a DIFFERENT product. A sub-project inherits its parent\'s product, so re-parenting under a parent in a different product moves the project there too. The API refuses a move that is circular, crosses accounts, or exceeds the plan\'s nesting depth or sub-project count, and says which.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -338,6 +375,14 @@ const tools = [
           enum: ['active', 'completed', 'archived'],
           description: 'New status for the project',
         },
+        parent_project_id: {
+          type: ['number', 'null'],
+          description: 'Move the project under this parent. Pass null to detach it and make it top-level — it keeps whatever product it had, so no product_id is needed unless you also want to move it. Omit to leave the parent unchanged.',
+        },
+        product_id: {
+          type: 'number',
+          description: 'Move the project to this product. Only valid for a project with no parent — a sub-project cannot hold a product of its own, it inherits its parent\'s. Find ids via list_products.',
+        },
       },
       required: ['project_id'],
     },
@@ -750,7 +795,7 @@ const tools = [
   },
   {
     name: 'start_working',
-    description: 'Mark that you are actively working on a task. This shows other team members that the task is being worked on and by whom.',
+    description: 'Start work on a task. Two things happen: you are shown to the team as actively working on it (and a todo task moves to in_progress), and a TIMED WORK SESSION is opened with a UTC start instant, so how long the task was actually worked becomes measurable instead of guessed.\n\nCalling it a second time on the same task NEVER opens a second session. If your session is paused it is resumed; if it is already running you are told so, with how long it has been going. The response always says which of the three happened.\n\nIt also orients a cold session: the response carries the task\'s resume context and its recent work notes, so read the whole thing before you start. Pair it with stop_working, and use pause_working when you have to wait on something.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -764,7 +809,7 @@ const tools = [
   },
   {
     name: 'stop_working',
-    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.',
+    description: 'Stop working on a task: close your open work session with a UTC end instant, and drop the "actively working" flag (you stay assigned). The closed session is what makes the task\'s worked duration reportable.\n\nRequires an open session — if you have none this FAILS and writes nothing, rather than inventing a session with no start. Call start_working first.\n\nThis ENDS the session. If you are only waiting on something and intend to carry on afterwards, use pause_working instead: a pause keeps the session open and records why you stopped, which is what decides whether the interval counts as worked time.\n\nOptionally 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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -784,6 +829,43 @@ const tools = [
       required: ['task_id'],
     },
   },
+  {
+    name: 'pause_working',
+    description: 'Pause your open work session without ending it, and record WHY. Use this whenever work stops but is not finished — you asked the human a question, you are waiting on another agent, you are blocked on a build.\n\nTHE REASON IS THE POINT, and it decides the number:\n  waiting_on_human — you are blocked on a person and CANNOT proceed. The paused interval is EXCLUDED from worked time.\n  waiting_on_agent — you are blocked on another agent or an automated run that is itself active. The interval IS COUNTED as worked time: a sub-agent blocked on another active sub-agent is still working.\n  other — anything else. Counted as worked.\n\nOnly waiting on the human is not working. Choose waiting_on_human ONLY when a person has to act before you can continue; if a machine or another agent is doing the work, it is waiting_on_agent.\n\nResume with resume_working. Do NOT use stop_working for a pause — that ends the session and the reason is lost.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task whose session to pause',
+        },
+        reason: {
+          type: 'string',
+          enum: ['waiting_on_human', 'waiting_on_agent', 'other'],
+          description: 'Why work stopped. waiting_on_human EXCLUDES this interval from worked time; waiting_on_agent and other INCLUDE it. Required — there is no default, because the whole worked-time figure turns on this value.',
+        },
+        detail: {
+          type: 'string',
+          description: 'Optional free text: what specifically you are waiting on (e.g. "asked whether to merge PR #280").',
+        },
+      },
+      required: ['task_id', 'reason'],
+    },
+  },
+  {
+    name: 'resume_working',
+    description: 'Resume your paused work session — closes the pause by recording the UTC instant you came back, so the paused interval has both boundaries and can be measured. The session itself was never closed and keeps its original start.\n\nFails if the session is not paused, rather than pretending to resume something. start_working also resumes a paused session, so use whichever reads better; this one does not re-fetch the orientation block.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task whose session to resume',
+        },
+      },
+      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.',
@@ -965,11 +1047,18 @@ const toolHandlers = {
     };
   },
 
-  async update_project({ project_id, name, description, status }) {
+  async update_project({ project_id, name, description, status, parent_project_id, product_id }) {
     const updates = {};
     if (name !== undefined) updates.name = name;
     if (description !== undefined) updates.description = description;
     if (status !== undefined) updates.status = status;
+    // These two are forwarded on `!== undefined`, never on truthiness: null is
+    // the MEANINGFUL value for parent_project_id (it detaches the project), and
+    // PUT /api/projects/:id only writes a column it was actually sent — so an
+    // omitted key leaves parent and product exactly as they were, and a
+    // name-only update can never silently detach anything.
+    if (parent_project_id !== undefined) updates.parent_project_id = parent_project_id;
+    if (product_id !== undefined) updates.product_id = product_id;
 
     const project = await apiRequest(`/projects/${project_id}`, {
       method: 'PUT',
@@ -1293,11 +1382,36 @@ const toolHandlers = {
   },
 
   async start_working({ task_id }) {
+    // Presence first, and unchanged: this is what writes the `started_working`
+    // task_events row and promotes a todo task to in_progress. The timed session
+    // below sits ALONGSIDE that audit trail, it does not replace it.
     await apiRequest(`/tasks/${task_id}/assignments`, {
       method: 'POST',
       body: JSON.stringify({ is_active: true }),
     });
 
+    // Open (or resume, or report) the work session. Non-fatal by design: the
+    // presence write already succeeded, and a session failure must not make
+    // start_working look like it did nothing.
+    let timing = '';
+    try {
+      const result = await apiRequest(`/tasks/${task_id}/work-session`, {
+        method: 'POST',
+        body: JSON.stringify({}),
+      });
+      const s = result.session || {};
+      if (result.action === 'resumed') {
+        const p = result.resumed_pause || {};
+        timing = `\n\nResumed work session #${s.id}, open since ${s.started_at} — the ${p.reason} pause that began at ${p.paused_at} is now closed. No second session was opened.`;
+      } else if (result.action === 'already_running') {
+        timing = `\n\nWork session #${s.id} was ALREADY running (started ${s.started_at}, ${s.worked_minutes} min worked so far). No second session was opened.`;
+      } else {
+        timing = `\n\nWork session #${s.id} opened at ${s.started_at} (UTC). Close it with stop_working; if you have to wait on something, use pause_working so the reason is recorded.`;
+      }
+    } catch (error) {
+      timing = `\n\n(Work session NOT recorded: ${error.message} — your presence flag is set, but no duration will be measured for this stretch.)`;
+    }
+
     // Orient a cold-starting session: surface the resume context + recent work notes.
     let orientation = '';
     try {
@@ -1330,7 +1444,7 @@ const toolHandlers = {
       content: [
         {
           type: 'text',
-          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.${orientation}`,
+          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.${timing}${orientation}`,
         },
       ],
     };
@@ -1353,6 +1467,42 @@ const toolHandlers = {
       captured.push('resume context');
     }
 
+    // Close the session BEFORE dropping presence, so a task with no open
+    // session fails here and nothing at all is changed.
+    //
+    // A missing session is a real answer, not an infrastructure hiccup: it means
+    // the caller believes it was timing work that was never timed. Report it and
+    // stop, rather than writing a session row with no start or silently clearing
+    // the flag as if a duration had been recorded. Any OTHER session failure
+    // (the endpoint being unreachable, say) must not strand the presence flag,
+    // so that one is reported and the stop continues.
+    let timing = '';
+    let sessionError = null;
+    try {
+      const result = await apiRequest(`/tasks/${task_id}/work-session`, {
+        method: 'DELETE',
+        body: JSON.stringify({ state: 'completed' }),
+      });
+      const s = result.session || {};
+      const paused = Number(s.paused_minutes || 0);
+      const pausedText = paused > 0
+        ? ` (${s.elapsed_minutes} min elapsed, ${paused} min of that paused)`
+        : '';
+      timing = ` Work session #${s.id} closed at ${s.ended_at} — ${s.worked_minutes} minutes worked${pausedText}.`;
+    } catch (error) {
+      sessionError = error;
+    }
+
+    if (sessionError?.code === 'NO_OPEN_SESSION') {
+      throw new Error(
+        `${sessionError.message} Nothing was changed: no session row was written and ` +
+        'your active-work flag was left as it was.'
+      );
+    }
+    if (sessionError) {
+      timing = ` (Work session NOT closed: ${sessionError.message})`;
+    }
+
     await apiRequest(`/tasks/${task_id}/assignments?stop_only=true`, {
       method: 'DELETE',
     });
@@ -1362,7 +1512,51 @@ const toolHandlers = {
       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}`,
+          text: `Stopped working on task #${task_id}. You are still assigned to the task but no longer marked as actively working.${timing}${capturedText}`,
+        },
+      ],
+    };
+  },
+
+  async pause_working({ task_id, reason, detail }) {
+    const result = await apiRequest(`/tasks/${task_id}/work-session/pause`, {
+      method: 'POST',
+      body: JSON.stringify({ reason, note: detail }),
+    });
+    const p = result.pause || {};
+    const s = result.session || {};
+    const counted = result.counts_as_worked
+      ? 'This interval WILL count as worked time.'
+      : 'This interval will NOT count as worked time.';
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Paused work session #${s.id} on task #${task_id} at ${p.paused_at} (reason: ${reason}). ` +
+            `${counted} ${s.worked_minutes} minutes worked so far. ` +
+            'The session is still open — call resume_working when you are back.',
+        },
+      ],
+    };
+  },
+
+  async resume_working({ task_id }) {
+    const result = await apiRequest(`/tasks/${task_id}/work-session/resume`, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+    const p = result.resumed_pause || {};
+    const s = result.session || {};
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Resumed work session #${s.id} on task #${task_id} at ${p.resumed_at}. ` +
+            `The ${p.reason} pause ran ${p.minutes} minutes and ` +
+            `${p.counts_as_worked ? 'COUNTS as worked time' : 'is EXCLUDED from worked time'}. ` +
+            `${s.worked_minutes} minutes worked on this session so far.`,
         },
       ],
     };