@attrove/mcp 0.1.7 → 0.1.9

package/README.md

@@ -16,14 +16,29 @@ pnpm add @attrove/mcp
 
 ### Claude Desktop
 
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Claude Desktop supports two transport options:
+
+**HTTP transport (recommended)** — uses OAuth 2.1, no API key needed:
+
+```json
+{
+  "mcpServers": {
+    "attrove": {
+      "type": "streamable-http",
+      "url": "https://api.attrove.com/mcp"
+    }
+  }
+}
+```
+
+**Stdio transport** — add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
     "attrove": {
       "command": "npx",
-      "args": ["@attrove/mcp"],
+      "args": ["-y", "@attrove/mcp@latest"],
       "env": {
         "ATTROVE_API_KEY": "sk_...",
         "ATTROVE_USER_ID": "user-uuid"
@@ -44,7 +59,7 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
   "mcpServers": {
     "attrove": {
       "command": "npx",
-      "args": ["@attrove/mcp"],
+      "args": ["-y", "@attrove/mcp@latest"],
       "env": {
         "ATTROVE_API_KEY": "sk_...",
         "ATTROVE_USER_ID": "user-uuid"
@@ -66,6 +81,33 @@ export ATTROVE_API_KEY="sk_..."
 export ATTROVE_USER_ID="user-uuid"
 ```
 
+### ChatGPT (via HTTP endpoint)
+
+ChatGPT and other AI assistants that support MCP connectors can connect via the hosted HTTP endpoint.
+
+> **Note:** ChatGPT's connector interface may change over time. If these steps don't match your experience, refer to [OpenAI's current documentation](https://help.openai.com) for the latest instructions.
+
+**Basic requirements:**
+- HTTP endpoint URL: `https://api.attrove.com/mcp`
+- Authentication: Bearer token (`sk_...`)
+- Custom header: `X-Attrove-User-Id` with your user UUID
+
+**Example setup steps (may vary):**
+1. Open ChatGPT Settings → **Connectors** → Enable **Developer Mode**
+2. Click **Create Connector** and configure:
+   - **Name:** `Attrove`
+   - **URL:** `https://api.attrove.com/mcp`
+   - **Authentication:** Bearer token
+   - **Token:** Your API key (`sk_...`)
+3. Add custom header:
+   - **Header:** `X-Attrove-User-Id`
+   - **Value:** Your user ID (UUID)
+
+Once connected, you can ask ChatGPT questions like:
+- "What emails need my attention this week?"
+- "Summarize my meeting with the marketing team"
+- "What has John been asking about lately?"
+
 ### Direct CLI Usage
 
 ```bash
@@ -99,8 +141,8 @@ Ask questions about the user's communications and get AI-generated answers.
 
 **Parameters:**
 - `query` (required): The question to ask
-- `integration_ids` (optional): Filter to specific integration IDs (UUIDs, e.g., `["550e8400-e29b-41d4-a716-446655440000"]`)
-- `include_sources` (optional): Include source snippets
+- `integration_ids` (optional): Filter to specific integration IDs (array of UUID strings)
+- `include_sources` (optional): Include source snippets in the response
 
 **Example prompts:**
 - "What did Sarah say about the Q4 budget?"
@@ -118,7 +160,7 @@ Search for specific messages or conversations.
 - `after_date` (optional): Only messages after this date (ISO 8601)
 - `before_date` (optional): Only messages before this date
 - `sender_domains` (optional): Filter by sender domains
-- `include_body_text` (optional): Include message content (default: true)
+- `include_body_text` (optional): Include message content in results (default: true, bodies truncated to 200 characters)
 
 **Example prompts:**
 - "Find all emails about the product launch"
@@ -136,6 +178,37 @@ List the user's connected integrations.
 - "What services are connected?"
 - "Show me my integrations"
 
+### `attrove_events`
+
+List calendar events from the user's connected calendar accounts.
+
+**Parameters:**
+- `start_date` (optional): Start of date range (ISO 8601)
+- `end_date` (optional): End of date range (ISO 8601)
+- `limit` (optional): Max events to return (default 25, max 100)
+
+**Example prompts:**
+- "What's on my calendar today?"
+- "Do I have any meetings tomorrow?"
+- "When is my next meeting with Sarah?"
+- "What's my schedule for Friday?"
+
+### `attrove_meetings`
+
+List meetings with AI-generated summaries and action items.
+
+**Parameters:**
+- `start_date` (optional): Start of date range (ISO 8601)
+- `end_date` (optional): End of date range (ISO 8601)
+- `provider` (optional): Filter by meeting provider (`google_meet`, `zoom`, `teams`)
+- `limit` (optional): Max meetings to return (default 10, max 50)
+
+**Example prompts:**
+- "What happened in my last meeting?"
+- "Summarize yesterday's standup"
+- "What are the action items from the product review?"
+- "Show me my recent meetings"
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -165,6 +238,77 @@ await startServer({
 });
 ```
 
+### HTTP Endpoint (Hosted)
+
+For AI assistants that connect via HTTP (like ChatGPT), use the hosted endpoint:
+
+```bash
+# Test the endpoint
+curl -X POST https://api.attrove.com/mcp \
+  -H "Authorization: Bearer sk_..." \
+  -H "X-Attrove-User-Id: user-uuid" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+Or integrate in your own server using the HTTP handler:
+
+```typescript
+import { createHttpHandler } from '@attrove/mcp';
+
+const handler = createHttpHandler(
+  {
+    apiKey: 'sk_...',
+    userId: 'user-uuid',
+    baseUrl: 'https://api.attrove.com', // optional: custom API endpoint
+  },
+  {
+    enableJsonResponse: true, // optional: use JSON instead of SSE (default: true)
+    timeoutMs: 30000, // optional: request timeout in ms (default: 30000)
+  }
+);
+
+// With Fastify (recommended)
+fastify.post('/mcp', async (request, reply) => {
+  const result = await handler.handleRequest(request.raw, reply.raw, request.body);
+
+  if (!result.handled) {
+    // Handle timeout with 504, other errors with 500
+    const statusCode = result.isTimeout ? 504 : 500;
+    const userMessage = result.isTimeout
+      ? 'Request timed out. Try a simpler query or reduce the scope.'
+      : 'An unexpected error occurred. Please try again.';
+
+    // Only send response if headers haven't been sent (e.g., during streaming)
+    if (!reply.raw.headersSent) {
+      reply.code(statusCode).send({
+        success: false,
+        error: { code: result.isTimeout ? 'REQUEST_TIMEOUT' : 'INTERNAL_ERROR', message: userMessage }
+      });
+    } else if (!reply.raw.writableEnded) {
+      reply.raw.end(); // Ensure stream is closed
+    }
+    return;
+  }
+
+  // Optional: monitor cleanup failures for resource leak detection
+  if (result.cleanupFailed) {
+    console.warn('MCP cleanup failed - potential resource leak');
+  }
+});
+
+// With raw Node.js HTTP server
+import { createServer } from 'node:http';
+const server = createServer(async (req, res) => {
+  // Note: You'll need to parse the body yourself for raw HTTP
+  const result = await handler.handleRequest(req, res);
+  if (!result.handled) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: result.error }));
+  }
+});
+```
+
 ## Getting API Credentials
 
 1. Sign up at [attrove.com](https://attrove.com)
@@ -209,7 +353,7 @@ Set `ATTROVE_DEBUG=true` to enable verbose error logging with stack traces:
   "mcpServers": {
     "attrove": {
       "command": "npx",
-      "args": ["@attrove/mcp"],
+      "args": ["-y", "@attrove/mcp@latest"],
       "env": {
         "ATTROVE_API_KEY": "sk_...",
         "ATTROVE_USER_ID": "user-uuid",
@@ -233,14 +377,14 @@ The Attrove API has rate limits. If you're making many requests, you may need to
 For AI assistants and code generation tools, Attrove provides machine-readable documentation:
 
 - **llms.txt**: `https://attrove.com/llms.txt` - Condensed API reference for LLMs
-- **Quickstart**: `https://github.com/attrove/quickstart` - Example code with CLAUDE.md context
+- **Examples**: `https://github.com/attrove/examples` - Example code with CLAUDE.md context
 
 ## Links
 
 - [Documentation](https://docs.attrove.com)
 - [API Reference](https://docs.attrove.com/api)
 - [TypeScript SDK](https://www.npmjs.com/package/@attrove/sdk)
-- [Quickstart Examples](https://github.com/attrove/quickstart)
+- [Examples](https://github.com/attrove/examples)
 
 ## License
 

package/cjs/index.js

@@ -28,7 +28,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersion = exports.integrationsToolDefinition = exports.searchToolDefinition = exports.queryToolDefinition = exports.allToolDefinitions = exports.getConfigFromEnv = exports.startServer = exports.createServer = void 0;
+exports.createHttpHandler = exports.getVersion = exports.meetingsToolDefinition = exports.eventsToolDefinition = exports.integrationsToolDefinition = exports.searchToolDefinition = exports.queryToolDefinition = exports.allToolDefinitions = exports.getConfigFromEnv = exports.startServer = exports.createServer = void 0;
 var server_js_1 = require("./server.js");
 Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_js_1.createServer; } });
 Object.defineProperty(exports, "startServer", { enumerable: true, get: function () { return server_js_1.startServer; } });
@@ -38,5 +38,10 @@ Object.defineProperty(exports, "allToolDefinitions", { enumerable: true, get: fu
 Object.defineProperty(exports, "queryToolDefinition", { enumerable: true, get: function () { return index_js_1.queryToolDefinition; } });
 Object.defineProperty(exports, "searchToolDefinition", { enumerable: true, get: function () { return index_js_1.searchToolDefinition; } });
 Object.defineProperty(exports, "integrationsToolDefinition", { enumerable: true, get: function () { return index_js_1.integrationsToolDefinition; } });
+Object.defineProperty(exports, "eventsToolDefinition", { enumerable: true, get: function () { return index_js_1.eventsToolDefinition; } });
+Object.defineProperty(exports, "meetingsToolDefinition", { enumerable: true, get: function () { return index_js_1.meetingsToolDefinition; } });
 var version_js_1 = require("./version.js");
 Object.defineProperty(exports, "getVersion", { enumerable: true, get: function () { return version_js_1.getVersion; } });
+// HTTP transport for hosted MCP endpoints
+var http_js_1 = require("./transport/http.js");
+Object.defineProperty(exports, "createHttpHandler", { enumerable: true, get: function () { return http_js_1.createHttpHandler; } });

package/cjs/server.js

@@ -44,12 +44,14 @@ function validateQueryInput(args) {
     if (typeof input.query !== "string" || input.query.trim() === "") {
         throw new sdk_1.ValidationError('Missing required parameter "query". Please provide a question to ask.', sdk_1.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: "query" });
     }
+    if (input.include_sources !== undefined &&
+        typeof input.include_sources !== "boolean") {
+        throw new sdk_1.ValidationError(`include_sources must be a boolean, received ${typeof input.include_sources}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "include_sources", received: typeof input.include_sources });
+    }
     return {
         query: input.query,
         integration_ids: validateStringArray(input.integration_ids, "integration_ids"),
-        include_sources: typeof input.include_sources === "boolean"
-            ? input.include_sources
-            : undefined,
+        include_sources: input.include_sources,
     };
 }
 /**
@@ -65,14 +67,81 @@ function validateSearchInput(args) {
     if (typeof input.query !== "string" || input.query.trim() === "") {
         throw new sdk_1.ValidationError('Missing required parameter "query". Please provide a search query.', sdk_1.ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: "query" });
     }
+    if (input.after_date !== undefined && typeof input.after_date !== "string") {
+        throw new sdk_1.ValidationError(`after_date must be a string (ISO 8601), received ${typeof input.after_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "after_date", received: typeof input.after_date });
+    }
+    if (input.before_date !== undefined &&
+        typeof input.before_date !== "string") {
+        throw new sdk_1.ValidationError(`before_date must be a string (ISO 8601), received ${typeof input.before_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "before_date", received: typeof input.before_date });
+    }
+    if (input.include_body_text !== undefined &&
+        typeof input.include_body_text !== "boolean") {
+        throw new sdk_1.ValidationError(`include_body_text must be a boolean, received ${typeof input.include_body_text}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "include_body_text", received: typeof input.include_body_text });
+    }
     return {
         query: input.query,
-        after_date: typeof input.after_date === "string" ? input.after_date : undefined,
-        before_date: typeof input.before_date === "string" ? input.before_date : undefined,
+        after_date: input.after_date,
+        before_date: input.before_date,
         sender_domains: validateStringArray(input.sender_domains, "sender_domains"),
-        include_body_text: typeof input.include_body_text === "boolean"
-            ? input.include_body_text
-            : undefined,
+        include_body_text: input.include_body_text,
+    };
+}
+/**
+ * Validate input for the events tool.
+ * All parameters are optional, so validation is light type checking.
+ */
+function validateEventsInput(args) {
+    if (args !== undefined && args !== null && typeof args !== "object") {
+        throw new sdk_1.ValidationError("Invalid arguments. Expected an object or empty.", sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { expected: "object", received: typeof args });
+    }
+    const input = (args ?? {});
+    if (input.start_date !== undefined && typeof input.start_date !== "string") {
+        throw new sdk_1.ValidationError(`start_date must be a string (ISO 8601), received ${typeof input.start_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "start_date", received: typeof input.start_date });
+    }
+    if (input.end_date !== undefined && typeof input.end_date !== "string") {
+        throw new sdk_1.ValidationError(`end_date must be a string (ISO 8601), received ${typeof input.end_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "end_date", received: typeof input.end_date });
+    }
+    if (input.limit !== undefined && typeof input.limit !== "number") {
+        throw new sdk_1.ValidationError(`limit must be a number, received ${typeof input.limit}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "limit", received: typeof input.limit });
+    }
+    return {
+        start_date: input.start_date,
+        end_date: input.end_date,
+        limit: input.limit,
+    };
+}
+/**
+ * Validate input for the meetings tool.
+ * All parameters are optional, so validation is light type checking.
+ */
+function validateMeetingsInput(args) {
+    if (args !== undefined && args !== null && typeof args !== "object") {
+        throw new sdk_1.ValidationError("Invalid arguments. Expected an object or empty.", sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { expected: "object", received: typeof args });
+    }
+    const input = (args ?? {});
+    const validProviders = ["google_meet", "zoom", "teams"];
+    let provider;
+    if (input.provider !== undefined && input.provider !== null) {
+        if (typeof input.provider !== "string" ||
+            !validProviders.includes(input.provider)) {
+            throw new sdk_1.ValidationError(`Invalid provider "${String(input.provider)}". Must be one of: ${validProviders.join(", ")}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "provider", received: input.provider, valid: validProviders });
+        }
+        provider = input.provider;
+    }
+    if (input.start_date !== undefined && typeof input.start_date !== "string") {
+        throw new sdk_1.ValidationError(`start_date must be a string (ISO 8601), received ${typeof input.start_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "start_date", received: typeof input.start_date });
+    }
+    if (input.end_date !== undefined && typeof input.end_date !== "string") {
+        throw new sdk_1.ValidationError(`end_date must be a string (ISO 8601), received ${typeof input.end_date}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "end_date", received: typeof input.end_date });
+    }
+    if (input.limit !== undefined && typeof input.limit !== "number") {
+        throw new sdk_1.ValidationError(`limit must be a number, received ${typeof input.limit}`, sdk_1.ErrorCodes.VALIDATION_INVALID_FORMAT, { field: "limit", received: typeof input.limit });
+    }
+    return {
+        start_date: input.start_date,
+        end_date: input.end_date,
+        provider,
+        limit: input.limit,
     };
 }
 /**
@@ -121,7 +190,7 @@ function formatErrorResponse(error) {
     };
 }
 /**
- * Create and configure the Attrove MCP server.
+ * Wire up tool definitions and dispatch logic for the Attrove MCP server.
  */
 function createServer(config) {
     const server = new index_js_1.Server({
@@ -132,85 +201,75 @@ function createServer(config) {
             tools: {},
         },
     });
-    // Create Attrove client
-    // Type assertion is safe because startServer validates the apiKey prefix
     const client = new sdk_1.Attrove({
         apiKey: config.apiKey,
         userId: config.userId,
         baseUrl: config.baseUrl,
     });
-    // Register tool list handler
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
         return {
             tools: index_js_2.allToolDefinitions.map((tool) => ({
                 name: tool.name,
                 description: tool.description,
                 inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
             })),
         };
     });
-    // Register tool call handler
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        // Validate input outside try-catch so validation errors propagate clearly
-        // and programming bugs in validation don't get caught as API errors
-        let validatedInput;
-        switch (name) {
-            case "attrove_query":
-                validatedInput = validateQueryInput(args);
-                break;
-            case "attrove_search":
-                validatedInput = validateSearchInput(args);
-                break;
-            case "attrove_integrations":
-                // No input validation needed
-                break;
-            default:
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Unknown tool: ${name}. Available tools: attrove_query, attrove_search, attrove_integrations`,
-                        },
-                    ],
-                    isError: true,
-                };
-        }
-        // Execute tool with narrowed try-catch for API/network errors only
         try {
             let result;
             switch (name) {
                 case "attrove_query":
-                    result = await (0, index_js_2.executeQueryTool)(client, validatedInput);
+                    result = await (0, index_js_2.executeQueryTool)(client, validateQueryInput(args));
                     break;
                 case "attrove_search":
-                    result = await (0, index_js_2.executeSearchTool)(client, validatedInput);
+                    result = await (0, index_js_2.executeSearchTool)(client, validateSearchInput(args));
                     break;
                 case "attrove_integrations":
                     result = await (0, index_js_2.executeIntegrationsTool)(client);
                     break;
+                case "attrove_events":
+                    result = await (0, index_js_2.executeEventsTool)(client, validateEventsInput(args));
+                    break;
+                case "attrove_meetings":
+                    result = await (0, index_js_2.executeMeetingsTool)(client, validateMeetingsInput(args));
+                    break;
                 default:
-                    // Already handled above, but TypeScript needs this
-                    throw new Error(`Unexpected tool: ${name}`);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown tool: ${name}. Available tools: attrove_query, attrove_search, attrove_integrations, attrove_events, attrove_meetings`,
+                            },
+                        ],
+                        isError: true,
+                    };
             }
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: result,
-                    },
-                ],
+                content: [{ type: "text", text: result }],
             };
         }
         catch (error) {
-            // Expected API/network errors - format directly for user
-            if ((0, sdk_1.isAttroveError)(error) || error instanceof sdk_1.ValidationError) {
+            // Validation errors = bad input → propagate as JSON-RPC errors (invalid params)
+            if (error instanceof sdk_1.ValidationError) {
+                throw error;
+            }
+            if ((0, sdk_1.isAttroveError)(error)) {
+                if (error.status && error.status >= 500) {
+                    // prettier-ignore
+                    console.error("[AttroveMCP]", JSON.stringify({ level: "error", msg: "MCP tool received server error from API", errorId: "MCP_TOOL_API_SERVER_ERROR", tool: name, errorCode: error.code, status: error.status }));
+                }
+                else if (error.status && error.status >= 400) {
+                    // prettier-ignore
+                    console.error("[AttroveMCP]", JSON.stringify({ level: "debug", msg: "MCP tool received client error from API", errorId: "MCP_TOOL_API_CLIENT_ERROR", tool: name, errorCode: error.code, status: error.status }));
+                }
                 return formatErrorResponse(error);
             }
-            // Unexpected errors (programming bugs, system errors) - always log, then format for user.
-            // We catch all errors to keep the MCP server running, but logging ensures visibility.
+            // Unexpected errors — log and return to keep the MCP server running
             // prettier-ignore
-            console.error('[AttroveMCP] Unexpected error in tool handler:', error);
+            console.error("[AttroveMCP]", JSON.stringify({ level: "error", msg: "MCP unexpected error in tool handler", errorId: "MCP_TOOL_UNEXPECTED_ERROR", tool: name, error: error instanceof Error ? error.message : String(error), stack: error instanceof Error ? error.stack : undefined }));
             return formatErrorResponse(error);
         }
     });
@@ -218,7 +277,7 @@ function createServer(config) {
 }
 exports.createServer = createServer;
 /**
- * Start the MCP server with stdio transport.
+ * Connect the MCP server to stdin/stdout and begin serving requests.
  */
 async function startServer(config) {
     const server = createServer(config);
@@ -229,7 +288,7 @@ exports.startServer = startServer;
 /**
  * Get configuration from environment variables.
  *
- * @throws {Error} If required environment variables are missing
+ * @throws {Error} If required environment variables are missing or invalid
  */
 function getConfigFromEnv() {
     const apiKey = process.env.ATTROVE_API_KEY;
@@ -239,12 +298,15 @@ function getConfigFromEnv() {
         throw new Error("ATTROVE_API_KEY environment variable is required. " +
             "Set it to your Attrove API key (sk_...).");
     }
+    if (!apiKey.startsWith("sk_")) {
+        throw new Error("ATTROVE_API_KEY must start with 'sk_'. Check that you're using a valid API key.");
+    }
     if (!userId) {
         throw new Error("ATTROVE_USER_ID environment variable is required. " +
             "Set it to the user ID (UUID) for the user whose context you want to access.");
     }
     return {
-        apiKey,
+        apiKey: apiKey,
         userId,
         baseUrl,
     };

package/cjs/tools/events.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Events Tool
+ *
+ * MCP tool for listing calendar events from connected integrations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeEventsTool = exports.eventsToolDefinition = void 0;
+/**
+ * MCP schema for discovering and filtering calendar events.
+ */
+exports.eventsToolDefinition = {
+    name: "attrove_events",
+    description: `List calendar events from the user's own connected calendar accounts.
+
+This read-only tool returns events from the authenticated user's authorized calendar integrations (e.g., Google Calendar). Only calendars the user has explicitly connected are accessed. Use this when the user asks about:
+- "What's on my calendar today/this week?"
+- "Do I have any meetings tomorrow?"
+- "When is my next meeting with Sarah?"
+- "What's my schedule for Friday?"`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: {
+                type: "string",
+                description: "Start of date range (ISO 8601). If omitted, the server determines the default.",
+            },
+            end_date: {
+                type: "string",
+                description: "End of date range (ISO 8601). If omitted, the server determines the default.",
+            },
+            limit: {
+                type: "number",
+                description: "Max events to return (default 25, max 100)",
+            },
+        },
+        required: [],
+    },
+    annotations: {
+        title: "Calendar Events",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+/**
+ * Format a calendar event's time range for display (e.g. "Jan 15, 2:00 PM – 3:00 PM").
+ * Returns a fallback string when the event contains unparseable dates.
+ */
+function formatEventTime(event) {
+    if (event.all_day) {
+        const start = new Date(event.start_time);
+        if (Number.isNaN(start.getTime())) {
+            return "All day";
+        }
+        return `All day (${start.toLocaleDateString()})`;
+    }
+    const start = new Date(event.start_time);
+    const end = new Date(event.end_time);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+        return event.start_time ?? "Unknown time";
+    }
+    const dateStr = start.toLocaleDateString(undefined, {
+        month: "short",
+        day: "numeric",
+    });
+    const startTime = start.toLocaleTimeString(undefined, {
+        hour: "numeric",
+        minute: "2-digit",
+    });
+    const endTime = end.toLocaleTimeString(undefined, {
+        hour: "numeric",
+        minute: "2-digit",
+    });
+    return `${dateStr}, ${startTime} – ${endTime}`;
+}
+/**
+ * Fetch calendar events via the SDK and format them as a human-readable summary.
+ */
+async function executeEventsTool(client, input) {
+    const options = {
+        expand: ["attendees", "location", "description"],
+    };
+    if (input.start_date) {
+        options.startDate = input.start_date;
+    }
+    if (input.end_date) {
+        options.endDate = input.end_date;
+    }
+    options.limit = Math.max(1, Math.min(input.limit ?? 25, 100));
+    const response = await client.events.list(options);
+    if (!response.data) {
+        // prettier-ignore
+        console.error("[AttroveMCP]", JSON.stringify({ level: "warn", msg: "Events API returned success but data was nullish", errorId: "MCP_EVENTS_MALFORMED_RESPONSE" }));
+        return "The events API returned an unexpected response format. Please try again.";
+    }
+    if (response.data.length === 0) {
+        return "No calendar events found for the specified date range.";
+    }
+    const events = response.data;
+    let result = `Found ${events.length} calendar event(s):\n`;
+    for (const event of events) {
+        result += `\n### ${event.title}\n`;
+        result += `- **When:** ${formatEventTime(event)}\n`;
+        if (event.location) {
+            result += `- **Where:** ${event.location}\n`;
+        }
+        if (event.event_link) {
+            result += `- **Meeting link:** ${event.event_link}\n`;
+        }
+        else if (event.html_link) {
+            result += `- **Calendar link:** ${event.html_link}\n`;
+        }
+        if (event.attendees?.length) {
+            const attendeeList = event.attendees
+                .map((a) => {
+                const name = a.name || a.email;
+                const status = a.status ? ` (${a.status})` : "";
+                return `${name}${status}`;
+            })
+                .join(", ");
+            result += `- **Attendees:** ${attendeeList}\n`;
+        }
+        if (event.status && event.status !== "confirmed") {
+            result += `- **Status:** ${event.status}\n`;
+        }
+    }
+    if (response.pagination?.has_more) {
+        result += `\n_Showing ${events.length} of ${response.pagination.total_count ?? "more"} events. Adjust start_date, end_date, or limit to refine results._\n`;
+    }
+    return result;
+}
+exports.executeEventsTool = executeEventsTool;