@nestr/mcp 0.1.46 → 0.1.48

package/build/tools/index.js

@@ -27,7 +27,7 @@ function completableResponse(data, source, title) {
 // Fields to keep for compact list responses (reduces token usage)
 const COMPACT_FIELDS = {
     // Common fields for all nests (includes fields needed by the completable list app)
-    base: ["_id", "title", "purpose", "completed", "labels", "path", "parentId", "ancestors", "description", "due"],
+    base: ["_id", "title", "purpose", "completed", "labels", "path", "parentId", "ancestors", "description", "due", "hints"],
     // Additional fields for roles
     role: ["accountabilities", "domains"],
     // Additional fields for users
@@ -65,6 +65,68 @@ function compactResponse(data, type = "nest") {
         return compact;
     });
 }
+// URL-to-tool mapping for hint enrichment.
+// The Nestr API returns hints with relative URLs (e.g., "/nests/abc123/children?search=...").
+// This maps those URL patterns to MCP tool calls so models can act on hints directly.
+// Note: patterns are tried in order — more specific patterns must come before catch-alls.
+const HINT_URL_PATTERNS = [
+    // /nests/{id}/children?search=... → nestr_search with in:{id} scoped query
+    {
+        pattern: /^\/nests\/([^/]+)\/children$/,
+        tool: "nestr_search",
+        params: (m, sp, workspaceId) => {
+            const search = sp.get("search") || "";
+            const result = { query: `in:${m[1]} ${search}`.trim() };
+            if (workspaceId)
+                result.workspaceId = workspaceId;
+            return result;
+        },
+    },
+    // /nests/{id}/posts → nestr_get_comments
+    { pattern: /^\/nests\/([^/]+)\/posts$/, tool: "nestr_get_comments", params: (m) => ({ nestId: m[1] }) },
+    // /nests/{id}/tensions → nestr_list_tensions
+    { pattern: /^\/nests\/([^/]+)\/tensions$/, tool: "nestr_list_tensions", params: (m) => ({ nestId: m[1] }) },
+    // /nests/{id} → nestr_get_nest (must be last — catches all /nests/{id} patterns)
+    { pattern: /^\/nests\/([^/]+)$/, tool: "nestr_get_nest", params: (m) => ({ nestId: m[1] }) },
+];
+// Enrich hints with tool call parameters so models can act on hints directly.
+// Extracts workspaceId from nest ancestors (last element) for search-based hints.
+function enrichHints(data) {
+    if (!data || typeof data !== "object")
+        return data;
+    // Handle arrays (e.g., from getNestChildren)
+    if (Array.isArray(data)) {
+        return data.map((item) => enrichHints(item));
+    }
+    // Handle wrapped responses { data: [...] }
+    if ("data" in data && Array.isArray(data.data)) {
+        return { ...data, data: enrichHints(data.data) };
+    }
+    // Enrich hints on this nest
+    const record = data;
+    if (Array.isArray(record.hints)) {
+        // Extract workspaceId from ancestors (last element is always the workspace)
+        const ancestors = record.ancestors;
+        const workspaceId = ancestors?.length ? ancestors[ancestors.length - 1] : undefined;
+        record.hints = record.hints.map((hint) => {
+            if (!hint.url)
+                return hint;
+            // Parse URL and query params
+            const [path, queryString] = hint.url.split("?");
+            const searchParams = new URLSearchParams(queryString || "");
+            for (const { pattern, tool, params } of HINT_URL_PATTERNS) {
+                const match = path.match(pattern);
+                if (match) {
+                    return { ...hint, toolCall: { tool, params: params(match, searchParams, workspaceId) } };
+                }
+            }
+            // Log unrecognized hint URLs so we can add mappings when the API adds new patterns
+            console.error(`[nestr-mcp] Unrecognized hint URL pattern: "${hint.url}" (hint type: ${hint.type})`);
+            return hint;
+        });
+    }
+    return data;
+}
 // Tool input schemas using Zod
 export const schemas = {
     listWorkspaces: z.object({
@@ -94,11 +156,13 @@ export const schemas = {
     getNest: z.object({
         nestId: z.string().describe("Nest ID. Supports comma-separated IDs to fetch multiple nests in one call (e.g., 'id1,id2,id3') — returns an array instead of a single object. Keep total URL under 2000 chars to avoid HTTP limits."),
         fieldsMetaData: z.boolean().optional().describe("Set to true to include field schema metadata (e.g., available options for project.status)"),
+        hints: z.boolean().optional().describe("Include contextual hints on each nest (default: true). Hints surface actionable signals like unassigned roles, stale projects, or unread comments. Set to false for bulk lookups where you only need structural data, not contextual guidance."),
     }),
     getNestChildren: z.object({
         nestId: z.string().describe("Parent nest ID"),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
+        hints: z.boolean().optional().describe("Include contextual hints on each child nest (default: true). Set to false for large result sets or bulk operations where contextual signals aren't needed."),
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Tasks for Website Redesign\"). Omit for default."),
     }),
     createNest: z.object({
@@ -133,11 +197,11 @@ export const schemas = {
     }),
     addComment: z.object({
         nestId: z.string().describe("Nest ID to comment on"),
-        body: z.string().describe("Comment text (supports HTML and @mentions)"),
+        body: z.string().describe("Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
     }),
     updateComment: z.object({
         commentId: z.string().describe("Comment ID to update"),
-        body: z.string().describe("Updated comment text (supports HTML and @mentions)"),
+        body: z.string().describe("Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
     }),
     deleteComment: z.object({
         commentId: z.string().describe("Comment ID to delete"),
@@ -491,7 +555,27 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_search",
-        description: "Search for nests within a workspace. Supports operators: label:, parent-label:, assignee: (me/userId/!userId/none), admin:, createdby:, completed:, type:, has: (due/pastdue/children/incompletechildren), depth:, mindepth:, in:, updated-date:, limit:, template:, data.property:, fields.{label}.{property}: to search any value in a nest's fields object (supports partial match, e.g., fields.project.status:Current — use nestr_get_nest with fieldsMetaData=true to discover available fields), label->field:value. Use ! prefix for negation. IMPORTANT: Use completed:false when searching for work to exclude old completed items. Response includes meta.total showing total matching count. IMPORTANT UI RULE: The completable list app must ONLY be used when results contain completable items (tasks, projects, todos) AND there are results to show. When searching for roles, circles, metrics, policies, or any non-completable type, you MUST omit the _listTitle parameter and respond in plain text instead — never render these in the app. Also never render empty results in the app.",
+        description: `Search for nests within a workspace. IMPORTANT: Use completed:false when searching for work to exclude old completed items.
+
+Operators (combine with spaces for AND; commas within operator for OR; ! prefix for negation):
+- label:role / label:!project — Filter/exclude by label
+- parent-label:circle — Parent has this label
+- assignee:me / assignee:userId / assignee:none / assignee:!userId — Filter by assignee
+- completed:false / completed:true / completed:past_7_days / completed:this_month / completed:YYYY-MM-DD_YYYY-MM-DD
+- in:nestId — Scope to descendants of a specific nest
+- depth:1 / depth:2 — Limit depth (1=direct children, 2=children+grandchildren)
+- mindepth:N — Minimum depth from context
+- has:due / has:pastdue / has:children / has:incompletechildren (supports ! prefix)
+- project->status:Current,Future / project->status:!Done — Field value search (label->field:value)
+- fields.label.property:value — Search any field value (supports partial match)
+- data.property:value — Search data properties
+- updated-date:past_7_days / updated-date:!past_30_days — Filter by update recency
+- sort:title / sort:due / sort:updatedAt / sort:createdAt + sort-order:asc/desc
+- createdby:me / admin:me / type:comment / limit:N / template:id
+
+Examples: label:role → all roles | assignee:me completed:false → my active work | in:circleId label:role depth:1 → roles in circle | label:project project->status:Current → active projects | in:roleId label:project → role's projects | has:pastdue completed:false → overdue items | label:accountability customer → accountabilities matching keyword
+
+Response includes meta.total showing total matching count. IMPORTANT UI RULE: The completable list app must ONLY be used when results are confirmed to contain completable items (tasks, projects, todos) AND there are results to show. When searching for roles, circles, metrics, policies, or any non-completable type, you MUST omit the _listTitle parameter and respond in plain text instead. Never render empty results in the app.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -504,7 +588,8 @@ export const toolDefinitions = [
             },
             required: ["workspaceId", "query"],
         },
-        _meta: completableListUi,
+        // No _meta: completableListUi — search returns all types of nests (roles, circles, etc.).
+        // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
     {
@@ -515,6 +600,7 @@ export const toolDefinitions = [
             properties: {
                 nestId: { type: "string", description: "Nest ID, or comma-separated IDs to fetch multiple nests at once (e.g., 'id1,id2,id3'). Keep total URL under 2000 chars." },
                 fieldsMetaData: { type: "boolean", description: "Set to true to include field schema metadata (available options, field types)" },
+                hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for bulk lookups where you only need structural data." },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
             },
             required: ["nestId"],
@@ -530,17 +616,19 @@ export const toolDefinitions = [
                 nestId: { type: "string", description: "Parent nest ID" },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
+                hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for large result sets or bulk operations." },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
                 _listTitle: { type: "string", description: "Short descriptive title for the list UI header (e.g., \"Tasks for Website Redesign\", \"API project sub-tasks\"). Include the parent name for context." },
             },
             required: ["nestId"],
         },
-        _meta: completableListUi,
+        // No _meta: completableListUi — children can be any type (roles, accountabilities, etc.).
+        // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
     {
         name: "nestr_create_nest",
-        description: "Create a new nest (task, project, role, circle, etc.) under a parent. Set users to assign to people - placing under a role does NOT auto-assign. For roles and circles: include accountabilities and domains arrays to create them inline (requires workspaceId). The API auto-routes to the self-organization endpoint when governance labels are detected with accountabilities/domains.",
+        description: "Create a new nest (task, project, role, circle, etc.) under a parent. Set users to assign to people - placing under a role does NOT auto-assign. For roles and circles: include accountabilities and domains arrays to create them inline (requires workspaceId). The API auto-routes to the self-organization endpoint when governance labels are detected with accountabilities/domains. GOVERNANCE RULE: Only create roles, circles, accountabilities, domains, or policies directly during workspace/circle setup mode (new or sparsely populated workspace). In established workspaces with multiple users, governance changes MUST go through the tension/proposal flow (nestr_create_tension + nestr_add_tension_part) so circle members can consent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -579,7 +667,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_nest",
-        description: "Update properties of an existing nest. Use parentId to move a nest (e.g., inbox item to a project). For roles and circles: include accountabilities and domains arrays to update them inline (requires workspaceId). For AI knowledge persistence, create skill-labeled nests under roles/circles instead of using data fields.",
+        description: "Update properties of an existing nest. Use parentId to move a nest (e.g., inbox item to a project). For roles and circles: include accountabilities and domains arrays to update them inline (requires workspaceId). For AI knowledge persistence, create skill-labeled nests under roles/circles instead of using data fields. GOVERNANCE RULE: Only modify governance items (roles, circles, accountabilities, domains, policies) directly during setup mode. In established workspaces, governance changes MUST go through tensions (nestr_create_tension + nestr_add_tension_part).",
         inputSchema: {
             type: "object",
             properties: {
@@ -635,7 +723,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_delete_nest",
-        description: "Delete a nest (use with caution)",
+        description: "Delete a nest (use with caution). GOVERNANCE RULE: To remove governance items (roles, accountabilities, domains, policies) in established workspaces, use nestr_remove_tension_part to propose deletion through the consent process instead.",
         inputSchema: {
             type: "object",
             properties: {
@@ -647,12 +735,12 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_comment",
-        description: "Add a comment to a nest. Use @username to mention someone.",
+        description: "Add a comment to a nest. Supports @mentions using the format @{userId|email|circle|everyone}: @{userId} mentions by user ID, @{email} mentions by any email the user is registered with in Nestr, @{circle} notifies all role fillers in the nearest ancestor circle, @{everyone} is available in the UI but not yet via the API.",
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Nest ID to comment on" },
-                body: { type: "string", description: "Comment text (supports HTML and @mentions)" },
+                body: { type: "string", description: "Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
             },
             required: ["nestId", "body"],
         },
@@ -660,12 +748,12 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_comment",
-        description: "Update an existing comment's text.",
+        description: "Update an existing comment's text. Supports @mentions using the format @{userId|email|circle|everyone}: @{userId} mentions by user ID, @{email} mentions by any email the user is registered with in Nestr, @{circle} notifies all role fillers in the nearest ancestor circle, @{everyone} is available in the UI but not yet via the API.",
         inputSchema: {
             type: "object",
             properties: {
                 commentId: { type: "string", description: "Comment ID to update" },
-                body: { type: "string", description: "Updated comment text (supports HTML and @mentions)" },
+                body: { type: "string", description: "Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
             },
             required: ["commentId", "body"],
         },
@@ -1542,8 +1630,9 @@ async function _handleToolCall(client, name, args) {
                 const nest = await client.getNest(parsed.nestId, {
                     cleanText: true,
                     fieldsMetaData: parsed.fieldsMetaData,
+                    hints: parsed.hints !== false,
                 });
-                return formatResult(nest);
+                return formatResult(enrichHints(nest));
             }
             case "nestr_get_nest_children": {
                 const parsed = schemas.getNestChildren.parse(args);
@@ -1551,8 +1640,9 @@ async function _handleToolCall(client, name, args) {
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
+                    hints: parsed.hints !== false,
                 });
-                return formatResult(completableResponse(compactResponse(children), "children", parsed._listTitle || "Sub-items"));
+                return formatResult(completableResponse(compactResponse(enrichHints(children)), "children", parsed._listTitle || "Sub-items"));
             }
             case "nestr_create_nest": {
                 const parsed = schemas.createNest.parse(args);
@@ -1860,17 +1950,30 @@ async function _handleToolCall(client, name, args) {
             case "nestr_get_me": {
                 const parsed = schemas.getMe.parse(args);
                 try {
-                    const user = await client.getCurrentUser({
+                    let user = await client.getCurrentUser({
                         fullWorkspaces: parsed.fullWorkspaces,
                     });
-                    return formatResult({
+                    // Guard against oversized responses (e.g. many workspaces with large adminUsers arrays).
+                    // If the serialized user exceeds 50KB, retry without fullWorkspaces to avoid
+                    // blowing past MCP client token limits.
+                    const MAX_USER_RESPONSE_BYTES = 50_000;
+                    let droppedFullWorkspaces = false;
+                    if (parsed.fullWorkspaces && JSON.stringify(user).length > MAX_USER_RESPONSE_BYTES) {
+                        user = await client.getCurrentUser({ fullWorkspaces: false });
+                        droppedFullWorkspaces = true;
+                    }
+                    const result = {
                         authMode: "oauth",
                         user,
                         mode: user.bot ? "role-filler" : "assistant",
                         hint: user.bot
                             ? "You are a bot energizing roles. You have no authority as an agent — only through the roles you fill. Act autonomously within your roles' accountabilities. Process tensions proactively."
                             : "You are assisting a human who energizes roles. Defer to them for decisions. Help them articulate tensions and navigate governance.",
-                    });
+                    };
+                    if (droppedFullWorkspaces) {
+                        result.warning = "fullWorkspaces was dropped because the response exceeded the size limit. Use nestr_list_workspaces to browse workspaces individually.";
+                    }
+                    return formatResult(result);
                 }
                 catch (err) {
                     // If the error is from the tokenProvider (expired OAuth session),