@nestr/mcp 0.1.24 → 0.1.27

package/README.md

@@ -71,34 +71,93 @@ Ask your AI assistant things like:
 
 ## Available Tools
 
+### Workspace & Search
+
 | Tool | Description |
 |------|-------------|
 | `nestr_list_workspaces` | List accessible workspaces |
 | `nestr_get_workspace` | Get workspace details |
+| `nestr_create_workspace` | Create a new workspace (OAuth only) |
 | `nestr_search` | Search for nests (tasks, projects, roles) |
+
+### Nests (Tasks, Projects, Roles)
+
+| Tool | Description |
+|------|-------------|
 | `nestr_get_nest` | Get details of a specific nest |
 | `nestr_get_nest_children` | Get child nests |
 | `nestr_create_nest` | Create a new nest |
 | `nestr_update_nest` | Update nest properties |
 | `nestr_delete_nest` | Delete a nest |
+| `nestr_reorder_nest` | Reorder a nest relative to another |
+| `nestr_bulk_reorder` | Bulk reorder multiple nests |
+
+### Comments & Discussion
+
+| Tool | Description |
+|------|-------------|
 | `nestr_add_comment` | Add a comment to a nest |
 | `nestr_get_comments` | Get comments/discussion on a nest |
+
+### Organization Structure
+
+| Tool | Description |
+|------|-------------|
 | `nestr_list_circles` | List organizational circles |
 | `nestr_get_circle` | Get circle details |
 | `nestr_get_circle_roles` | Get roles in a circle |
 | `nestr_list_roles` | List all roles |
 | `nestr_list_users` | List workspace members |
 | `nestr_get_user` | Get user details |
-| `nestr_list_labels` | List available labels |
+
+### Labels & Projects
+
+| Tool | Description |
+|------|-------------|
+| `nestr_list_labels` | List workspace labels |
 | `nestr_get_label` | Get label details |
 | `nestr_get_projects` | List projects with status |
+
+### Insights & Apps
+
+| Tool | Description |
+|------|-------------|
 | `nestr_get_insights` | Get workspace metrics |
 | `nestr_get_insight_history` | Get historical trend data for a metric |
 | `nestr_get_workspace_apps` | List enabled apps/features |
-| `nestr_list_inbox` | List items in user's inbox (OAuth only) |
-| `nestr_create_inbox_item` | Quick capture to inbox (OAuth only) |
-| `nestr_get_inbox_item` | Get inbox item details (OAuth only) |
-| `nestr_update_inbox_item` | Update inbox item (OAuth only) |
+
+### Personal (OAuth only)
+
+| Tool | Description |
+|------|-------------|
+| `nestr_list_inbox` | List items in user's inbox |
+| `nestr_create_inbox_item` | Quick capture to inbox |
+| `nestr_get_inbox_item` | Get inbox item details |
+| `nestr_update_inbox_item` | Update inbox item |
+| `nestr_reorder_inbox` | Reorder inbox items |
+| `nestr_list_personal_labels` | List user's personal labels |
+| `nestr_create_personal_label` | Create a personal label |
+| `nestr_get_daily_plan` | Get items marked for today |
+
+## MCP Apps (Interactive UI)
+
+MCP Apps are interactive UI components that can be embedded in MCP clients that support them (like Claude.ai). They provide rich, visual interfaces for working with Nestr data.
+
+### Completable List
+
+**Resource URI:** `ui://nestr/completable-list`
+
+An interactive list for viewing and completing tasks and projects.
+
+**Features:**
+- Projects show a box icon, todos show a checkbox
+- Check items to mark them complete (strikethrough)
+- Inline editing of titles (auto-saves)
+- Drag-and-drop reordering
+- Shows parent path for context
+- Quick link to open item in Nestr
+
+**Usage:** When an AI assistant returns task or project results, supporting clients can render this interactive UI instead of plain text, allowing you to complete items, edit titles, and reorder directly in the chat.
 
 ## Authentication
 
@@ -116,14 +175,54 @@ API keys provide full workspace access and work with the local npm package. See
 
 ## Environment Variables
 
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `NESTR_API_KEY` | Nestr API key (full workspace access) | Yes* |
-| `NESTR_OAUTH_TOKEN` | OAuth token (respects user permissions) | Yes* |
-| `NESTR_API_BASE` | API base URL (default: `https://app.nestr.io/api`) | No |
+### Authentication (Required)
+
+| Variable | Description |
+|----------|-------------|
+| `NESTR_API_KEY` | Nestr API key (full workspace access) |
+| `NESTR_OAUTH_TOKEN` | OAuth token (respects user permissions) |
 
 \* Either `NESTR_API_KEY` or `NESTR_OAUTH_TOKEN` is required for local usage.
 
+### Configuration (Optional)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NESTR_API_BASE` | API base URL | `https://app.nestr.io/api` |
+
+### Hosting/Server (HTTP transport only)
+
+These are used when running the HTTP server for hosted deployments:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP server port | `3000` |
+| `NESTR_OAUTH_CLIENT_ID` | OAuth client ID for hosted OAuth flow | - |
+| `NESTR_OAUTH_CLIENT_SECRET` | OAuth client secret | - |
+| `OAUTH_ENCRYPTION_KEY` | 32-byte base64 key for encrypting OAuth sessions at rest | - |
+| `GTM_ID` | Google Tag Manager container ID for landing page | - |
+
+### Analytics (Optional)
+
+Server-side analytics options:
+
+**GA4 Measurement Protocol:**
+
+| Variable | Description |
+|----------|-------------|
+| `GA4_MEASUREMENT_ID` | GA4 Measurement ID (e.g., `G-XXXXXXXXXX`) |
+| `GA4_API_SECRET` | Measurement Protocol API secret |
+| `GA4_DEBUG` | Set to `true` to validate events without recording |
+
+**Note:** Both `GA4_MEASUREMENT_ID` and `GA4_API_SECRET` are required for GA4 tracking. If only the measurement ID is set, a warning is logged and tracking is disabled.
+
+**MCPcat (MCP-specific analytics):**
+
+| Variable | Description |
+|----------|-------------|
+| `MCPCAT_PROJECT_ID` | MCPcat project ID (from [mcpcat.io](https://mcpcat.io)) |
+| `MCPCAT_ENABLE_REPLAY` | Enable session replay (default: `false`) |
+
 ## Development
 
 ```bash

package/build/analytics/ga4.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GA4 Analytics via Measurement Protocol
+ *
+ * Implements the EventTracker interface for Google Analytics 4.
+ * Uses the Measurement Protocol for server-side event tracking.
+ *
+ * Environment variables:
+ * - GA4_MEASUREMENT_ID: GA4 measurement ID (e.g., G-XXXXXXXXXX)
+ * - GA4_API_SECRET: Measurement Protocol API secret
+ * - GA4_DEBUG: Set to "true" to use debug endpoint (validates but doesn't record)
+ */
+export {};
+//# sourceMappingURL=ga4.d.ts.map

package/build/analytics/ga4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ga4.d.ts","sourceRoot":"","sources":["../../src/analytics/ga4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/build/analytics/ga4.js

@@ -0,0 +1,135 @@
+/**
+ * GA4 Analytics via Measurement Protocol
+ *
+ * Implements the EventTracker interface for Google Analytics 4.
+ * Uses the Measurement Protocol for server-side event tracking.
+ *
+ * Environment variables:
+ * - GA4_MEASUREMENT_ID: GA4 measurement ID (e.g., G-XXXXXXXXXX)
+ * - GA4_API_SECRET: Measurement Protocol API secret
+ * - GA4_DEBUG: Set to "true" to use debug endpoint (validates but doesn't record)
+ */
+import { analytics, } from "./index.js";
+// GA4 configuration from environment
+const GA4_MEASUREMENT_ID = process.env.GA4_MEASUREMENT_ID;
+const GA4_API_SECRET = process.env.GA4_API_SECRET;
+const GA4_ENDPOINT = "https://www.google-analytics.com/mp/collect";
+// Debug endpoint for testing (validates but doesn't record)
+const GA4_DEBUG_ENDPOINT = "https://www.google-analytics.com/debug/mp/collect";
+const DEBUG_MODE = process.env.GA4_DEBUG === "true";
+/**
+ * Send event(s) to GA4 Measurement Protocol
+ * Non-blocking - failures are logged but don't throw
+ */
+async function sendToGA4(payload) {
+    const endpoint = DEBUG_MODE ? GA4_DEBUG_ENDPOINT : GA4_ENDPOINT;
+    const url = `${endpoint}?measurement_id=${GA4_MEASUREMENT_ID}&api_secret=${GA4_API_SECRET}`;
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+        if (DEBUG_MODE) {
+            const debugResponse = await response.json();
+            console.log("[GA4] Debug response:", JSON.stringify(debugResponse, null, 2));
+        }
+        else if (!response.ok) {
+            console.error(`[GA4] Failed to send event: ${response.status}`);
+        }
+    }
+    catch (error) {
+        console.error("[GA4] Error sending event:", error);
+    }
+}
+/**
+ * Build and send an event
+ */
+function trackEvent(context, eventName, params) {
+    const payload = {
+        client_id: context.clientId,
+        events: [
+            {
+                name: eventName,
+                params: {
+                    ...params,
+                    app: "nestr_mcp",
+                    mcp_client: context.mcpClient,
+                    transport: context.transport,
+                    engagement_time_msec: 100,
+                },
+            },
+        ],
+    };
+    if (context.userId) {
+        payload.user_id = context.userId;
+    }
+    // Fire and forget
+    sendToGA4(payload).catch(() => { });
+}
+/**
+ * GA4 EventTracker implementation
+ */
+class GA4Tracker {
+    name = "GA4";
+    initialize() {
+        // Validate configuration
+        if (GA4_MEASUREMENT_ID && !GA4_API_SECRET) {
+            console.warn("[GA4] Warning: GA4_MEASUREMENT_ID is set but GA4_API_SECRET is missing. " +
+                "GA4 analytics is disabled. Get your API secret from: " +
+                "GA4 Admin → Data Streams → Measurement Protocol API secrets");
+            throw new Error("GA4 configuration incomplete");
+        }
+        if (!GA4_MEASUREMENT_ID || !GA4_API_SECRET) {
+            throw new Error("GA4 not configured");
+        }
+        console.log(`[GA4] Initialized with measurement ID: ${GA4_MEASUREMENT_ID}${DEBUG_MODE ? " (debug mode)" : ""}`);
+    }
+    trackSessionStart(context, params) {
+        trackEvent(context, "mcp_session_start", {
+            has_token: params?.hasToken,
+            auth_method: params?.authMethod,
+        });
+    }
+    trackToolCall(context, params) {
+        trackEvent(context, "mcp_tool_call", {
+            tool_name: params.toolName,
+            workspace_id: params.workspaceId,
+            success: params.success,
+            error_code: params.errorCode,
+        });
+    }
+    trackOAuthStart(context, params) {
+        trackEvent(context, "mcp_oauth_start", {
+            client_consumer: params?.clientConsumer,
+        });
+    }
+    trackOAuthComplete(context, params) {
+        trackEvent(context, "mcp_oauth_complete", {
+            is_new_user: params?.isNewUser,
+        });
+    }
+    trackSessionEnd(context, params) {
+        trackEvent(context, "mcp_session_end", {
+            duration_seconds: params?.duration,
+            tool_call_count: params?.toolCallCount,
+        });
+    }
+    trackError(context, params) {
+        trackEvent(context, "mcp_error", {
+            error_type: params.errorType,
+            error_message: params.errorMessage?.slice(0, 100),
+            tool_name: params.toolName,
+        });
+    }
+}
+// Auto-register GA4 tracker if configured
+try {
+    analytics.register(new GA4Tracker());
+}
+catch {
+    // Not configured or incomplete - that's fine, warning already logged if needed
+}
+//# sourceMappingURL=ga4.js.map

package/build/analytics/ga4.js.map

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

package/build/analytics/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Analytics Event Tracking
+ *
+ * Generic event tracking interface with pluggable implementations.
+ * Trackers register themselves and all receive events.
+ *
+ * Usage:
+ *   import { analytics, AnalyticsContext } from "./analytics/index.js";
+ *   analytics.trackSessionStart(context, { hasToken: true });
+ */
+/**
+ * Analytics context for an MCP session
+ */
+export interface AnalyticsContext {
+    /** Client ID for session tracking */
+    clientId: string;
+    /** User ID for cross-session tracking (e.g., Nestr user._id) */
+    userId?: string;
+    /** MCP client name (e.g., "claude-desktop", "cursor") */
+    mcpClient?: string;
+    /** Transport type */
+    transport: "http" | "stdio";
+}
+/**
+ * Session start event parameters
+ */
+export interface SessionStartParams {
+    hasToken?: boolean;
+    authMethod?: "oauth" | "api_key";
+}
+/**
+ * Tool call event parameters
+ */
+export interface ToolCallParams {
+    toolName: string;
+    workspaceId?: string;
+    success?: boolean;
+    errorCode?: string;
+}
+/**
+ * OAuth start event parameters
+ */
+export interface OAuthStartParams {
+    clientConsumer?: string;
+}
+/**
+ * OAuth complete event parameters
+ */
+export interface OAuthCompleteParams {
+    isNewUser?: boolean;
+}
+/**
+ * Session end event parameters
+ */
+export interface SessionEndParams {
+    duration?: number;
+    toolCallCount?: number;
+}
+/**
+ * Error event parameters
+ */
+export interface ErrorParams {
+    errorType: string;
+    errorMessage?: string;
+    toolName?: string;
+}
+/**
+ * Event tracker interface - implement this to add a new analytics provider
+ */
+export interface EventTracker {
+    /** Unique name for this tracker (for logging) */
+    readonly name: string;
+    /** Called when tracker is registered - use for startup validation */
+    initialize?(): void;
+    /** Track MCP session start */
+    trackSessionStart(context: AnalyticsContext, params?: SessionStartParams): void;
+    /** Track MCP tool call */
+    trackToolCall(context: AnalyticsContext, params: ToolCallParams): void;
+    /** Track OAuth flow start */
+    trackOAuthStart(context: AnalyticsContext, params?: OAuthStartParams): void;
+    /** Track OAuth flow completion */
+    trackOAuthComplete(context: AnalyticsContext, params?: OAuthCompleteParams): void;
+    /** Track MCP session end */
+    trackSessionEnd(context: AnalyticsContext, params?: SessionEndParams): void;
+    /** Track errors */
+    trackError(context: AnalyticsContext, params: ErrorParams): void;
+}
+/**
+ * Analytics registry - manages multiple event trackers
+ */
+declare class Analytics {
+    private trackers;
+    /**
+     * Register an event tracker
+     */
+    register(tracker: EventTracker): void;
+    /**
+     * Check if any trackers are registered
+     */
+    isEnabled(): boolean;
+    /**
+     * Generate a new client ID for session tracking
+     */
+    generateClientId(): string;
+    /**
+     * Track session start across all registered trackers
+     */
+    trackSessionStart(context: AnalyticsContext, params?: SessionStartParams): void;
+    /**
+     * Track tool call across all registered trackers
+     */
+    trackToolCall(context: AnalyticsContext, params: ToolCallParams): void;
+    /**
+     * Track OAuth start across all registered trackers
+     */
+    trackOAuthStart(context: AnalyticsContext, params?: OAuthStartParams): void;
+    /**
+     * Track OAuth complete across all registered trackers
+     */
+    trackOAuthComplete(context: AnalyticsContext, params?: OAuthCompleteParams): void;
+    /**
+     * Track session end across all registered trackers
+     */
+    trackSessionEnd(context: AnalyticsContext, params?: SessionEndParams): void;
+    /**
+     * Track error across all registered trackers
+     */
+    trackError(context: AnalyticsContext, params: ErrorParams): void;
+}
+/**
+ * Singleton analytics instance
+ */
+export declare const analytics: Analytics;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/analytics/index.d.ts.map

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

package/build/analytics/index.js

@@ -0,0 +1,125 @@
+/**
+ * Analytics Event Tracking
+ *
+ * Generic event tracking interface with pluggable implementations.
+ * Trackers register themselves and all receive events.
+ *
+ * Usage:
+ *   import { analytics, AnalyticsContext } from "./analytics/index.js";
+ *   analytics.trackSessionStart(context, { hasToken: true });
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Analytics registry - manages multiple event trackers
+ */
+class Analytics {
+    trackers = [];
+    /**
+     * Register an event tracker
+     */
+    register(tracker) {
+        try {
+            tracker.initialize?.();
+            this.trackers.push(tracker);
+            console.log(`[Analytics] Registered tracker: ${tracker.name}`);
+        }
+        catch (error) {
+            console.error(`[Analytics] Failed to register tracker ${tracker.name}:`, error);
+        }
+    }
+    /**
+     * Check if any trackers are registered
+     */
+    isEnabled() {
+        return this.trackers.length > 0;
+    }
+    /**
+     * Generate a new client ID for session tracking
+     */
+    generateClientId() {
+        return randomUUID();
+    }
+    /**
+     * Track session start across all registered trackers
+     */
+    trackSessionStart(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackSessionStart(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackSessionStart error:`, error);
+            }
+        }
+    }
+    /**
+     * Track tool call across all registered trackers
+     */
+    trackToolCall(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackToolCall(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackToolCall error:`, error);
+            }
+        }
+    }
+    /**
+     * Track OAuth start across all registered trackers
+     */
+    trackOAuthStart(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackOAuthStart(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackOAuthStart error:`, error);
+            }
+        }
+    }
+    /**
+     * Track OAuth complete across all registered trackers
+     */
+    trackOAuthComplete(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackOAuthComplete(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackOAuthComplete error:`, error);
+            }
+        }
+    }
+    /**
+     * Track session end across all registered trackers
+     */
+    trackSessionEnd(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackSessionEnd(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackSessionEnd error:`, error);
+            }
+        }
+    }
+    /**
+     * Track error across all registered trackers
+     */
+    trackError(context, params) {
+        for (const tracker of this.trackers) {
+            try {
+                tracker.trackError(context, params);
+            }
+            catch (error) {
+                console.error(`[Analytics] ${tracker.name} trackError error:`, error);
+            }
+        }
+    }
+}
+/**
+ * Singleton analytics instance
+ */
+export const analytics = new Analytics();
+//# sourceMappingURL=index.js.map

package/build/analytics/index.js.map

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

package/build/api/client.d.ts

@@ -116,6 +116,22 @@ export declare class NestrClient {
         cleanText?: boolean;
     }): Promise<Nest[]>;
     getWorkspace(workspaceId: string, cleanText?: boolean): Promise<Nest>;
+    createWorkspace(options: {
+        title: string;
+        purpose?: string;
+        configuration?: {
+            /** 'collaborate' for team workspace, 'personal' for individual workspace */
+            collaborators?: 'collaborate' | 'personal';
+            /** Self-organization model */
+            governance?: 'holacracy' | 'sociocracy' | 'roles_circles';
+            /** Subscription plan for collaborative workspaces */
+            plan?: 'plan_starter' | 'plan_pro';
+            /** Optional apps to enable */
+            variableApps?: Array<'okr' | 'feedback' | 'insights'>;
+            /** Layout style (personal workspaces only) */
+            layout?: 'board' | 'list';
+        };
+    }): Promise<Nest>;
     searchWorkspace(workspaceId: string, search: string, options?: {
         limit?: number;
         page?: number;
@@ -126,7 +142,12 @@ export declare class NestrClient {
         page?: number;
         cleanText?: boolean;
     }): Promise<Nest[]>;
-    getNest(nestId: string, cleanText?: boolean): Promise<Nest>;
+    getNest(nestId: string, options?: {
+        cleanText?: boolean;
+        fieldsMetaData?: boolean;
+    }): Promise<Nest & {
+        fieldsMetaData?: Record<string, unknown>;
+    }>;
     getNestChildren(nestId: string, options?: {
         limit?: number;
         page?: number;
@@ -235,6 +256,57 @@ export declare class NestrClient {
         completed: boolean;
         data: Record<string, unknown>;
     }>): Promise<Nest>;
+    /**
+     * List the current user's personal labels.
+     * Requires OAuth token (user-scoped) - does not work with workspace API keys.
+     */
+    listPersonalLabels(): Promise<Label[]>;
+    /**
+     * Create a new personal label for the current user.
+     * Requires OAuth token (user-scoped) - does not work with workspace API keys.
+     */
+    createPersonalLabel(data: {
+        title: string;
+        description?: string;
+        color?: string;
+        icon?: string;
+    }): Promise<Label>;
+    /**
+     * Get the user's daily plan - items marked with the 'now' label.
+     * Requires OAuth token (user-scoped) - does not work with workspace API keys.
+     * Note: Only returns items from inbox and in-scope workspaces.
+     */
+    getDailyPlan(): Promise<Nest[]>;
+    /**
+     * Reorder a nest by positioning it before or after another nest.
+     * Updates searchOrder (and order if both nests share the same parent).
+     */
+    reorderNest(nestId: string, position: "before" | "after", relatedNestId: string): Promise<Nest & {
+        searchOrder?: number;
+        order?: number;
+    }>;
+    /**
+     * Bulk reorder nests by providing an array of nest IDs in the desired order.
+     * Updates searchOrder for all nests and order for nests sharing the same parent.
+     */
+    bulkReorder(workspaceId: string, nestIds: string[]): Promise<Array<Nest & {
+        searchOrder?: number;
+        order?: number;
+    }>>;
+    /**
+     * Reorder inbox items by providing an array of item IDs in the desired order.
+     * Requires OAuth token.
+     */
+    reorderInbox(nestIds: string[]): Promise<Array<Nest & {
+        searchOrder?: number;
+        order?: number;
+    }>>;
+    /**
+     * Get the current authenticated user's info.
+     * Requires OAuth token - does not work with workspace API keys.
+     * Used for analytics to get user_id for session stitching.
+     */
+    getCurrentUser(): Promise<User>;
 }
 /**
  * Factory function to create client from environment variables