@attrove/mcp 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# @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
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "attrove": {
+      "command": "npx",
+      "args": ["@attrove/mcp"],
+      "env": {
+        "ATTROVE_API_KEY": "sk_...",
+        "ATTROVE_USER_ID": "user-uuid"
+      }
+    }
+  }
+}
+```
+
+### Direct CLI Usage
+
+```bash
+ATTROVE_API_KEY=sk_... ATTROVE_USER_ID=user-uuid npx @attrove/mcp
+```
+
+## 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?"
+
+### `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"
+
+### `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
+
+## License
+
+MIT

package/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/package.json

@@ -1 +1,68 @@
-{"name":"@attrove/mcp","version":"0.0.1"}
+{
+  "name": "@attrove/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Attrove - AI-powered context retrieval for Claude and Cursor",
+  "main": "./cjs/index.js",
+  "module": "./esm/index.js",
+  "types": "./types/src/index.d.ts",
+  "bin": {
+    "attrove-mcp": "./bin/attrove-mcp.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/src/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./types/src/index.d.ts",
+        "default": "./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": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}