@idea-base/mcp-server 2.2.0 → 2.4.0

package/README.md

@@ -66,7 +66,15 @@ 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 |
+| `list_sprints` | List a product's sprints with real task counts and its cadence |
+| `get_sprint` | One sprint: tasks, counts, commitment ledger; optionally candidates + blocked work |
+| `create_sprint` | Open a sprint — next on the cadence, or an explicit window |
+| `add_tasks_to_sprint` | Commit tasks (refuses a task already in another sprint) |
+| `remove_tasks_from_sprint` | Take tasks out of a sprint |
+| `close_sprint` | Close it; unfinished work carries forward. Irreversible |
+| `get_sprint_cadence` | Read a product's sprint rhythm |
+| `set_sprint_cadence` | Set length, start weekday, carry-over, auto-open |
 
 ### Tasks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idea-base/mcp-server",
-  "version": "2.2.0",
+  "version": "2.4.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));
@@ -232,7 +254,12 @@ async function apiRequest(endpoint, options = {}) {
       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
@@ -327,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: {
@@ -348,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'],
     },
@@ -908,6 +943,108 @@ const tools = [
       },
     },
   },
+  {
+    name: 'list_sprints',
+    description: 'List a product\'s sprints, newest first, with real task counts and its cadence. Sprints are owned by the PRODUCT: the product sets the rhythm and owns the lifecycle, while projects add and remove the work. A sprint can hold tasks from any project under that product, sub-projects included.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        product_id: { type: 'number', description: 'The product whose sprints to list. Find ids via list_products.' },
+      },
+      required: ['product_id'],
+    },
+  },
+  {
+    name: 'get_sprint',
+    description: 'Get one sprint: its tasks with derived status, counts taken from real task rows, and — for a CLOSED sprint — the commitment ledger saying what it committed to and what became of each item. Pass candidates:true to also get the open work that could be pulled in, and the work being held back as blocked (with the reason).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sprint_id: { type: 'number', description: 'The sprint to retrieve' },
+        candidates: { type: 'boolean', description: 'Also return work eligible to be added, and blocked work held out of it. Default false.' },
+      },
+      required: ['sprint_id'],
+    },
+  },
+  {
+    name: 'create_sprint',
+    description: 'Open a sprint on a product. With no dates it opens the NEXT one on the product\'s cadence, which is the normal case; pass starts_on/ends_on only to set an explicit window. One sprint per product per period — a second for the same period is refused rather than duplicated.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        product_id: { type: 'number', description: 'The product to open the sprint on' },
+        name: { type: 'string', description: 'Optional. Defaults to its date range.' },
+        goal: { type: 'string', description: 'What this sprint is meant to achieve' },
+        starts_on: { type: 'string', description: 'YYYY-MM-DD. Omit to follow the cadence.' },
+        ends_on: { type: 'string', description: 'YYYY-MM-DD. Omit to run one cadence length from starts_on.' },
+        state: { type: 'string', enum: ['planned', 'active'], description: 'Default planned. A sprint cannot be created closed.' },
+      },
+      required: ['product_id'],
+    },
+  },
+  {
+    name: 'add_tasks_to_sprint',
+    description: 'Commit tasks to a sprint. Each task is checked on its own and the result says which were added and which were refused and why — a task already in another sprint is REFUSED, not moved, because a task belongs to at most one. Tasks must belong to a project under the sprint\'s product.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sprint_id: { type: 'number', description: 'The sprint to add to' },
+        task_ids: { type: 'array', items: { type: 'number' }, description: 'Task ids to commit (max 100)' },
+      },
+      required: ['sprint_id', 'task_ids'],
+    },
+  },
+  {
+    name: 'remove_tasks_from_sprint',
+    description: 'Take tasks out of a sprint. The tasks themselves are untouched — the sprint is the time box, not the owner of the work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sprint_id: { type: 'number', description: 'The sprint to remove from' },
+        task_ids: { type: 'array', items: { type: 'number' }, description: 'Task ids to remove (max 100)' },
+      },
+      required: ['sprint_id', 'task_ids'],
+    },
+  },
+  {
+    name: 'close_sprint',
+    description: 'Close a sprint. Unfinished work moves into the next sprint and its carry count increments (unless the product\'s cadence has carry-over off, in which case it is released); finished work stays attached. Every task held is written to the commitment ledger first, so what the sprint committed to survives the carry. This is an action, not a status edit — closing is irreversible.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sprint_id: { type: 'number', description: 'The sprint to close' },
+        carry_to_sprint_id: { type: 'number', description: 'Optional explicit destination for unfinished work. Must be an open sprint in the same product; otherwise the next sprint is used or opened.' },
+      },
+      required: ['sprint_id'],
+    },
+  },
+  {
+    name: 'get_sprint_cadence',
+    description: 'Get a product\'s sprint rhythm: length in days, which weekday it starts, whether unfinished work carries over, and whether sprints open unattended. A product with no cadence row still reports the weekly-Monday default, flagged as not configured.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        product_id: { type: 'number', description: 'The product whose cadence to read' },
+      },
+      required: ['product_id'],
+    },
+  },
+  {
+    name: 'set_sprint_cadence',
+    description: 'Set a product\'s sprint rhythm. "Mon-Sun weekly" is length_days 7 + start_weekday 1; a Wednesday fortnight is 14 + 3. Changing it does not move sprints that already exist — it applies from the next sprint opened. Setting a cadence is also what opts a product into having sprints opened and closed on the schedule.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        product_id: { type: 'number', description: 'The product to configure' },
+        length_days: { type: 'number', description: 'Sprint length in days, 1-90. Default 7.' },
+        start_weekday: { type: 'number', description: '0 = Sunday through 6 = Saturday. Default 1 (Monday). Only decides the FIRST sprint; later ones follow the previous sprint\'s end.' },
+        carry_over_unfinished: { type: 'boolean', description: 'Move unfinished work into the next sprint on close. Default true.' },
+        auto_create: { type: 'boolean', description: 'Open the next sprint unattended on the schedule. Default true.' },
+        enabled: { type: 'boolean', description: 'Whether the schedule touches this product at all. Default true.' },
+      },
+      required: ['product_id'],
+    },
+  },
   {
     name: 'get_product',
     description: 'Get details of a specific product including linked projects, team members, and statistics.',
@@ -1012,11 +1149,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',
@@ -1581,6 +1725,69 @@ const toolHandlers = {
     };
   },
 
+  async list_sprints({ product_id }) {
+    const data = await apiRequest(`/products/${product_id}/sprints`);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async get_sprint({ sprint_id, candidates }) {
+    const data = await apiRequest(`/sprints/${sprint_id}${candidates ? '?candidates=1' : ''}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async create_sprint({ product_id, name, goal, starts_on, ends_on, state }) {
+    const data = await apiRequest(`/products/${product_id}/sprints`, {
+      method: 'POST',
+      body: JSON.stringify({ name, goal, starts_on, ends_on, state }),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async add_tasks_to_sprint({ sprint_id, task_ids }) {
+    const data = await apiRequest(`/sprints/${sprint_id}/tasks`, {
+      method: 'POST',
+      body: JSON.stringify({ task_ids }),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async remove_tasks_from_sprint({ sprint_id, task_ids }) {
+    const data = await apiRequest(`/sprints/${sprint_id}/tasks`, {
+      method: 'DELETE',
+      body: JSON.stringify({ task_ids }),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async close_sprint({ sprint_id, carry_to_sprint_id }) {
+    const data = await apiRequest(`/sprints/${sprint_id}/close`, {
+      method: 'POST',
+      body: JSON.stringify({ carry_to_sprint_id }),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async get_sprint_cadence({ product_id }) {
+    const data = await apiRequest(`/products/${product_id}/sprint-cadence`);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
+  async set_sprint_cadence({ product_id, length_days, start_weekday, carry_over_unfinished, auto_create, enabled }) {
+    const body = {};
+    // Forwarded on `!== undefined` so an omitted field keeps its current value
+    // rather than being reset to a default the caller never asked for.
+    if (length_days !== undefined) body.length_days = length_days;
+    if (start_weekday !== undefined) body.start_weekday = start_weekday;
+    if (carry_over_unfinished !== undefined) body.carry_over_unfinished = carry_over_unfinished;
+    if (auto_create !== undefined) body.auto_create = auto_create;
+    if (enabled !== undefined) body.enabled = enabled;
+    const data = await apiRequest(`/products/${product_id}/sprint-cadence`, {
+      method: 'PUT',
+      body: JSON.stringify(body),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  },
+
   async get_product({ product_id }) {
     const product = await apiRequest(`/products/${product_id}`);
     return {