@intangle/mcp-server 2.6.1 → 2.6.3

package/README.md

@@ -17,7 +17,7 @@ Intangle is an AI context system that gives Claude and other AI assistants persi
 Claude code by running the command below (recommend "-s" user for global across projects):
 
 ```bash
-claude mcp add intangle -s user --env MCP_API_KEY=<your-api-key-here> --env NEXT_APP_URL=https://intangle.app -- npx -y @intangle/mcp-server
+claude mcp add intangle -s user --env MCP_API_KEY=<your-api-key-here> --env NEXT_APP_URL=https://app.intangle.app -- npx -y @intangle/mcp-server
 ```
 
 If your deployment is behind Vercel Deployment Protection (for example staging), add:
@@ -36,7 +36,7 @@ Standard MCP (Claude desktop, Cursor): by adding to your `claude_desktop_config.
       "args": ["@intangle/mcp-server"],
       "env": {
         "MCP_API_KEY": "your-api-key-here",
-        "NEXT_APP_URL": "https://intangle.app",
+        "NEXT_APP_URL": "https://app.intangle.app",
         "VERCEL_BYPASS_TOKEN": "optional-vercel-bypass-token-for-protected-deployments"
       }
     }

package/dist/index.js

@@ -30,7 +30,7 @@ try {
     config({ quiet: true });
     config({ path: ".env.local", quiet: true });
     // Base URL for API calls to Next.js app
-    const API_BASE_URL = process.env.NEXT_APP_URL || "https://intangle.app";
+    const API_BASE_URL = process.env.NEXT_APP_URL || "https://app.intangle.app";
     const MCP_API_KEY = process.env.MCP_API_KEY;
     const VERCEL_BYPASS_TOKEN = process.env.VERCEL_BYPASS_TOKEN || process.env.VERCEL_PROTECTION_BYPASS;
     log(`CWD: ${process.cwd()}`);
@@ -155,6 +155,11 @@ try {
             if (responseBody.trim() === "") {
                 return {};
             }
+            if (contentType.includes("text/html") ||
+                /^\s*<!DOCTYPE\s+html/i.test(responseBody) ||
+                /^\s*<html\b/i.test(responseBody)) {
+                throw new Error(`API call to ${buildApiUrl(endpoint)} returned HTML instead of JSON. Check NEXT_APP_URL and point it at the app host, e.g. https://app.intangle.app.`);
+            }
             return JSON.parse(responseBody);
         }
         catch (error) {
@@ -257,7 +262,7 @@ try {
         resourceTemplates: [],
     }));
     async function handleSearchContext(args) {
-        const { space_id, query, topics } = args;
+        const { space_id, query, topics, group_id, project_id, folder_id } = args;
         // Require space_id
         if (!space_id) {
             throw new Error("space_id is required. Use list_spaces to see available options.");
@@ -265,12 +270,18 @@ try {
         return makeApiCall("search", {
             space_id,
             query,
+            group_id,
+            project_id,
+            folder_id,
             topics,
         });
     }
     async function handleFetch(args) {
-        const { id, ids } = args;
-        return makeApiCall("fetch", { id, ids });
+        const { id, ids, space_id } = args;
+        return makeApiCall("fetch", { id, ids, space_id });
+    }
+    async function handleUsageStatus() {
+        return makeApiCall("usage-status", {});
     }
     async function handleFetchConversationMessages(args) {
         const { space_id, conversation_id } = args;
@@ -308,14 +319,14 @@ try {
         if (!space_id) {
             throw new Error("space_id is required. Use view_spaces to see available options.");
         }
-        return makeApiCall("view-groups", { space_id });
+        return makeApiCall("view-groups", args);
     }
     async function handleViewProjects(args) {
         const { space_id } = args;
         if (!space_id) {
             throw new Error("space_id is required. Use view_spaces to see available options.");
         }
-        return makeApiCall("view-projects", { space_id });
+        return makeApiCall("view-projects", args);
     }
     async function handleViewProject(args) {
         const { project_id, space_id, slug } = args;
@@ -325,71 +336,67 @@ try {
         if (!space_id) {
             throw new Error("space_id is required. Use view_spaces to see available options.");
         }
-        return makeApiCall("view-project", { project_id, space_id, slug });
+        return makeApiCall("view-project", args);
     }
     async function handleCreateGroup(args) {
         const { space_id, name } = args;
         if (!space_id || !name) {
             throw new Error("space_id and name are required");
         }
-        return makeApiCall("create-group", { space_id, name });
+        return makeApiCall("create-group", args);
     }
     async function handleRenameGroup(args) {
         const { space_id, group_id, name } = args;
         if (!space_id || !group_id || !name) {
             throw new Error("space_id, group_id, and name are required");
         }
-        return makeApiCall("rename-group", { space_id, group_id, name });
+        return makeApiCall("rename-group", args);
     }
     async function handleDeleteGroup(args) {
         const { space_id, group_id } = args;
         if (!space_id || !group_id) {
             throw new Error("space_id and group_id are required");
         }
-        return makeApiCall("delete-group", { space_id, group_id });
+        return makeApiCall("delete-group", args);
     }
     async function handleCreateProject(args) {
         const { space_id, name, group_id } = args;
         if (!space_id || !name) {
             throw new Error("space_id and name are required");
         }
-        return makeApiCall("create-project", { space_id, name, group_id });
+        return makeApiCall("create-project", args);
     }
     async function handleRenameProject(args) {
         const { space_id, project_id, name } = args;
         if (!space_id || !project_id || !name) {
             throw new Error("space_id, project_id, and name are required");
         }
-        return makeApiCall("rename-project", { space_id, project_id, name });
+        return makeApiCall("rename-project", args);
     }
     async function handleDeleteProject(args) {
         const { space_id, project_id } = args;
         if (!space_id || !project_id) {
             throw new Error("space_id and project_id are required");
         }
-        return makeApiCall("delete-project", { space_id, project_id });
+        return makeApiCall("delete-project", args);
     }
     async function handleAssignProjectToGroup(args) {
         const { space_id, project_id, group_id } = args;
         if (!space_id || !project_id) {
             throw new Error("space_id and project_id are required");
         }
-        return makeApiCall("assign-project-to-group", {
-            space_id,
-            project_id,
-            group_id,
-        });
+        return makeApiCall("assign-project-to-group", args);
     }
     async function handleCreateSpace(args) {
         return makeApiCall("create-space", args);
     }
     async function handleViewSpace(args) {
         const { space_id } = args;
-        return makeApiCall("view-space", { space_id });
+        return makeApiCall("view-space", args);
     }
     async function handleStart(args) {
         const { space_id } = args;
-        return makeApiCall("start", { space_id });
+        return makeApiCall("start", args);
     }
     async function handleUpdateSpace(args) {
         if (!args.space_id) {
@@ -462,6 +469,9 @@ try {
                 case "fetch_items":
                     result = await handleFetch(args);
                     break;
+                case "usage_status":
+                    result = await handleUsageStatus();
+                    break;
                 case "fetch_conversation_messages":
                     result = await handleFetchConversationMessages(args);
                     break;

package/dist/tool-definitions.js

@@ -15,6 +15,18 @@ const TOOL_DEFINITIONS = [
                     type: "string",
                     description: "REQUIRED: Space to search in (use view_spaces to see available options)"
                 },
+                group_id: {
+                    type: "string",
+                    description: "Optional: Restrict search to one group inside the chosen space."
+                },
+                project_id: {
+                    type: "string",
+                    description: "Optional: Restrict search to one project inside the chosen space."
+                },
+                folder_id: {
+                    type: "string",
+                    description: "Optional: Restrict search to one folder inside the chosen space/project."
+                },
                 topics: {
                     type: "array",
                     items: { type: "string" },
@@ -31,6 +43,10 @@ const TOOL_DEFINITIONS = [
         inputSchema: {
             type: "object",
             properties: {
+                space_id: {
+                    type: "string",
+                    description: "Optional: Space containing the items. Provide this for shared/org spaces so fetch resolves against the correct graph."
+                },
                 id: {
                     type: "string",
                     description: "Single ID to fetch (context or task ID like 'mem_123' or 'task_456' or 'skill_789')"
@@ -43,10 +59,22 @@ const TOOL_DEFINITIONS = [
             }
         }
     },
+    {
+        name: "usage_status",
+        title: "Usage Status",
+        description: "Return the live shared AI + voice usage status for the authenticated user, including 4-hour and weekly counters and reset times when available.",
+        inputSchema: {
+            type: "object",
+            properties: {}
+        },
+        annotations: {
+            readOnlyHint: true
+        }
+    },
     {
         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`.",
+        description: "Read persisted messages from a conversation/chat summary. Use this to poll shared threads after async `message` calls and to fetch only new messages via `since_timestamp` instead of reloading the whole thread. External agents should pass stable participant fields so unread counts and subscriptions stay consistent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -77,7 +105,7 @@ const TOOL_DEFINITIONS = [
     {
         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.",
+        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. External agents should reuse a stable participant_id, set participant_type to `agent`, and send a clear participant_label so Tan can distinguish callers.",
         inputSchema: {
             type: "object",
             properties: {
@@ -95,15 +123,15 @@ const TOOL_DEFINITIONS = [
                 },
                 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."
+                    description: "Optional stable participant ID. External agents should always reuse the same explicit `agent_*` style ID across message, subscribe_conversation, list_conversation_inbox, fetch_conversation_messages, and mark_conversation_read."
                 },
                 participant_type: {
                     type: "string",
-                    description: "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+                    description: "Optional participant type. External MCP callers should set this to `agent`. Supported values: `user`, `agent`, `assistant`, `connector`."
                 },
                 participant_label: {
                     type: "string",
-                    description: "Optional display label for the participant in collaborative chat UIs."
+                    description: "Optional display label for the participant in collaborative chat UIs. External agents should send a human-readable label such as `Claude Research` or `Codex Builder`."
                 },
                 mark_read: {
                     type: "boolean",
@@ -116,7 +144,7 @@ const TOOL_DEFINITIONS = [
     {
         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.",
+        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 without reloading full transcripts. Reuse the same participant_id, participant_type=`agent`, and participant_label so unread state stays attached to the right caller.",
         inputSchema: {
             type: "object",
             properties: {
@@ -130,15 +158,15 @@ const TOOL_DEFINITIONS = [
                 },
                 participant_id: {
                     type: "string",
-                    description: "Optional stable participant ID. Use the same value you used for message/subscribe calls to read the same inbox."
+                    description: "Optional stable participant ID. Use the exact same value you used for message and subscribe_conversation so the inbox stays tied to one external agent identity."
                 },
                 participant_type: {
                     type: "string",
-                    description: "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+                    description: "Optional participant type. External MCP callers should set this to `agent`. 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."
+                    description: "Optional display label used when the participant identity is being created for the first time. Reuse the same label for the same external agent."
                 },
                 unread_only: {
                     type: "boolean",
@@ -159,7 +187,7 @@ const TOOL_DEFINITIONS = [
     {
         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.",
+        description: "Advance a participant's read cursor for a shared conversation. Use this after processing messages returned from fetch_conversation_messages so unread counts stay accurate for external agents and separate callers do not share one cursor.",
         inputSchema: {
             type: "object",
             properties: {
@@ -177,15 +205,15 @@ const TOOL_DEFINITIONS = [
                 },
                 participant_id: {
                     type: "string",
-                    description: "Optional stable participant ID. Use the same value you used for message/subscribe calls."
+                    description: "Optional stable participant ID. Use the same value you used for message, subscribe_conversation, and list_conversation_inbox."
                 },
                 participant_type: {
                     type: "string",
-                    description: "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+                    description: "Optional participant type. External MCP callers should set this to `agent`. 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."
+                    description: "Optional display label used when the participant identity is being created for the first time. Reuse the same label for the same external agent."
                 },
                 read_at: {
                     type: "integer",
@@ -400,7 +428,7 @@ const TOOL_DEFINITIONS = [
     {
         name: "start",
         title: "Start Space Session",
-        description: "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.",
+        description: "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. Use this before asking Tan to do work in that space.",
         inputSchema: {
             type: "object",
             properties: {
@@ -415,7 +443,7 @@ const TOOL_DEFINITIONS = [
     {
         name: "view_spaces",
         title: "View Spaces",
-        description: "View all available spaces with their descriptions and metrics.",
+        description: "View the spaces this connector can access so you can choose the right space for memory, communicating and collaborating with Tan agent. If your connector is scoped to one space, you will only see that space. Use the exact space_id from this list for all space-scoped tools.",
         inputSchema: {
             type: "object",
             properties: {}
@@ -452,7 +480,7 @@ const TOOL_DEFINITIONS = [
     {
         name: "view_space",
         title: "View Space",
-        description: "View detailed information about a space including configuration and overview.",
+        description: "View detailed information about a space including configuration and overview. Use this when you need the exact active scope before saving memory or communicating and collaborating with Tan agent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -467,7 +495,7 @@ const TOOL_DEFINITIONS = [
     {
         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\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.",
+        description: "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- Prefer updating an existing related memory when the new information refines or extends it instead of creating a duplicate\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nUse project_id and group_id when you know the active project or group scope. The system learns from patterns - sharing how the user works helps it anticipate their needs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -479,6 +507,10 @@ const TOOL_DEFINITIONS = [
                     type: "string",
                     description: "Optional: Project to add items to. All items created in this request will be linked to this project and appear on its canvas. Get project IDs from the start tool output."
                 },
+                group_id: {
+                    type: "string",
+                    description: "Optional: Group to add items to. Use this alongside project_id when the current item belongs in a group."
+                },
                 add: {
                     type: "object",
                     description: "Add new items. ALWAYS pass 'type' field on each item to skip expensive auto-classification.",
@@ -718,7 +750,7 @@ const TOOL_DEFINITIONS = [
     {
         name: "message",
         title: "Message Assistant",
-        description: "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.",
+        description: "Primary way to use Intangle for memory, communicating and collaborating with Tan agent in a shared thread. Send a request and either wait for one assistant turn to complete or submit asynchronously for later polling. External agents should include a stable participant_id, participant_type=`agent`, and participant_label so Tan can identify who is speaking and keep progress updates attached to the right caller. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
         inputSchema: {
             type: "object",
             properties: {
@@ -728,7 +760,7 @@ const TOOL_DEFINITIONS = [
                 },
                 content: {
                     type: "string",
-                    description: "User message content to send to the assistant."
+                    description: "User message content to send to Tan."
                 },
                 provider: {
                     type: "string",
@@ -760,19 +792,19 @@ const TOOL_DEFINITIONS = [
                 },
                 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."
+                    description: "Optional. Defaults to true. Set false to submit the turn asynchronously when you want a quick acknowledgement first and then poll later with list_conversation_inbox or 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."
+                    description: "Optional stable participant ID for collaborative/shared chats. External agents should always send and reuse an explicit `agent_*` style ID so Tan can tell different external agents apart."
                 },
                 participant_type: {
                     type: "string",
-                    description: "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+                    description: "Optional participant type. External MCP callers should set this to `agent`. Supported values: `user`, `agent`, `assistant`, `connector`."
                 },
                 participant_label: {
                     type: "string",
-                    description: "Optional display label for the participant in collaborative chat UIs."
+                    description: "Optional display label for the participant in collaborative chat UIs. External agents should send a clear label that Tan can use in follow-up coordination."
                 },
                 timezone: {
                     type: "string",
@@ -809,6 +841,7 @@ const TOOL_DEFINITIONS = [
 const READ_ONLY_TOOLS = new Set([
     "search",
     "fetch_items",
+    "usage_status",
     "fetch_conversation_messages",
     "list_conversation_inbox",
     "start",
@@ -823,6 +856,7 @@ const DESTRUCTIVE_TOOLS = new Set([
 const IDEMPOTENT_TOOLS = new Set([
     "search",
     "fetch_items",
+    "usage_status",
     "fetch_conversation_messages",
     "list_conversation_inbox",
     "start",

package/index.ts

@@ -45,7 +45,7 @@ try {
   config({ path: ".env.local", quiet: true })
 
   // Base URL for API calls to Next.js app
-  const API_BASE_URL = process.env.NEXT_APP_URL || "https://intangle.app"
+  const API_BASE_URL = process.env.NEXT_APP_URL || "https://app.intangle.app"
   const MCP_API_KEY = process.env.MCP_API_KEY
   const VERCEL_BYPASS_TOKEN =
     process.env.VERCEL_BYPASS_TOKEN || process.env.VERCEL_PROTECTION_BYPASS
@@ -209,6 +209,16 @@ try {
         return {}
       }
 
+      if (
+        contentType.includes("text/html") ||
+        /^\s*<!DOCTYPE\s+html/i.test(responseBody) ||
+        /^\s*<html\b/i.test(responseBody)
+      ) {
+        throw new Error(
+          `API call to ${buildApiUrl(endpoint)} returned HTML instead of JSON. Check NEXT_APP_URL and point it at the app host, e.g. https://app.intangle.app.`
+        )
+      }
+
       return JSON.parse(responseBody)
     } catch (error: unknown) {
       if (error instanceof Error && error.name === "AbortError") {
@@ -338,10 +348,13 @@ try {
   }))
 
   async function handleSearchContext(args: any) {
-    const { space_id, query, topics } = args as {
+    const { space_id, query, topics, group_id, project_id, folder_id } = args as {
       space_id: string
       query: string
       topics?: string[]
+      group_id?: string
+      project_id?: string
+      folder_id?: string
     }
 
     // Require space_id
@@ -354,14 +367,25 @@ try {
     return makeApiCall("search", {
       space_id,
       query,
+      group_id,
+      project_id,
+      folder_id,
       topics,
     })
   }
 
   async function handleFetch(args: any) {
-    const { id, ids } = args as { id?: string; ids?: string[] }
+    const { id, ids, space_id } = args as {
+      id?: string
+      ids?: string[]
+      space_id?: string
+    }
 
-    return makeApiCall("fetch", { id, ids })
+    return makeApiCall("fetch", { id, ids, space_id })
+  }
+
+  async function handleUsageStatus() {
+    return makeApiCall("usage-status", {})
   }
 
   async function handleFetchConversationMessages(args: any) {
@@ -425,7 +449,7 @@ try {
       )
     }
 
-    return makeApiCall("view-groups", { space_id })
+    return makeApiCall("view-groups", args)
   }
 
   async function handleViewProjects(args: any) {
@@ -435,7 +459,7 @@ try {
         "space_id is required. Use view_spaces to see available options."
       )
     }
-    return makeApiCall("view-projects", { space_id })
+    return makeApiCall("view-projects", args)
   }
 
   async function handleViewProject(args: any) {
@@ -457,7 +481,7 @@ try {
       )
     }
 
-    return makeApiCall("view-project", { project_id, space_id, slug })
+    return makeApiCall("view-project", args)
   }
 
   async function handleCreateGroup(args: any) {
@@ -466,7 +490,7 @@ try {
       throw new Error("space_id and name are required")
     }
 
-    return makeApiCall("create-group", { space_id, name })
+    return makeApiCall("create-group", args)
   }
 
   async function handleRenameGroup(args: any) {
@@ -480,7 +504,7 @@ try {
       throw new Error("space_id, group_id, and name are required")
     }
 
-    return makeApiCall("rename-group", { space_id, group_id, name })
+    return makeApiCall("rename-group", args)
   }
 
   async function handleDeleteGroup(args: any) {
@@ -493,7 +517,7 @@ try {
       throw new Error("space_id and group_id are required")
     }
 
-    return makeApiCall("delete-group", { space_id, group_id })
+    return makeApiCall("delete-group", args)
   }
 
   async function handleCreateProject(args: any) {
@@ -507,7 +531,7 @@ try {
       throw new Error("space_id and name are required")
     }
 
-    return makeApiCall("create-project", { space_id, name, group_id })
+    return makeApiCall("create-project", args)
   }
 
   async function handleRenameProject(args: any) {
@@ -521,7 +545,7 @@ try {
       throw new Error("space_id, project_id, and name are required")
     }
 
-    return makeApiCall("rename-project", { space_id, project_id, name })
+    return makeApiCall("rename-project", args)
   }
 
   async function handleDeleteProject(args: any) {
@@ -534,7 +558,7 @@ try {
       throw new Error("space_id and project_id are required")
     }
 
-    return makeApiCall("delete-project", { space_id, project_id })
+    return makeApiCall("delete-project", args)
   }
 
   async function handleAssignProjectToGroup(args: any) {
@@ -548,11 +572,7 @@ try {
       throw new Error("space_id and project_id are required")
     }
 
-    return makeApiCall("assign-project-to-group", {
-      space_id,
-      project_id,
-      group_id,
-    })
+    return makeApiCall("assign-project-to-group", args)
   }
 
   async function handleCreateSpace(args: any) {
@@ -561,12 +581,12 @@ try {
 
   async function handleViewSpace(args: any) {
     const { space_id } = args as { space_id: string }
-    return makeApiCall("view-space", { space_id })
+    return makeApiCall("view-space", args)
   }
 
   async function handleStart(args: any) {
     const { space_id } = args as { space_id: string }
-    return makeApiCall("start", { space_id })
+    return makeApiCall("start", args)
   }
 
   async function handleUpdateSpace(args: any) {
@@ -668,6 +688,9 @@ try {
         case "fetch_items":
           result = await handleFetch(args)
           break
+        case "usage_status":
+          result = await handleUsageStatus()
+          break
         case "fetch_conversation_messages":
           result = await handleFetchConversationMessages(args)
           break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intangle/mcp-server",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Model Context Protocol server for Intangle - AI context that persists across conversations",
   "main": "dist/index.js",
   "type": "module",

package/tool-definitions.ts

@@ -18,6 +18,21 @@ const TOOL_DEFINITIONS = [
           description:
             "REQUIRED: Space to search in (use view_spaces to see available options)"
         },
+        group_id: {
+          type: "string",
+          description:
+            "Optional: Restrict search to one group inside the chosen space."
+        },
+        project_id: {
+          type: "string",
+          description:
+            "Optional: Restrict search to one project inside the chosen space."
+        },
+        folder_id: {
+          type: "string",
+          description:
+            "Optional: Restrict search to one folder inside the chosen space/project."
+        },
         topics: {
           type: "array",
           items: { type: "string" },
@@ -35,6 +50,11 @@ const TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
+        space_id: {
+          type: "string",
+          description:
+            "Optional: Space containing the items. Provide this for shared/org spaces so fetch resolves against the correct graph."
+        },
         id: {
           type: "string",
           description:
@@ -49,11 +69,24 @@ const TOOL_DEFINITIONS = [
       }
     }
   },
+  {
+    name: "usage_status",
+    title: "Usage Status",
+    description:
+      "Return the live shared AI + voice usage status for the authenticated user, including 4-hour and weekly counters and reset times when available.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
   {
     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`.",
+      "Read persisted messages from a conversation/chat summary. Use this to poll shared threads after async `message` calls and to fetch only new messages via `since_timestamp` instead of reloading the whole thread. External agents should pass stable participant fields so unread counts and subscriptions stay consistent.",
     inputSchema: {
       type: "object",
       properties: {
@@ -90,7 +123,7 @@ const TOOL_DEFINITIONS = [
     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.",
+      "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. External agents should reuse a stable participant_id, set participant_type to `agent`, and send a clear participant_label so Tan can distinguish callers.",
     inputSchema: {
       type: "object",
       properties: {
@@ -112,17 +145,17 @@ const TOOL_DEFINITIONS = [
         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."
+            "Optional stable participant ID. External agents should always reuse the same explicit `agent_*` style ID across message, subscribe_conversation, list_conversation_inbox, fetch_conversation_messages, and mark_conversation_read."
         },
         participant_type: {
           type: "string",
           description:
-            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+            "Optional participant type. External MCP callers should set this to `agent`. Supported values: `user`, `agent`, `assistant`, `connector`."
         },
         participant_label: {
           type: "string",
           description:
-            "Optional display label for the participant in collaborative chat UIs."
+            "Optional display label for the participant in collaborative chat UIs. External agents should send a human-readable label such as `Claude Research` or `Codex Builder`."
         },
         mark_read: {
           type: "boolean",
@@ -137,7 +170,7 @@ const TOOL_DEFINITIONS = [
     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.",
+      "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 without reloading full transcripts. Reuse the same participant_id, participant_type=`agent`, and participant_label so unread state stays attached to the right caller.",
     inputSchema: {
       type: "object",
       properties: {
@@ -154,17 +187,17 @@ const TOOL_DEFINITIONS = [
         participant_id: {
           type: "string",
           description:
-            "Optional stable participant ID. Use the same value you used for message/subscribe calls to read the same inbox."
+            "Optional stable participant ID. Use the exact same value you used for message and subscribe_conversation so the inbox stays tied to one external agent identity."
         },
         participant_type: {
           type: "string",
           description:
-            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+            "Optional participant type. External MCP callers should set this to `agent`. 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."
+            "Optional display label used when the participant identity is being created for the first time. Reuse the same label for the same external agent."
         },
         unread_only: {
           type: "boolean",
@@ -189,7 +222,7 @@ const TOOL_DEFINITIONS = [
     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.",
+      "Advance a participant's read cursor for a shared conversation. Use this after processing messages returned from fetch_conversation_messages so unread counts stay accurate for external agents and separate callers do not share one cursor.",
     inputSchema: {
       type: "object",
       properties: {
@@ -211,17 +244,17 @@ const TOOL_DEFINITIONS = [
         participant_id: {
           type: "string",
           description:
-            "Optional stable participant ID. Use the same value you used for message/subscribe calls."
+            "Optional stable participant ID. Use the same value you used for message, subscribe_conversation, and list_conversation_inbox."
         },
         participant_type: {
           type: "string",
           description:
-            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+            "Optional participant type. External MCP callers should set this to `agent`. 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."
+            "Optional display label used when the participant identity is being created for the first time. Reuse the same label for the same external agent."
         },
         read_at: {
           type: "integer",
@@ -451,7 +484,7 @@ const TOOL_DEFINITIONS = [
     name: "start",
     title: "Start Space Session",
     description:
-      "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.",
+      "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. Use this before asking Tan to do work in that space.",
     inputSchema: {
       type: "object",
       properties: {
@@ -467,7 +500,7 @@ const TOOL_DEFINITIONS = [
     name: "view_spaces",
     title: "View Spaces",
     description:
-      "View all available spaces with their descriptions and metrics.",
+      "View the spaces this connector can access so you can choose the right space for memory, communicating and collaborating with Tan agent. If your connector is scoped to one space, you will only see that space. Use the exact space_id from this list for all space-scoped tools.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -509,7 +542,7 @@ const TOOL_DEFINITIONS = [
     name: "view_space",
     title: "View Space",
     description:
-      "View detailed information about a space including configuration and overview.",
+      "View detailed information about a space including configuration and overview. Use this when you need the exact active scope before saving memory or communicating and collaborating with Tan agent.",
     inputSchema: {
       type: "object",
       properties: {
@@ -525,7 +558,7 @@ const TOOL_DEFINITIONS = [
     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\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.",
+      "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- Prefer updating an existing related memory when the new information refines or extends it instead of creating a duplicate\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nUse project_id and group_id when you know the active project or group scope. The system learns from patterns - sharing how the user works helps it anticipate their needs.",
     inputSchema: {
       type: "object",
       properties: {
@@ -539,6 +572,11 @@ const TOOL_DEFINITIONS = [
           description:
             "Optional: Project to add items to. All items created in this request will be linked to this project and appear on its canvas. Get project IDs from the start tool output."
         },
+        group_id: {
+          type: "string",
+          description:
+            "Optional: Group to add items to. Use this alongside project_id when the current item belongs in a group."
+        },
         add: {
           type: "object",
           description:
@@ -800,7 +838,7 @@ const TOOL_DEFINITIONS = [
     name: "message",
     title: "Message Assistant",
     description:
-      "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.",
+      "Primary way to use Intangle for memory, communicating and collaborating with Tan agent in a shared thread. Send a request and either wait for one assistant turn to complete or submit asynchronously for later polling. External agents should include a stable participant_id, participant_type=`agent`, and participant_label so Tan can identify who is speaking and keep progress updates attached to the right caller. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
     inputSchema: {
       type: "object",
       properties: {
@@ -811,7 +849,7 @@ const TOOL_DEFINITIONS = [
         },
         content: {
           type: "string",
-          description: "User message content to send to the assistant."
+          description: "User message content to send to Tan."
         },
         provider: {
           type: "string",
@@ -849,22 +887,22 @@ const TOOL_DEFINITIONS = [
         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."
+            "Optional. Defaults to true. Set false to submit the turn asynchronously when you want a quick acknowledgement first and then poll later with list_conversation_inbox or 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."
+            "Optional stable participant ID for collaborative/shared chats. External agents should always send and reuse an explicit `agent_*` style ID so Tan can tell different external agents apart."
         },
         participant_type: {
           type: "string",
           description:
-            "Optional participant type. Defaults to `user`. Supported values: `user`, `agent`, `assistant`, `connector`."
+            "Optional participant type. External MCP callers should set this to `agent`. Supported values: `user`, `agent`, `assistant`, `connector`."
         },
         participant_label: {
           type: "string",
           description:
-            "Optional display label for the participant in collaborative chat UIs."
+            "Optional display label for the participant in collaborative chat UIs. External agents should send a clear label that Tan can use in follow-up coordination."
         },
         timezone: {
           type: "string",
@@ -902,6 +940,7 @@ const TOOL_DEFINITIONS = [
 const READ_ONLY_TOOLS = new Set([
   "search",
   "fetch_items",
+  "usage_status",
   "fetch_conversation_messages",
   "list_conversation_inbox",
   "start",
@@ -918,6 +957,7 @@ const DESTRUCTIVE_TOOLS = new Set([
 const IDEMPOTENT_TOOLS = new Set([
   "search",
   "fetch_items",
+  "usage_status",
   "fetch_conversation_messages",
   "list_conversation_inbox",
   "start",