@attrove/mcp 0.1.3 → 0.1.5

package/README.md

@@ -35,7 +35,9 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 
 ### Cursor
 
-Add to your Cursor MCP settings:
+1. Open Cursor Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux)
+2. Search for "MCP" or navigate to **Features > MCP Servers**
+3. Click "Edit in settings.json" or add directly:
 
 ```json
 {
@@ -52,12 +54,43 @@ Add to your Cursor MCP settings:
 }
 ```
 
+4. Restart Cursor for changes to take effect
+5. In the chat, you can now ask questions about your connected integrations
+
+### Claude Code (Terminal)
+
+If using Claude Code in the terminal, the MCP server is configured via environment variables:
+
+```bash
+export ATTROVE_API_KEY="sk_..."
+export ATTROVE_USER_ID="user-uuid"
+```
+
 ### Direct CLI Usage
 
 ```bash
 ATTROVE_API_KEY=sk_... ATTROVE_USER_ID=user-uuid npx @attrove/mcp
 ```
 
+## Common Use Cases
+
+Once connected, you can ask your AI assistant natural language questions. Here are some examples:
+
+**Meeting prep:**
+> "What context do I need for my 2pm meeting with the marketing team?"
+
+**Email follow-ups:**
+> "Are there any emails from last week that I haven't responded to?"
+
+**Project status:**
+> "What's the latest on the Q4 roadmap discussions?"
+
+**People search:**
+> "What has John from Acme Corp been asking about recently?"
+
+**Historical context:**
+> "Find the thread where we discussed the pricing changes last month"
+
 ## Available Tools
 
 ### `attrove_query`
@@ -73,6 +106,8 @@ Ask questions about the user's communications and get AI-generated answers.
 - "What did Sarah say about the Q4 budget?"
 - "Summarize my meeting with the engineering team"
 - "What are the action items from yesterday's standup?"
+- "When is my next meeting with the product team?"
+- "What context do I need before my 3pm call?"
 
 ### `attrove_search`
 
@@ -88,6 +123,8 @@ Search for specific messages or conversations.
 **Example prompts:**
 - "Find all emails about the product launch"
 - "Show me conversations with the marketing team"
+- "Search for messages mentioning the deadline extension"
+- "Find discussions with acme.com from last month"
 
 ### `attrove_integrations`
 
@@ -191,6 +228,20 @@ The Attrove API has rate limits. If you're making many requests, you may need to
 
 - Node.js 18.0.0 or later
 
+## AI-Friendly Documentation
+
+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
+
+## 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)
+
 ## License
 
 MIT

package/cjs/README.md

@@ -0,0 +1,247 @@
+# @attrove/mcp
+
+MCP (Model Context Protocol) server for Attrove. Enables AI assistants like Claude and Cursor to access your users' unified context from Gmail, Slack, Google Calendar, and more.
+
+## Installation
+
+```bash
+npm install @attrove/mcp
+# or
+yarn add @attrove/mcp
+# or
+pnpm add @attrove/mcp
+```
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "attrove": {
+      "command": "npx",
+      "args": ["@attrove/mcp"],
+      "env": {
+        "ATTROVE_API_KEY": "sk_...",
+        "ATTROVE_USER_ID": "user-uuid"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+1. Open Cursor Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux)
+2. Search for "MCP" or navigate to **Features > MCP Servers**
+3. Click "Edit in settings.json" or add directly:
+
+```json
+{
+  "mcpServers": {
+    "attrove": {
+      "command": "npx",
+      "args": ["@attrove/mcp"],
+      "env": {
+        "ATTROVE_API_KEY": "sk_...",
+        "ATTROVE_USER_ID": "user-uuid"
+      }
+    }
+  }
+}
+```
+
+4. Restart Cursor for changes to take effect
+5. In the chat, you can now ask questions about your connected integrations
+
+### Claude Code (Terminal)
+
+If using Claude Code in the terminal, the MCP server is configured via environment variables:
+
+```bash
+export ATTROVE_API_KEY="sk_..."
+export ATTROVE_USER_ID="user-uuid"
+```
+
+### Direct CLI Usage
+
+```bash
+ATTROVE_API_KEY=sk_... ATTROVE_USER_ID=user-uuid npx @attrove/mcp
+```
+
+## Common Use Cases
+
+Once connected, you can ask your AI assistant natural language questions. Here are some examples:
+
+**Meeting prep:**
+> "What context do I need for my 2pm meeting with the marketing team?"
+
+**Email follow-ups:**
+> "Are there any emails from last week that I haven't responded to?"
+
+**Project status:**
+> "What's the latest on the Q4 roadmap discussions?"
+
+**People search:**
+> "What has John from Acme Corp been asking about recently?"
+
+**Historical context:**
+> "Find the thread where we discussed the pricing changes last month"
+
+## Available Tools
+
+### `attrove_query`
+
+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
+
+**Example prompts:**
+- "What did Sarah say about the Q4 budget?"
+- "Summarize my meeting with the engineering team"
+- "What are the action items from yesterday's standup?"
+- "When is my next meeting with the product team?"
+- "What context do I need before my 3pm call?"
+
+### `attrove_search`
+
+Search for specific messages or conversations.
+
+**Parameters:**
+- `query` (required): The search query
+- `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)
+
+**Example prompts:**
+- "Find all emails about the product launch"
+- "Show me conversations with the marketing team"
+- "Search for messages mentioning the deadline extension"
+- "Find discussions with acme.com from last month"
+
+### `attrove_integrations`
+
+List the user's connected integrations.
+
+**Parameters:** None
+
+**Example prompts:**
+- "What services are connected?"
+- "Show me my integrations"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ATTROVE_API_KEY` | Yes | Your Attrove API key (`sk_...`) |
+| `ATTROVE_USER_ID` | Yes | User ID to scope API calls |
+| `ATTROVE_BASE_URL` | No | Custom API base URL |
+| `ATTROVE_DEBUG` | No | Set to `true` for verbose error logging |
+
+## Programmatic Usage
+
+You can also use the server programmatically:
+
+```typescript
+import { createServer, startServer } from '@attrove/mcp';
+
+// Create a server instance
+const server = createServer({
+  apiKey: 'sk_...',
+  userId: 'user-uuid'
+});
+
+// Or start directly with stdio transport
+await startServer({
+  apiKey: 'sk_...',
+  userId: 'user-uuid'
+});
+```
+
+## Getting API Credentials
+
+1. Sign up at [attrove.com](https://attrove.com)
+2. Create an organization in the dashboard
+3. Generate an API key (`sk_...`)
+4. Provision a user to get a user ID
+
+```typescript
+import { Attrove } from '@attrove/sdk';
+
+const admin = Attrove.admin({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret'
+});
+
+// Create a user
+const { id, apiKey } = await admin.users.create({
+  email: 'user@example.com'
+});
+
+// Use `apiKey` as ATTROVE_API_KEY and `id` as ATTROVE_USER_ID
+```
+
+## Troubleshooting
+
+### "ATTROVE_API_KEY environment variable is required"
+
+Make sure you've set the environment variables correctly in your MCP configuration.
+
+### Tools not showing up
+
+1. Restart Claude/Cursor after configuration changes
+2. Check the MCP server logs for errors
+3. Verify your API key is valid
+
+### Debugging errors
+
+Set `ATTROVE_DEBUG=true` to enable verbose error logging with stack traces:
+
+```json
+{
+  "mcpServers": {
+    "attrove": {
+      "command": "npx",
+      "args": ["@attrove/mcp"],
+      "env": {
+        "ATTROVE_API_KEY": "sk_...",
+        "ATTROVE_USER_ID": "user-uuid",
+        "ATTROVE_DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+### Rate limiting
+
+The Attrove API has rate limits. If you're making many requests, you may need to wait before trying again.
+
+## Requirements
+
+- Node.js 18.0.0 or later
+
+## AI-Friendly Documentation
+
+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
+
+## 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)
+
+## License
+
+MIT

package/cjs/bin/attrove-mcp.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Attrove MCP Server CLI
+ *
+ * Starts the MCP server for use with Claude, Cursor, or other MCP-compatible clients.
+ *
+ * Required environment variables:
+ * - ATTROVE_API_KEY: Your Attrove API key (sk_...)
+ * - ATTROVE_USER_ID: The user ID to scope API calls
+ *
+ * Optional environment variables:
+ * - ATTROVE_BASE_URL: Custom API base URL (defaults to https://api.attrove.com)
+ * - ATTROVE_DEBUG: Set to "true" to enable debug logging
+ *
+ * Usage:
+ *   ATTROVE_API_KEY=sk_... ATTROVE_USER_ID=... npx @attrove/mcp
+ *
+ * Claude Desktop configuration:
+ *   {
+ *     "mcpServers": {
+ *       "attrove": {
+ *         "command": "npx",
+ *         "args": ["@attrove/mcp"],
+ *         "env": {
+ *           "ATTROVE_API_KEY": "sk_...",
+ *           "ATTROVE_USER_ID": "..."
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+const isDebug = process.env.ATTROVE_DEBUG === 'true' || process.env.DEBUG === 'true';
+
+async function main() {
+  try {
+    // Import the server module
+    const { startServer, getConfigFromEnv } = await import('../esm/index.js');
+
+    // Get configuration from environment
+    const config = getConfigFromEnv();
+
+    // Start the server
+    await startServer(config);
+  } catch (error) {
+    // Always show the error message
+    console.error('Failed to start Attrove MCP server:', error.message);
+
+    // Show stack trace in debug mode for easier troubleshooting
+    if (isDebug && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+
+    // Show additional context for common errors
+    if (error.message.includes('ATTROVE_API_KEY')) {
+      console.error('\nHint: Set the ATTROVE_API_KEY environment variable to your API key (sk_...)');
+    } else if (error.message.includes('ATTROVE_USER_ID')) {
+      console.error('\nHint: Set the ATTROVE_USER_ID environment variable to the user ID (UUID)');
+    } else if (error.message.includes('Cannot find module')) {
+      console.error('\nHint: Try running "npm install" or "npm rebuild" to reinstall dependencies');
+    }
+
+    process.exit(1);
+  }
+}
+
+main();

package/cjs/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@attrove/mcp",
+  "version": "0.1.5",
+  "description": "MCP server for Attrove - AI-powered context retrieval for Claude and Cursor",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "attrove-mcp": "./bin/attrove-mcp.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "attrove",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai",
+    "rag",
+    "llm"
+  ],
+  "author": "Attrove <support@attrove.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/attrove/attrove-js.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://attrove.com/docs/mcp",
+  "bugs": {
+    "url": "https://github.com/attrove/attrove-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "nx build mcp",
+    "test": "nx test mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@attrove/sdk": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs"
+}

package/cjs/src/__mocks__/version.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Mock version module for Jest tests.
+ *
+ * This avoids the import.meta.url ESM issue when running tests with ts-jest.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetVersionCache = exports.getVersion = void 0;
+function getVersion() {
+    return '1.0.0-test';
+}
+exports.getVersion = getVersion;
+function resetVersionCache() {
+    // No-op in mock
+}
+exports.resetVersionCache = resetVersionCache;
+//# sourceMappingURL=version.js.map

package/cjs/src/__mocks__/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../../../../packages/mcp/src/__mocks__/version.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,SAAgB,UAAU;IACxB,OAAO,YAAY,CAAC;AACtB,CAAC;AAFD,gCAEC;AAED,SAAgB,iBAAiB;IAC/B,gBAAgB;AAClB,CAAC;AAFD,8CAEC"}

package/cjs/src/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * MCP Constants
+ *
+ * Centralized constants used across the MCP server. Consolidating these ensures
+ * consistency and makes maintenance easier.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BODY_PREVIEW_LENGTH = void 0;
+/**
+ * Maximum length for message body preview text in search results.
+ *
+ * When displaying search results, message bodies longer than this value
+ * will be truncated with an ellipsis to keep output manageable.
+ */
+exports.MAX_BODY_PREVIEW_LENGTH = 200;
+//# sourceMappingURL=constants.js.map

package/cjs/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../packages/mcp/src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,GAAG,CAAC"}

package/cjs/src/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * @attrove/mcp
+ *
+ * MCP server for Attrove - enables AI assistants like Claude and Cursor
+ * to access user context through the Attrove API.
+ *
+ * @example
+ * ```bash
+ * # Run via npx
+ * ATTROVE_API_KEY=sk_... ATTROVE_USER_ID=... npx @attrove/mcp
+ *
+ * # Configure in Claude Desktop
+ * {
+ *   "mcpServers": {
+ *     "attrove": {
+ *       "command": "npx",
+ *       "args": ["@attrove/mcp"],
+ *       "env": {
+ *         "ATTROVE_API_KEY": "sk_...",
+ *         "ATTROVE_USER_ID": "..."
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @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;
+var server_1 = require("./server");
+Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_1.createServer; } });
+Object.defineProperty(exports, "startServer", { enumerable: true, get: function () { return server_1.startServer; } });
+Object.defineProperty(exports, "getConfigFromEnv", { enumerable: true, get: function () { return server_1.getConfigFromEnv; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "allToolDefinitions", { enumerable: true, get: function () { return tools_1.allToolDefinitions; } });
+Object.defineProperty(exports, "queryToolDefinition", { enumerable: true, get: function () { return tools_1.queryToolDefinition; } });
+Object.defineProperty(exports, "searchToolDefinition", { enumerable: true, get: function () { return tools_1.searchToolDefinition; } });
+Object.defineProperty(exports, "integrationsToolDefinition", { enumerable: true, get: function () { return tools_1.integrationsToolDefinition; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "getVersion", { enumerable: true, get: function () { return version_1.getVersion; } });
+//# sourceMappingURL=index.js.map

package/cjs/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/mcp/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAEH,mCAAuE;AAA9D,sGAAA,YAAY,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAGpD,iCAKiB;AAJf,2GAAA,kBAAkB,OAAA;AAClB,4GAAA,mBAAmB,OAAA;AACnB,6GAAA,oBAAoB,OAAA;AACpB,mHAAA,0BAA0B,OAAA;AAG5B,qCAAuC;AAA9B,qGAAA,UAAU,OAAA"}