@intangle/mcp-server 2.5.5 → 2.6.0

package/tool-definitions.ts

@@ -1,10 +1,10 @@
 // Tools definition - matches the stdio server
-export const TOOLS = [
+const TOOL_DEFINITIONS = [
   {
     name: "search",
     title: "Search Space",
     description:
-      "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Use fetch tool to get full content for specific IDs when needed.",
+      "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Default to one search per question, then use fetch_items for full details instead of repeating paraphrased searches.",
     inputSchema: {
       type: "object",
       properties: {
@@ -49,55 +49,409 @@ export const TOOLS = [
       }
     }
   },
-  // PROJECTS DISABLED - Projects have been disabled. May be re-enabled later.
-  // {
-  //   name: "view_projects",
-  //   title: "View Projects",
-  //   description:
-  //     "List all projects in a space. Projects are user-created canvases that organize context, tasks, documents, and skills. Use this to discover available projects before viewing their contents.",
-  //   inputSchema: {
-  //     type: "object",
-  //     properties: {
-  //       space_id: {
-  //         type: "string",
-  //         description:
-  //           "REQUIRED: Space to list projects from (use view_spaces to see available options)"
-  //       }
-  //     },
-  //     required: ["space_id"]
-  //   }
-  // },
-  // {
-  //   name: "view_project",
-  //   title: "View Project",
-  //   description:
-  //     "View a specific project with all its items (context, tasks, documents, skills). Returns item metadata (IDs, titles, types, status) for each item in the project. Use fetch_items to get full content of specific items.",
-  //   inputSchema: {
-  //     type: "object",
-  //     properties: {
-  //       project_id: {
-  //         type: "string",
-  //         description:
-  //           "Project ID to view (e.g., 'proj_123...'). Get project IDs from view_projects."
-  //       },
-  //       space_id: {
-  //         type: "string",
-  //         description:
-  //           "Optional: Space ID (required if using slug instead of project_id)"
-  //       },
-  //       slug: {
-  //         type: "string",
-  //         description:
-  //           "Optional: Project slug (URL-friendly name). Requires space_id if used."
-  //       }
-  //     }
-  //   }
-  // },
+  {
+    name: "fetch_conversation_messages",
+    title: "Fetch Conversation Messages",
+    description:
+      "Read persisted messages from a conversation/chat summary. Useful for polling shared threads after async `message` calls or when multiple participants are collaborating in the same conversation. Returns stable message IDs and timestamps so callers can dedupe and continue from `next_cursor`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space containing the conversation (use view_spaces first)."
+        },
+        conversation_id: {
+          type: "string",
+          description:
+            "REQUIRED: Chat summary / conversation ID to read (e.g. 'summary_123...')."
+        },
+        organization_id: {
+          type: "string",
+          description:
+            "Optional Clerk org ID when the space belongs to an organization graph."
+        },
+        since_timestamp: {
+          type: "integer",
+          description:
+            "Optional millisecond cursor. Only messages newer than this timestamp are returned."
+        },
+        limit: {
+          type: "integer",
+          description:
+            "Optional page size from 1 to 200 (default 50)."
+        }
+      },
+      required: ["space_id", "conversation_id"]
+    }
+  },
+  {
+    name: "subscribe_conversation",
+    title: "Subscribe Conversation",
+    description:
+      "Register a participant in a shared conversation so it can use inbox and read-cursor tools without first sending a message. By default the subscription starts caught up at the latest message.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space containing the conversation (use view_spaces first)."
+        },
+        conversation_id: {
+          type: "string",
+          description:
+            "REQUIRED: Chat summary / conversation ID to subscribe to."
+        },
+        organization_id: {
+          type: "string",
+          description:
+            "Optional Clerk org ID when the space belongs to an organization graph."
+        },
+        participant_id: {
+          type: "string",
+          description:
+            "Optional stable participant ID. Use an explicit `user_*` or `agent_*` style ID when you want the same participant identity reused across calls."
+        },
+        participant_type: {
+          type: "string",
+          description:
+            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+        },
+        participant_label: {
+          type: "string",
+          description:
+            "Optional display label for the participant in collaborative chat UIs."
+        },
+        mark_read: {
+          type: "boolean",
+          description:
+            "Optional. Defaults to true. When true, the subscription starts caught up at the current latest message."
+        }
+      },
+      required: ["space_id", "conversation_id"]
+    }
+  },
+  {
+    name: "list_conversation_inbox",
+    title: "List Conversation Inbox",
+    description:
+      "List the conversations a participant is subscribed to in one space, with unread counts and read cursors. Use this to poll multiple shared threads efficiently.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to list inbox conversations from (use view_spaces first)."
+        },
+        organization_id: {
+          type: "string",
+          description:
+            "Optional Clerk org ID when the space belongs to an organization graph."
+        },
+        participant_id: {
+          type: "string",
+          description:
+            "Optional stable participant ID. Use the same value you used for message/subscribe calls to read the same inbox."
+        },
+        participant_type: {
+          type: "string",
+          description:
+            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+        },
+        participant_label: {
+          type: "string",
+          description:
+            "Optional display label used when the participant identity is being created for the first time."
+        },
+        unread_only: {
+          type: "boolean",
+          description:
+            "Optional. When true, only return conversations that currently have unread messages."
+        },
+        since_timestamp: {
+          type: "integer",
+          description:
+            "Optional millisecond cursor. Only conversations updated after this timestamp are returned."
+        },
+        limit: {
+          type: "integer",
+          description:
+            "Optional page size from 1 to 200 (default 50)."
+        }
+      },
+      required: ["space_id"]
+    }
+  },
+  {
+    name: "mark_conversation_read",
+    title: "Mark Conversation Read",
+    description:
+      "Advance a participant's read cursor for a shared conversation. Use this after processing messages returned from fetch_conversation_messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space containing the conversation (use view_spaces first)."
+        },
+        conversation_id: {
+          type: "string",
+          description:
+            "REQUIRED: Chat summary / conversation ID to mark as read."
+        },
+        organization_id: {
+          type: "string",
+          description:
+            "Optional Clerk org ID when the space belongs to an organization graph."
+        },
+        participant_id: {
+          type: "string",
+          description:
+            "Optional stable participant ID. Use the same value you used for message/subscribe calls."
+        },
+        participant_type: {
+          type: "string",
+          description:
+            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+        },
+        participant_label: {
+          type: "string",
+          description:
+            "Optional display label used when the participant identity is being created for the first time."
+        },
+        read_at: {
+          type: "integer",
+          description:
+            "Optional millisecond cursor to advance to. If omitted, the conversation is marked read through its latest message."
+        }
+      },
+      required: ["space_id", "conversation_id"]
+    }
+  },
+  {
+    name: "view_groups",
+    title: "View Groups",
+    description:
+      "List all groups in a space, including the projects currently inside each group plus any ungrouped projects.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to list groups from (use view_spaces to see available options)"
+        }
+      },
+      required: ["space_id"]
+    }
+  },
+  {
+    name: "create_group",
+    title: "Create Group",
+    description: "Create a new group inside a space.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to create the group in."
+        },
+        name: {
+          type: "string",
+          description: "Name for the new group."
+        }
+      },
+      required: ["space_id", "name"]
+    }
+  },
+  {
+    name: "rename_group",
+    title: "Rename Group",
+    description: "Rename an existing group.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space containing the group."
+        },
+        group_id: {
+          type: "string",
+          description: "REQUIRED: Group ID to rename."
+        },
+        name: {
+          type: "string",
+          description: "REQUIRED: New group name."
+        }
+      },
+      required: ["space_id", "group_id", "name"]
+    }
+  },
+  {
+    name: "delete_group",
+    title: "Delete Group",
+    description:
+      "Delete a group. Projects inside it are preserved and become ungrouped.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space containing the group."
+        },
+        group_id: {
+          type: "string",
+          description: "REQUIRED: Group ID to delete."
+        }
+      },
+      required: ["space_id", "group_id"]
+    }
+  },
+  {
+    name: "view_projects",
+    title: "View Projects",
+    description:
+      "List all projects in a space, including which group each project belongs to.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to list projects from (use view_spaces to see available options)"
+        }
+      },
+      required: ["space_id"]
+    }
+  },
+  {
+    name: "view_project",
+    title: "View Project",
+    description:
+      "View a specific project with all its items. Use fetch_items to retrieve full content for specific item IDs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description:
+            "Project ID to view (e.g., 'proj_123...'). Get project IDs from view_projects."
+        },
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space containing the project."
+        },
+        slug: {
+          type: "string",
+          description:
+            "Optional: Project slug (URL-friendly name)."
+        }
+      },
+      required: ["space_id"]
+    }
+  },
+  {
+    name: "create_project",
+    title: "Create Project",
+    description:
+      "Create a new project in a space. Optionally place it inside a group immediately.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space to create the project in."
+        },
+        name: {
+          type: "string",
+          description: "REQUIRED: Project name."
+        },
+        group_id: {
+          type: "string",
+          description: "Optional: Group ID to place the project inside."
+        }
+      },
+      required: ["space_id", "name"]
+    }
+  },
+  {
+    name: "rename_project",
+    title: "Rename Project",
+    description: "Rename an existing project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space containing the project."
+        },
+        project_id: {
+          type: "string",
+          description: "REQUIRED: Project ID to rename."
+        },
+        name: {
+          type: "string",
+          description: "REQUIRED: New project name."
+        }
+      },
+      required: ["space_id", "project_id", "name"]
+    }
+  },
+  {
+    name: "delete_project",
+    title: "Delete Project",
+    description: "Delete an existing project from a space.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space containing the project."
+        },
+        project_id: {
+          type: "string",
+          description: "REQUIRED: Project ID to delete."
+        }
+      },
+      required: ["space_id", "project_id"]
+    }
+  },
+  {
+    name: "assign_project_to_group",
+    title: "Assign Project To Group",
+    description:
+      "Move a project into a group. Omit group_id to make the project ungrouped.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description: "REQUIRED: Space containing the project."
+        },
+        project_id: {
+          type: "string",
+          description: "REQUIRED: Project ID to move."
+        },
+        group_id: {
+          type: "string",
+          description:
+            "Optional: Target group ID. Omit this to ungroup the project."
+        }
+      },
+      required: ["space_id", "project_id"]
+    }
+  },
   {
     name: "start",
     title: "Start Space Session",
     description:
-      "Begin working in a space. Returns a dynamic briefing including: recent developments, current priorities, active tasks, user preferences for this space, and learned insights about how the user/org works. Use this context to personalize your assistance and anticipate needs.",
+      "Load a space fast for a new external caller. Returns assistant-curated current items, useful insights, skills, recent conversations, and assistant preferences so the caller can get oriented quickly and fetch deeper details only when needed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -171,7 +525,7 @@ export const TOOLS = [
     name: "update_memory",
     title: "Update Memory",
     description:
-      "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
+      "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nIMPORTANT: Include at least one operation: add, update, or delete.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
     inputSchema: {
       type: "object",
       properties: {
@@ -203,9 +557,9 @@ export const TOOLS = [
                   },
                   type: {
                     type: "string",
-                    enum: ["task", "context", "skill", "document"],
+                    enum: ["task", "context", "skill", "document", "insight"],
                     description:
-                      "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material. Omitting this triggers expensive auto-classification."
+                      "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material, 'insight' for durable patterns/principles. Omitting this triggers expensive auto-classification."
                   },
                   subtasks: {
                     type: "array",
@@ -339,14 +693,122 @@ export const TOOLS = [
           }
         }
       },
-      required: ["space_id"]
+      required: ["space_id"],
+      anyOf: [{ required: ["add"] }, { required: ["update"] }, { required: ["delete"] }]
+    }
+  },
+  {
+    name: "update_folders",
+    title: "Update Folders",
+    description:
+      "Unified folder management. Supports list, create, rename, move_items, and delete operations in one call so external MCP callers can organize memory the same way as the in-app assistant.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to operate in (use view_spaces to see available options)."
+        },
+        list: {
+          type: "object",
+          description:
+            "Optional list operation. Use this first to discover existing folders and IDs.",
+          properties: {
+            section_type: {
+              type: "string",
+              enum: [
+                "projects",
+                "insights",
+                "insights_space",
+                "insights_user",
+                "agents",
+                "skills",
+                "conversations",
+                "dashboard"
+              ],
+              description: "Optional: filter folders by sidebar section."
+            }
+          }
+        },
+        create: {
+          type: "array",
+          description: "Optional create operations.",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Folder name." },
+              section_type: {
+                type: "string",
+                enum: [
+                  "projects",
+                  "insights",
+                  "insights_space",
+                  "insights_user",
+                  "agents",
+                  "skills",
+                  "conversations",
+                  "dashboard"
+                ],
+                description: "Sidebar section this folder belongs to."
+              },
+              parent_id: {
+                type: "string",
+                description: "Optional parent folder ID for nesting."
+              }
+            },
+            required: ["name", "section_type"]
+          }
+        },
+        rename: {
+          type: "array",
+          description: "Optional rename operations.",
+          items: {
+            type: "object",
+            properties: {
+              folder_id: { type: "string", description: "Folder ID to rename." },
+              new_name: { type: "string", description: "New folder name." }
+            },
+            required: ["folder_id", "new_name"]
+          }
+        },
+        move_items: {
+          type: "array",
+          description:
+            "Optional item move operations. Set folder_id to null to move an item back to root.",
+          items: {
+            type: "object",
+            properties: {
+              item_id: { type: "string", description: "Item ID to move." },
+              folder_id: {
+                type: ["string", "null"],
+                description: "Target folder ID, or null to remove from folder."
+              }
+            },
+            required: ["item_id", "folder_id"]
+          }
+        },
+        delete: {
+          type: "array",
+          description: "Optional delete operations (folder IDs).",
+          items: { type: "string" }
+        }
+      },
+      required: ["space_id"],
+      anyOf: [
+        { required: ["list"] },
+        { required: ["create"] },
+        { required: ["rename"] },
+        { required: ["move_items"] },
+        { required: ["delete"] }
+      ]
     }
   },
   {
     name: "message",
     title: "Message Assistant",
     description:
-      "Primary orchestration tool. Send a request to the Intangle assistant and wait for one assistant turn to complete. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
+      "Primary orchestration tool. Send a request to the Intangle assistant and either wait for one assistant turn to complete or submit asynchronously for later polling. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
     inputSchema: {
       type: "object",
       properties: {
@@ -387,6 +849,26 @@ export const TOOLS = [
           description:
             "Optional timeout in milliseconds (10,000 to 300,000; default 120,000)."
         },
+        wait_for_response: {
+          type: "boolean",
+          description:
+            "Optional. Defaults to true. Set false to submit the turn asynchronously and poll the conversation later with fetch_conversation_messages."
+        },
+        participant_id: {
+          type: "string",
+          description:
+            "Optional stable participant ID for collaborative/shared chats. Use an explicit `user_*` or `agent_*` style ID when you want the same participant identity reused across calls."
+        },
+        participant_type: {
+          type: "string",
+          description:
+            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+        },
+        participant_label: {
+          type: "string",
+          description:
+            "Optional display label for the participant in collaborative chat UIs."
+        },
         timezone: {
           type: "string",
           description: "Optional IANA timezone for assistant context."
@@ -396,7 +878,7 @@ export const TOOLS = [
     }
   }
   // DISABLED: memory_action tool is broken and causing errors.
-  // Pending OHM protocol fix. Use update_space, search, or fetch_items instead.
+  // Pending OHM protocol fix. Use update_memory, search, or fetch_items instead.
   // {
   //   name: "memory_action",
   //   title: "Memory Action (OHM Protocol)",
@@ -419,3 +901,39 @@ export const TOOLS = [
   //   }
   // }
 ]
+
+const READ_ONLY_TOOLS = new Set([
+  "search",
+  "fetch_items",
+  "fetch_conversation_messages",
+  "list_conversation_inbox",
+  "start",
+  "view_spaces",
+  "view_space"
+])
+
+const DESTRUCTIVE_TOOLS = new Set([
+  "create_space",
+  "update_memory",
+  "update_folders"
+])
+
+const IDEMPOTENT_TOOLS = new Set([
+  "search",
+  "fetch_items",
+  "fetch_conversation_messages",
+  "list_conversation_inbox",
+  "start",
+  "view_spaces",
+  "view_space"
+])
+
+export const TOOLS = TOOL_DEFINITIONS.map((tool) => ({
+  ...tool,
+  annotations: {
+    ...(READ_ONLY_TOOLS.has(tool.name) ? { readOnlyHint: true } : {}),
+    ...(DESTRUCTIVE_TOOLS.has(tool.name) ? { destructiveHint: true } : {}),
+    ...(IDEMPOTENT_TOOLS.has(tool.name) ? { idempotentHint: true } : {}),
+    openWorldHint: true
+  }
+}))