@idea-base/mcp-server 1.0.3 → 1.2.0

package/README.md

@@ -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.0.3",
+  "version": "1.2.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

@@ -66,7 +66,7 @@ const tools = [
   },
   {
     name: 'create_project',
-    description: 'Create a new project. Returns the created project with its ID.',
+    description: 'Create a new project. A TOP-LEVEL project requires product_id; a sub-project (parent_project_id set) inherits its parent\'s product. Returns the created project with its ID.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -80,7 +80,11 @@ const tools = [
         },
         parent_project_id: {
           type: 'number',
-          description: 'Parent project ID if this is a sub-project',
+          description: 'Parent project ID if this is a sub-project (inherits the parent\'s product)',
+        },
+        product_id: {
+          type: 'number',
+          description: 'Product this project belongs to. Required for a top-level project (no parent); omit for a sub-project. Find ids via list_products.',
         },
       },
       required: ['name'],
@@ -342,7 +346,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: {
@@ -350,10 +354,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',
@@ -385,7 +474,7 @@ const tools = [
   },
   {
     name: 'create_product',
-    description: 'Create a new product. Products are top-level containers that can have multiple projects linked to them.',
+    description: 'Create a new product. Products are top-level containers for projects. Every product belongs to a customer (customer_id is required) — use an internal/own-company customer for internal work. Find customer ids via list_products (each shows its customer_id).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -401,8 +490,12 @@ const tools = [
           type: 'string',
           description: 'GitHub repository URL for the product',
         },
+        customer_id: {
+          type: 'number',
+          description: 'Customer this product is for. REQUIRED — every product belongs to a customer.',
+        },
       },
-      required: ['name'],
+      required: ['name', 'customer_id'],
     },
   },
   {
@@ -449,13 +542,14 @@ const toolHandlers = {
     };
   },
 
-  async create_project({ name, description, parent_project_id }) {
+  async create_project({ name, description, parent_project_id, product_id }) {
     const project = await apiRequest('/projects', {
       method: 'POST',
       body: JSON.stringify({
         name,
         description,
         parent_project_id,
+        product_id,
       }),
     });
     return {
@@ -668,26 +762,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.`,
         },
       ],
     };
@@ -721,13 +905,14 @@ const toolHandlers = {
     };
   },
 
-  async create_product({ name, description, github_repo_url }) {
+  async create_product({ name, description, github_repo_url, customer_id }) {
     const product = await apiRequest('/products', {
       method: 'POST',
       body: JSON.stringify({
         name,
         description,
         github_repo_url,
+        customer_id,
       }),
     });
     return {