@nestr/mcp 0.1.8

package/build/server.js

@@ -0,0 +1,383 @@
+/**
+ * Nestr MCP Server
+ * Core server setup and configuration
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createClientFromEnv } from "./api/client.js";
+import { toolDefinitions, handleToolCall } from "./tools/index.js";
+// Server instructions provide context to AI assistants about what Nestr is and how to use it
+const SERVER_INSTRUCTIONS = `
+Nestr is a work management platform for teams practicing self-organization, Holacracy, Sociocracy, and Teal methodologies.
+
+## Workspace Types
+
+Most workspaces are organizational, representing a self-organized team. Check the workspace's labels to determine the type:
+
+- **Organizational Workspace** (most common): Has the "anchor-circle" label. The workspace IS the anchor circle of a self-organized team using Holacracy/Sociocracy/Teal governance. Contains sub-circles, roles with accountabilities and domains, and collaborative projects.
+- **Personal Workspace**: No "anchor-circle" label. A personal space where an individual tracks their own work and projects.
+
+The specific self-organization methodology is stored in \`workspace.data['self_organisation_type']\` (e.g., "holacracy", "sociocracy", "custom").
+
+## Core Concepts
+
+- **Workspace**: Top-level container - either an organization's anchor circle or a personal workspace
+- **Nest**: The universal building block - can be a task, project, role, circle, meeting, or any work item
+- **Circle**: A self-governing team with defined purpose, roles, and accountabilities (Holacracy/Sociocracy concept)
+- **Role**: A set of responsibilities (accountabilities) and decision rights (domains) that a person energizes
+- **Label**: Tags that define what type of nest something is (e.g., "project", "todo", "meeting", "anchor-circle")
+
+## Nest Model Architecture
+
+Every nest has these **standard fields**:
+- \`_id\` - Unique identifier
+- \`title\` - Display name
+- \`purpose\` - Why this nest exists (especially important for roles/circles)
+- \`description\` - Detailed description (may contain rich text)
+- \`parentId\` - ID of parent nest
+- \`ancestors\` - Array of ancestor IDs (for hierarchy traversal)
+- \`labels\` - Array of label IDs that define what type this nest is
+- \`fields\` - Label-specific custom fields (see below)
+- \`data\` - Miscellaneous data storage for non-field data (e.g., third-party IDs, integration metadata, custom tracking data)
+- \`due\` - Context-dependent date field:
+  - **Project/Task**: Due date
+  - **Role**: Re-election date (when the role assignment should be reviewed)
+  - **Meeting**: Start date/time
+- \`completed\` - Whether this item is completed (for tasks/projects/meetings etc.)
+- \`users\` - Array of user IDs assigned to this nest
+- \`createdAt\`, \`updatedAt\` - Timestamps
+
+### User Assignment
+
+**Important:** When creating tasks or projects, you must explicitly set the \`users\` array to associate work with a person. Placing a nest under a role does NOT automatically assign it to the role filler.
+
+\`\`\`json
+{
+  "parentId": "roleId",
+  "title": "Complete quarterly report",
+  "users": ["userId123"]
+}
+\`\`\`
+
+- \`users: ["userId"]\` - Assign to specific user(s)
+- \`users: []\` or omitted - Unassigned (valid for work under unfilled roles or shared tasks)
+
+**Note:** Accountabilities, domains, and policies never have users assigned - they belong to roles, not people.
+
+### The \`fields\` Property
+
+The \`fields\` object holds custom data defined by labels. Fields are **namespaced by the label that defines them**:
+
+\`\`\`json
+{
+  "fields": {
+    "project.status": "Current",
+    "role.electable-role": true,
+    "metric.frequency": "Weekly",
+    "circle.strategy": "Focus on enterprise clients"
+  }
+}
+\`\`\`
+
+**Key project statuses** (in \`fields['project.status']\`):
+- \`Future\` - Planned but not started
+- \`Current\` - Actively being worked on
+- \`Waiting\` - Blocked or on hold
+- \`Done\` - Completed
+
+**Circle strategy** (in \`fields['circle.strategy']\`):
+A strategy that all roles within the circle must follow. Sub-circle strategies must align with and support the super-circle's strategy.
+
+**Important:** Label field schemas can be customized at the workspace or circle level. This means the available fields and their options may vary between different parts of the organization hierarchy. Always check what fields are actually present on a nest rather than assuming a fixed schema.
+
+### Hierarchical Purpose
+
+The \`purpose\` field follows a strict hierarchy:
+- The **anchor circle's purpose** is the purpose of the entire organization
+- Each **sub-circle's purpose** must contribute to its parent circle's purpose
+- Each **role's purpose** must contribute to its circle's purpose
+
+This cascades through the entire hierarchy, which may be many layers deep. When creating or updating purposes, ensure they align with and serve the parent's purpose.
+
+## Best Practices
+
+1. **Start by listing workspaces** to get the workspace ID and check if it has the "anchor-circle" label
+2. **Use search** to find specific items rather than browsing through hierarchies
+3. **Check labels** to understand what type of nest you're working with
+4. **Use @mentions** in comments to notify team members
+5. **Respect the hierarchy**: nests live under parents (workspace → circle → role/project → task)
+6. **Check circle strategy and purpose** before creating work or governance:
+   - Fetch the parent circle to review its \`purpose\` and \`fields['circle.strategy']\`
+   - Ensure new projects and tasks align with and serve the circle's strategy
+   - Use strategy and purpose to prioritize work and define clear outcomes
+   - When proposing governance changes, consider how they support the circle's purpose
+7. **Use \`data.botContext\` to maintain AI memory** across sessions:
+   - Any nest can store AI context in \`data.botContext\` (markdown format) to persist learned information
+   - Update via \`nestr_update_nest\` with \`{ data: { botContext: "# Context\\n\\n..." } }\`
+   - Check for existing \`data.botContext\` when working on a nest to pick up prior context
+   - **Especially valuable for roles and circles**: Store information relevant to the *role*, not the person filling it (e.g., key contacts, recurring processes, domain knowledge). This context transfers automatically when the role is assigned to a different user.
+   - Enables future agentic work: AI agents can autonomously energize roles, maintaining continuity as they learn preferences, make decisions, and accumulate role-specific knowledge over time
+
+## Important Labels
+
+Labels define what type a nest is. The API strips the "circleplus-" prefix, so use labels without it.
+
+**Governance Structure:**
+- \`anchor-circle\` - The workspace itself when it's an organization
+- \`circle\` - A sub-circle/team within the organization
+- \`role\` - A role with accountabilities and domains
+- \`accountability\` - An ongoing activity the role is responsible for performing (Holacracy: "an ongoing activity that the Role will enact")
+- \`domain\` - An area the role has exclusive control over; others must get permission to impact it (Holacracy: "something the Role may exclusively control on behalf of the Organization")
+- \`policy\` - A grant or restriction of authority affecting how others interact with a domain or process. Can live on a domain, role, or circle directly.
+
+**Note:** Accountabilities, domains, and policies are child-nests of roles/circles. Use \`nestr_get_circle_roles\` or \`nestr_get_nest_children\` to retrieve them. The generic \`nestr_search\` won't return them by default.
+
+**Meetings & Operations:**
+- \`metric\` - A metric tracked by a role/circle
+- \`checklist\` - A recurring checklist item
+- \`governance\` - A governance meeting
+- \`tactical\` - A tactical/operational meeting
+
+**OKRs & Goals:**
+- \`goal\` - An Objective (the O in OKR)
+- \`result\` - A Key Result (the KR in OKR)
+
+**Work Tracking:**
+- \`project\` - An outcome requiring multiple steps to complete. Define in past tense as what "done" looks like (e.g., "Website redesign launched", "Q1 report published"). Has status: Future/Current/Waiting/Done.
+- *(no label)* - A nest without labels is a todo/action: a single, concrete action that can be done in one sitting (e.g., "Call supplier about pricing", "Draft intro paragraph"). The next physical step to move something forward.
+- \`note\` - A simple note
+- \`meeting\` - A calendar meeting
+- \`prepared-tension\` - A tension (gap between current and desired state). Used for meeting agenda items, async governance proposals, and general tension processing. Central to Holacracy practice.
+
+## Search Query Syntax
+
+The \`nestr_search\` tool supports powerful query operators. Combine multiple operators with spaces (AND logic) or use commas within an operator (OR logic).
+
+### Common Search Operators
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| \`label:\` | \`label:role\` | Filter by label type |
+| \`label:!\` | \`label:!project\` | Exclude label |
+| \`assignee:\` | \`assignee:me\` | Filter by assignee (use \`me\` for current user) |
+| \`completed:\` | \`completed:false\` | Filter by completion status |
+| \`has:\` | \`has:due\` | Items with a property (due, children, etc.) |
+| \`depth:\` | \`depth:1\` | Limit search depth (1 = direct children only) |
+| \`createdby:\` | \`createdby:me\` | Filter by creator |
+
+### Field Value Search
+
+Search by label-specific field values using \`label->field:value\`:
+- \`project->status:Current\` - Projects with status "Current"
+- \`project->status:Current,Future\` - Status is Current OR Future
+- \`project->status:!Done\` - Status is NOT Done
+
+### Search Examples
+
+\`\`\`
+label:role
+  -> Find all roles
+
+label:project assignee:me completed:false
+  -> My incomplete projects
+
+label:project project->status:Current
+  -> Projects with status "Current"
+
+label:circle depth:1
+  -> Direct sub-circles only
+
+has:due completed:false
+  -> Incomplete items with due dates
+
+label:meeting has:!completed
+  -> Meetings not yet completed
+
+label:policy spending
+  -> Policies mentioning spending
+
+label:policy budget cost expense
+  -> Policies about budgets, costs, or expenses
+
+label:accountability customer
+  -> Accountabilities related to customers
+\`\`\`
+
+### Additional Operators
+
+- \`parent-label:circle\` - Items under a circle
+- \`in:nestId\` - Search within specific nest
+- \`updated-date:past_7_days\` - Recently updated (also: past_30_days, this_month, etc.)
+- \`type:comment\` - Search comments/posts
+- \`deleted:true\` - Include deleted items
+
+## Linking to the Web App
+
+When sharing results with users, provide clickable links to the Nestr web app.
+
+**Base URL:** \`https://app.nestr.io\`
+
+### Link Formats
+
+| Format | Example | Use Case |
+|--------|---------|----------|
+| \`/n/{nestId}\` | \`/n/abc123\` | Direct link to any nest |
+| \`/n/{nestId}/{childId}\` | \`/n/circleId/roleId\` | Show child in context (opens detail pane on desktop) |
+| \`/n/{workspaceId}?s=1#hash\` | \`/n/wsId?s=1#users\` | Workspace admin settings |
+
+### Context Links (Detail Pane)
+
+Use the two-ID format to show items in context:
+- \`/n/{circleId}/{roleId}\` - Role within its circle
+- \`/n/{roleId}/{projectId}\` - Project owned by a role
+- \`/n/{projectId}/{taskId}\` - Task within its project
+
+### Cross-Workspace Views
+
+These pages show items across all workspaces for the current user:
+- \`/roles\` - All roles this user fills
+- \`/projects\` - All projects assigned to this user
+
+### User Profile
+
+View a user's roles within a specific workspace:
+- \`/profile/{userId}?cId={workspaceId}\` - User's roles in that workspace
+
+This works for viewing colleagues too - replace userId to see what roles they fill in the same workspace.
+
+### Admin Settings Hashes
+
+For workspace admins, link to settings with \`/n/{workspaceId}?s=1\` plus:
+- \`#users\` - Team members
+- \`#labels\` - Label configuration
+- \`#workspace-apps\` - Enabled apps/features
+- \`#plan\` - Subscription plan
+
+## Inbox (Quick Capture)
+
+The inbox is a collection point for capturing "stuff" that still needs processing. Use it for:
+- Quick capture of thoughts, ideas, or tasks without deciding where they belong
+- Collecting items that need clarification before becoming projects or actions
+- Temporary holding area before organizing into the proper location
+
+**Note:** Inbox tools require OAuth authentication (user-scoped token). They won't work with workspace API keys.
+
+### Inbox Workflow
+
+1. **Capture**: Use \`nestr_create_inbox_item\` to quickly add items without organizing
+2. **Review**: Use \`nestr_list_inbox\` to see items needing processing
+3. **Process**: For each item, decide:
+   - **Delete**: If not needed, mark \`completed: true\`
+   - **Do it**: If quick (<2 min), do it now and mark complete
+   - **Organize**: Move to appropriate location with \`nestr_update_nest\` by setting \`parentId\`
+
+### Moving Items Out of Inbox
+
+To clarify/organize an inbox item, use \`nestr_update_nest\` to change its \`parentId\`:
+
+\`\`\`json
+{
+  "nestId": "inboxItemId",
+  "parentId": "projectOrRoleId"
+}
+\`\`\`
+
+This moves the item from inbox to the specified project, role, or other location. A nest without any labels is the basic building block - it's completable and acts as a todo/action item.
+
+## Common Workflows
+
+- **Task Management**: Create nests (no label needed for basic todos), update completed status, add comments for updates
+- **Project Tracking**: List projects, get children to see tasks, check insights for metrics
+- **Team Structure**: List circles to see teams, get roles to understand accountabilities and domains
+- **Finding Accountabilities/Domains**: Use \`nestr_get_circle_roles\` for a circle's roles with their accountabilities, or \`nestr_get_nest_children\` on a specific role
+- **Search & Discovery**: Use search with operators like \`label:role\` or \`assignee:me completed:false\`
+- **Quick Capture**: Use inbox tools to capture thoughts without organizing, then process later
+`.trim();
+export function createServer(config = {}) {
+    const client = config.client || createClientFromEnv();
+    const server = new Server({
+        name: "nestr-mcp",
+        version: "0.1.0",
+        description: "Manage tasks, projects, roles, and circles for self-organizing teams. Built for Holacracy, Sociocracy, and Teal organizations practicing role-based governance and distributed authority. AI-native tool for the future of work - automate workflows and run your autonomous team with AI assistants.",
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    // Register tool list handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: toolDefinitions };
+    });
+    // Register tool call handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return handleToolCall(client, name, args || {});
+    });
+    // Register resource list handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: "nestr://workspaces",
+                    name: "My Workspaces",
+                    description: "List of Nestr workspaces you have access to",
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Register resource read handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === "nestr://workspaces") {
+            const workspaces = await client.listWorkspaces({ cleanText: true });
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(workspaces, null, 2),
+                    },
+                ],
+            };
+        }
+        // Handle dynamic workspace resources
+        const workspaceMatch = uri.match(/^nestr:\/\/workspace\/([^/]+)\/(.+)$/);
+        if (workspaceMatch) {
+            const [, workspaceId, resource] = workspaceMatch;
+            switch (resource) {
+                case "structure": {
+                    const circles = await client.listCircles(workspaceId, { cleanText: true });
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(circles, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case "projects": {
+                    const projects = await client.getWorkspaceProjects(workspaceId, {
+                        cleanText: true,
+                    });
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(projects, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+        }
+        throw new Error(`Unknown resource: ${uri}`);
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/build/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}