attio-mcp 1.3.6 → 1.4.1

package/README.md

@@ -4,7 +4,6 @@
 [![npm version](https://badge.fury.io/js/attio-mcp.svg)](https://badge.fury.io/js/attio-mcp)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 [![GitHub Release](https://img.shields.io/github/v/release/kesslerio/attio-mcp-server)](https://github.com/kesslerio/attio-mcp-server/releases)
-[![smithery badge](https://smithery.ai/badge/@kesslerio/attio-mcp-server)](https://smithery.ai/server/@kesslerio/attio-mcp-server)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kesslerio/attio-mcp-server)
 
 A comprehensive Model Context Protocol (MCP) server for [Attio](https://attio.com/), providing **complete CRM surface coverage**. This server enables AI assistants like Claude and ChatGPT to interact directly with your entire Attio workspace through natural language—manage Deals, Tasks, Lists, People, Companies, Records, and Notes without falling back to raw API calls.
@@ -17,14 +16,16 @@ Transform your CRM workflows with AI-powered automation. Instead of clicking thr
 
 > "Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list"
 
-## 🚀 **NEW: ChatGPT Developer Mode Integration**
+## 🚀 **ChatGPT Developer Mode Integration**
 
-**v1.0.0 introduces full ChatGPT compatibility!** ChatGPT Pro/Plus users can now access the entire Attio toolset through natural language via [Smithery marketplace](https://smithery.ai/server/@kesslerio/attio-mcp-server).
+> **⚠️ Smithery Temporarily Unavailable**: Smithery has changed their deployment model to require external hosting. We're working on Cloudflare Worker hosting for ChatGPT users. In the meantime, use [Tier 4 (Cloudflare Worker)](#tier-4-cloudflare-worker-remote-deployment) for ChatGPT/remote access.
+
+ChatGPT Pro/Plus users can access the Attio toolset through natural language using a self-hosted Cloudflare Worker:
 
 - **🔐 Built-in Approval Flows**: MCP safety annotations auto-approve read operations, request approval for writes
-- **🌐 OAuth Integration**: Seamless authentication via `https://server.smithery.ai/@kesslerio/attio-mcp-server/mcp`
+- **🌐 OAuth Integration**: Self-hosted OAuth via Cloudflare Worker deployment
 - **💬 Natural Language CRM**: Manage your entire Attio workspace through conversational AI
-- **📖 Setup Guide**: See [ChatGPT Developer Mode docs](./docs/chatgpt-developer-mode.md) for complete configuration
+- **📖 Setup Guide**: See [ChatGPT Developer Mode docs](./docs/chatgpt-developer-mode.md) and [Cloudflare Worker Guide](./examples/cloudflare-mcp-server/README.md)
 
 ## ✨ Core Features & Implementation Status
 
@@ -54,22 +55,28 @@ Transform your CRM workflows with AI-powered automation. Instead of clicking thr
 
 ### 📊 **Company Management**
 
-- **Universal Search**: Find companies with `search-records` and `advanced-search`
+- **Universal Search**: Find companies with `search_records` and `search_records_advanced`
 - **Full CRUD**: Create, read, update, and delete with universal record operations
-- **Relationship Discovery**: Find companies through `search-by-relationship`
-- **Batch Operations**: Process hundreds of companies with `batch-operations`
-- **Detailed Information**: Get contact, business, and social info with `get-detailed-info`
+- **Relationship Discovery**: Find companies through `search_records_by_relationship`
+- **Batch Operations**: Process hundreds of companies with `batch_records`
+- **Detailed Information**: Get contact, business, and social info with `get_record_info`
 
 ### 👥 **People Management**
 
 - **Universal Contact Search**: Find people by any criteria using universal search tools
-- **Relationship Tracking**: Link people to companies with `search-by-relationship`
-- **Activity Timeline**: Track interactions with `search-by-content` and `search-by-timeframe`
+- **Relationship Tracking**: Link people to companies with `search_records_by_relationship`
+- **Activity Timeline**: Track interactions with `search_records_by_content` and `search_records_by_timeframe`
 - **Advanced Filtering**: Multi-attribute search with universal filtering
 - **Bulk Operations**: Efficiently manage contacts with universal batch operations
 
-### 📋 **Lists & Pipeline Management** (11 Tools)
+### 📋 **Lists & Pipeline Management** (4 Tools + 8 Deprecated)
 
+- **Active Tools**: 4 consolidated tools with auto-mode detection ([Migration Guide](./docs/migration/v2-list-tools.md))
+  - `filter-list-entries` - Unified filtering with 4 modes
+  - `manage-list-entry` - Unified entry management with 3 modes
+  - `get-list-entries` - Retrieve list entries
+  - `get-record-list-memberships` - Find record's list memberships
+- **Deprecated (v2.0.0 removal)**: 8 legacy tools replaced by consolidated versions
 - **Pipeline Operations**: Move deals through sales stages
 - **Smart Segmentation**: Create and manage targeted contact lists
 - **Advanced Filtering**: Complex multi-condition filtering with AND/OR logic
@@ -91,6 +98,25 @@ Transform your CRM workflows with AI-powered automation. Instead of clicking thr
 - **Data Export**: JSON serialization for integrations
 - **Real-time Updates**: Live data synchronization with Attio
 
+### 🧠 **Claude Skills**
+
+Supercharge Claude's Attio knowledge with pre-built skills that prevent common errors and teach best practices.
+
+| Skill                      | Purpose                                        | Setup                                           |
+| -------------------------- | ---------------------------------------------- | ----------------------------------------------- |
+| **attio-mcp-usage**        | Error prevention + universal workflow patterns | Bundled - just use it                           |
+| **attio-workspace-schema** | YOUR workspace's exact field names and options | `npx attio-discover generate-skill --all --zip` |
+| **attio-skill-generator**  | Create custom workflow skills (advanced)       | Python + prompting                              |
+
+**Quick Start** (solves "wrong field name" errors):
+
+```bash
+npx attio-discover generate-skill --all --zip
+# Import ZIP into Claude Desktop: Settings > Skills > Install Skill
+```
+
+See [Skills Documentation](./docs/usage/skills/README.md) for complete setup and usage guides.
+
 ### 💬 **Pre-Built Prompts** (10 Prompts)
 
 Intelligent shortcuts that help Claude work faster with your CRM data:
@@ -177,7 +203,7 @@ For complete prompt documentation, see [docs/prompts/v1-catalog.md](./docs/promp
 ### 🤝 **OpenAI MCP Compatibility**
 
 - **Developer Mode Ready**: Every tool now publishes MCP safety annotations (`readOnlyHint`, `destructiveHint`) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes.
-- **Full Tool Access (Default)**: All 33 universal tools are exposed by default. Do NOT set `ATTIO_MCP_TOOL_MODE` in Smithery configuration for full access.
+- **Full Tool Access (Default)**: All 35 tools are exposed by default (21 universal + 11 list + 3 workspace member). Do NOT set `ATTIO_MCP_TOOL_MODE` in Smithery configuration for full access.
 - **Search-Only Mode**: To restrict to read-only tools (`search`, `fetch`, `aaa-health-check`), explicitly configure `ATTIO_MCP_TOOL_MODE: 'search'` in Smithery dashboard when Developer Mode is unavailable.
 - **Detailed Guide**: See [docs/chatgpt-developer-mode.md](./docs/chatgpt-developer-mode.md) for environment variables, approval flows, and validation tips.
 - **User Documentation**: See the [ChatGPT Developer Mode docs](./docs/chatgpt-developer-mode.md) for a complete walkthrough of approval flows and setup instructions.
@@ -190,189 +216,9 @@ For complete prompt documentation, see [docs/prompts/v1-catalog.md](./docs/promp
 
 For detailed troubleshooting and solutions, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) and [GitHub Issues](https://github.com/kesslerio/attio-mcp-server/issues).
 
-## 🎯 **Mastering Advanced Search Filters**
-
-**The Power Behind Precise CRM Queries** - Stop wrestling with complex data searches. Our advanced filtering system lets you find exactly what you need with surgical precision.
-
-> _"Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list"_ - This kind of complex query is exactly what advanced search filters excel at.
-
-### 🏗️ **Filter Architecture**
-
-Every advanced search follows this proven pattern that's been battle-tested across thousands of CRM queries:
-
-```json
-{
-  "resource_type": "companies",
-  "filters": {
-    "filters": [
-      {
-        "attribute": { "slug": "field_name" },
-        "condition": "operator",
-        "value": "search_value"
-      }
-    ]
-  }
-}
-```
-
-### ⚡ **Real-World Examples**
-
-**🔍 Single Criteria Search**
-
-```json
-{
-  "resource_type": "companies",
-  "filters": {
-    "filters": [
-      {
-        "attribute": { "slug": "name" },
-        "condition": "contains",
-        "value": "Tech"
-      }
-    ]
-  }
-}
-```
-
-**🎯 Multi-Criteria Power Search (AND Logic)**
-
-```json
-{
-  "resource_type": "companies",
-  "filters": {
-    "filters": [
-      {
-        "attribute": { "slug": "name" },
-        "condition": "contains",
-        "value": "Tech"
-      },
-      {
-        "attribute": { "slug": "employee_count" },
-        "condition": "greater_than",
-        "value": 50
-      },
-      {
-        "attribute": { "slug": "industry" },
-        "condition": "equals",
-        "value": "AI/Machine Learning"
-      }
-    ]
-  }
-}
-```
-
-**🚀 Flexible OR Logic**
-
-```json
-{
-  "resource_type": "companies",
-  "filters": {
-    "filters": [
-      {
-        "attribute": { "slug": "name" },
-        "condition": "contains",
-        "value": "Tech"
-      },
-      {
-        "attribute": { "slug": "name" },
-        "condition": "contains",
-        "value": "AI"
-      }
-    ],
-    "matchAny": true
-  }
-}
-```
-
-### 🧠 **Smart Filter Operators**
-
-| Operator       | Perfect For         | Example Use Case                      |
-| -------------- | ------------------- | ------------------------------------- |
-| `contains`     | Text searches       | Finding companies with "Tech" in name |
-| `equals`       | Exact matches       | Specific industry classification      |
-| `starts_with`  | Prefix searches     | Companies beginning with "Acme"       |
-| `ends_with`    | Suffix searches     | Companies ending with "Inc"           |
-| `greater_than` | Numerical analysis  | Companies with 100+ employees         |
-| `less_than`    | Size filtering      | Startups under 50 people              |
-| `is_empty`     | Data cleanup        | Find records missing key information  |
-| `is_not_empty` | Completeness checks | Records with populated fields         |
-
-### 💡 **Pro Tips for Different Teams**
+## 🎯 **Advanced Search Filters**
 
-**🎯 Sales Teams** - Use these field combinations:
-
-- **Companies**: `name`, `industry`, `employee_count`, `website`, `location`
-- **People**: `full_name`, `job_title`, `email`, `company`
-
-**📈 Marketing Teams** - Focus on engagement fields:
-
-- **Activity tracking**: `last_interaction`, `email_status`, `campaign_response`
-- **Segmentation**: `industry`, `company_size`, `location`, `engagement_score`
-
-**✅ Customer Success** - Monitor health metrics:
-
-- **Account health**: `renewal_date`, `support_tickets`, `usage_metrics`
-- **Risk indicators**: `last_contact`, `satisfaction_score`, `contract_value`
-
-### 🚨 **Avoid These Common Mistakes**
-
-❌ **Wrong** (Flat object structure):
-
-```json
-{
-  "filters": {
-    "name": { "operator": "contains", "value": "Test" }
-  }
-}
-```
-
-✅ **Correct** (Nested array structure):
-
-```json
-{
-  "filters": {
-    "filters": [
-      {
-        "attribute": { "slug": "name" },
-        "condition": "contains",
-        "value": "Test"
-      }
-    ]
-  }
-}
-```
-
-### 🔧 **Quick Troubleshooting**
-
-**Getting "Filters must include a 'filters' array property"?**
-
-1. ✅ Ensure your filters object contains a `filters` array
-2. ✅ Each array item needs `attribute`, `condition`, and `value`
-3. ✅ The `attribute` must be an object with a `slug` property
-4. ✅ Double-check your JSON structure matches the examples above
-
-**💬 Pro Tip**: Start with simple single-filter searches, then build complexity once you're comfortable with the structure.
-
-## 🏆 Latest Updates - Critical Issues Resolved
-
-✅ **100% Integration Test Pass Rate Achieved** - All critical API contract violations and build issues have been resolved:
-
-### Recently Fixed Issues (August 2025)
-
-- **P0 Critical API Failures**: Fixed response data structure handling for robust fallback patterns
-- **Build Compilation Errors**: Created missing enhanced-validation module and resolved TypeScript compilation
-- **E2E Test Implementation**: Fixed JSON truncation, resource mappings, and email validation consistency
-- **Field Parameter Filtering**: Resolved tasks attribute handling with special case for missing `/objects/tasks/attributes` endpoint
-- **Email Validation Consistency**: Fixed batch validation and create/update operation alignment
-- **Pagination System**: Documented tasks pagination limitation with in-memory handling workaround
-
-### Test Status
-
-- **Integration Tests**: 15/15 passing (100% pass rate)
-- **Build Status**: All TypeScript compilation successful
-- **API Contract**: All violations resolved with robust error handling
-
-See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for detailed solutions to these resolved issues.
+Build powerful CRM queries with multi-criteria AND/OR filtering. See the [Advanced Search Guide](./docs/usage/advanced-search.md) for complete examples and operator reference.
 
 ## 🚀 Installation
 
@@ -384,61 +230,23 @@ See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for detailed solutions to these r
 
 ### Client Compatibility
 
-| Client             | Smithery (Tier 1) | Local Install (Tier 2-3) | Cloudflare Worker (Tier 4) |
-| ------------------ | ----------------- | ------------------------ | -------------------------- |
-| Claude Desktop     | ✅ Recommended    | ✅ Full support          | ✅ Full support            |
-| Claude Web         | ✅ Recommended    | N/A                      | ✅ Full support            |
-| ChatGPT (Pro/Plus) | ✅ Required       | N/A                      | ✅ Full support            |
-| Cursor IDE         | ✅ Supported      | ✅ Full support          | ✅ Full support            |
-| Claude Code (CLI)  | Partial           | ✅ Recommended           | Partial                    |
+| Client             | Local Install (Tier 1-2) | Cloudflare Worker (Tier 3) |
+| ------------------ | ------------------------ | -------------------------- |
+| Claude Desktop     | ✅ Recommended           | ✅ Full support            |
+| Claude Web         | N/A                      | ✅ Full support            |
+| ChatGPT (Pro/Plus) | N/A                      | ✅ Recommended             |
+| Cursor IDE         | ✅ Full support          | ✅ Full support            |
+| Claude Code (CLI)  | ✅ Recommended           | Partial                    |
 
 **Choose your installation method:**
 
-- **Most users**: Use [Tier 1 (Smithery)](#tier-1-smithery-one-click---recommended) - zero local config required
-- **Local control**: Use [Tier 2 (Shell Installers)](#tier-2-shell-installers) - one command, automatic setup
-- **Power users**: Use [Tier 3 (Manual)](#tier-3-manual-configuration) - full control over configuration
-- **Teams/Enterprise**: Use [Tier 4 (Cloudflare Worker)](#tier-4-cloudflare-worker-remote-deployment) - self-hosted, multi-user OAuth
+- **Most users**: Use [Tier 1 (Shell Installers)](#tier-1-shell-installers) - one command, automatic setup
+- **Power users**: Use [Tier 2 (Manual)](#tier-2-manual-configuration) - full control over configuration
+- **ChatGPT/Teams/Enterprise**: Use [Tier 3 (Cloudflare Worker)](#tier-3-cloudflare-worker-remote-deployment) - self-hosted, multi-user OAuth
 
 ---
 
-### Tier 1: Smithery (One-Click) - Recommended
-
-> **Best for**: Claude Desktop, Claude Web, ChatGPT, Cursor - zero local installation required.
-
-[Smithery](https://smithery.ai/server/@kesslerio/attio-mcp-server) handles OAuth, hosting, and configuration automatically.
-
-#### Claude Desktop via Smithery
-
-```bash
-npx -y @smithery/cli install @kesslerio/attio-mcp-server --client claude
-```
-
-#### Cursor IDE via Smithery
-
-```bash
-npx -y @smithery/cli install @kesslerio/attio-mcp-server --client cursor
-```
-
-#### ChatGPT Developer Mode
-
-ChatGPT requires Smithery for OAuth authentication. Direct server URLs are not supported.
-
-1. Enable Developer Mode: **Settings → Connectors → Advanced → Developer Mode**
-2. Add MCP Server URL: `https://server.smithery.ai/@kesslerio/attio-mcp-server/mcp`
-3. Complete OAuth authorization when prompted
-
-See [ChatGPT Developer Mode Guide](./docs/chatgpt-developer-mode.md) for detailed setup instructions.
-
-#### Claude Web
-
-1. Go to [Claude.ai](https://claude.ai) Settings → Connectors
-2. Add new MCP connector
-3. Select "Attio CRM" from Smithery marketplace
-4. Authorize with your Attio account
-
----
-
-### Tier 2: Shell Installers
+### Tier 1: Shell Installers
 
 > **Best for**: Developers who prefer local installations with automatic configuration.
 
@@ -472,7 +280,7 @@ These scripts will:
 
 ---
 
-### Tier 3: Manual Configuration
+### Tier 2: Manual Configuration
 
 > **Best for**: Power users who prefer full control or use unsupported clients.
 
@@ -603,7 +411,7 @@ npm install attio-mcp
 
 ---
 
-### Tier 4: Cloudflare Worker (Remote Deployment)
+### Tier 3: Cloudflare Worker (Remote Deployment)
 
 > **Best for**: Teams needing centralized OAuth, multi-user access, mobile access, or running MCP without local installation.
 
@@ -615,18 +423,18 @@ Deploy your own Attio MCP server on Cloudflare Workers with full OAuth 2.1 suppo
 - Claude mobile app (iOS/Android)
 - Any browser on any device
 
-#### Smithery vs. Cloudflare Worker
+#### Cloudflare Worker Features
 
-| Feature           | Smithery  | Cloudflare Worker |
-| ----------------- | --------- | ----------------- |
-| Setup complexity  | Very Low  | Medium            |
-| OAuth built-in    | ✅        | ✅                |
-| Mobile app access | ✅        | ✅                |
-| Multi-user access | ❌        | ✅                |
-| Custom domain     | ❌        | ✅                |
-| Self-hosted       | ❌        | ✅                |
-| Team deployments  | Limited   | ✅ Full           |
-| Cost              | Free tier | Free tier         |
+| Feature           | Cloudflare Worker |
+| ----------------- | ----------------- |
+| Setup complexity  | Medium            |
+| OAuth built-in    | ✅                |
+| Mobile app access | ✅                |
+| Multi-user access | ✅                |
+| Custom domain     | ✅                |
+| Self-hosted       | ✅                |
+| Team deployments  | ✅ Full           |
+| Cost              | Free tier         |
 
 #### Quick Deploy
 
@@ -655,6 +463,80 @@ See [Cloudflare Worker Deployment Guide](./examples/cloudflare-mcp-server/README
 - Production deployment checklist
 - Troubleshooting guide
 
+---
+
+## 🆕 What's New in v1.4.0
+
+### Major Features
+
+- **🎯 Workspace Schema Skill Generator** (#983) - Auto-generate Claude Skills from your Attio workspace schema for error-free field names and options
+- **🔍 Select-field Transformer** (#1019) - Case-insensitive matching, partial matching, and UUID pass-through for select/status fields
+- **🛠️ Attio Skill Generator Meta-skill** (#1020) - Meta-skill for automatic workspace documentation
+- **📚 Universal Usage Guide Skill** (#1018) - Hand-crafted workflow patterns and error prevention
+- **⚙️ `get_record_attribute_options` tool** (#975) - Get valid options for select/status fields with enhanced error messages
+- **📞 Phone validation** (#951) - Built-in phone number validation support
+- **⏱️ Configurable option fetch delay** - Rate limiting control via `--option-fetch-delay` flag
+
+### Major Enhancements
+
+- **🏷️ MCP-compliant tool naming** (#1039) - All tools now use `snake_case`, verb-first naming (old names work via aliases until v2.0.0)
+- **🎨 Custom object display names** (#1017) - Fetch display names directly from Attio API
+- **📖 Split integration patterns** (#1023) - Progressive discovery patterns by use case
+- **💡 Enhanced attribute error messages** (#975) - Levenshtein distance suggestions for typos
+
+### Critical Fixes
+
+- 📝 Note content line breaks preserved (#1052)
+- 👤 People search "Unnamed" display fixed (#1051)
+- ✅ Select field persistence (#1045)
+- 🔗 Record-reference auto-transformation (#997)
+- 📊 Multi-select array auto-transformation (#992)
+- 🛡️ Complex attribute validation (#991)
+- ⚠️ Field persistence false warnings (#995)
+- 📦 SDK dependency pinning (#1025)
+- 💼 Deal stage/UTM validation (#1043)
+- 📍 Location field auto-normalization (#987)
+
+### Internal Improvements
+
+- Tool alias system refactoring (#1041) - Type-safe constants with pattern-based generation
+- Strategy Pattern for CRUD error handlers (#1001)
+- Consolidated metadata fetching (#984)
+- UniversalUpdateService modularization (#984)
+- Select transformation type rename (#1055) - `select_title_to_array` for clarity
+
+## 🔄 Migration Guide
+
+**Upgrading from v1.3.x or earlier?** Tool names have changed to follow MCP naming conventions.
+
+**Old names still work** via backward-compatible aliases, but will be removed in **v2.0.0 (Q1 2026)**.
+
+### Tool Name Changes
+
+| Old Name (Deprecated)            | New Name (MCP-compliant)         | Notes              |
+| -------------------------------- | -------------------------------- | ------------------ |
+| `records_search`                 | `search_records`                 | Verb-first pattern |
+| `records_get_details`            | `get_record_details`             | Verb-first pattern |
+| `records_get_attributes`         | `get_record_attributes`          | Verb-first pattern |
+| `records_discover_attributes`    | `discover_record_attributes`     | Verb-first pattern |
+| `records_search_advanced`        | `search_records_advanced`        | Verb-first pattern |
+| `records_search_by_relationship` | `search_records_by_relationship` | Verb-first pattern |
+| `records_search_by_content`      | `search_records_by_content`      | Verb-first pattern |
+| `records_search_by_timeframe`    | `search_records_by_timeframe`    | Verb-first pattern |
+| `records_batch`                  | `batch_records`                  | Verb-first pattern |
+| `search-records`                 | `search_records`                 | snake_case format  |
+| `get-record-details`             | `get_record_details`             | snake_case format  |
+| `create-record`                  | `create_record`                  | snake_case format  |
+| `update-record`                  | `update_record`                  | snake_case format  |
+| `delete-record`                  | `delete_record`                  | snake_case format  |
+| `create-note`                    | `create_note`                    | snake_case format  |
+| `list-notes`                     | `list_notes`                     | snake_case format  |
+| `smithery-debug-config`          | `smithery_debug_config`          | snake_case format  |
+
+**Action Required:** Update your integrations to use new tool names before Q1 2026. See [MIGRATION-GUIDE.md](docs/MIGRATION-GUIDE.md) for the complete migration table.
+
+---
+
 ## ⚡ Quick Start
 
 ### Prerequisites
@@ -921,87 +803,14 @@ See [docs/deployment/smithery-cli-setup.md](./docs/deployment/smithery-cli-setup
 
 ### **Testing**
 
-The project includes comprehensive testing at multiple levels with **100% E2E test pass rate**:
-
-#### **🚀 E2E Test Framework (100% Pass Rate)**
-
-Our comprehensive E2E test framework validates all universal tools with real Attio API integration:
-
 ```bash
-# E2E Tests (requires ATTIO_API_KEY in .env file)
-npm run e2e                 # Run complete E2E test suite (51 tests, 100% pass rate)
-npm test -- test/e2e/suites/universal-tools.e2e.test.ts  # Universal tools E2E tests
-
-# Set up E2E environment
-echo "ATTIO_API_KEY=your_api_key_here" > .env
-npm run e2e                 # Should show 51/51 tests passing
-```
-
-**✅ Comprehensive Coverage:**
-
-- **Pagination Testing**: Validates `offset` parameter across all universal tools
-- **Field Filtering**: Tests `fields` parameter for selective data retrieval
-- **Tasks Integration**: Complete lifecycle testing for tasks resource type
-- **Cross-Resource Validation**: Ensures consistent behavior across companies, people, lists, tasks
-- **Error Handling**: Validates graceful error responses and edge cases
-- **Performance Monitoring**: Tracks execution times and API response sizes
-
-**🛠️ Enhanced Assertions (7 New Methods):**
-
-```typescript
-// Available in test/e2e/utils/assertions.ts
-expectValidPagination(result, params); // Validates pagination behavior
-expectFieldFiltering(result, fields); // Validates field selection
-expectValidTasksIntegration(result); // Tasks-specific validation
-expectSpecificError(result, errorType); // Typed error validation
-expectOptimalPerformance(result, budget); // Performance validation
-expectValidUniversalToolParams(params); // Parameter validation
-expectValidBatchOperation(result, records); // Batch operation validation
-```
-
-**📊 Performance Benchmarks:**
-
-- **Search Operations**: < 1000ms per API call
-- **CRUD Operations**: < 1500ms per operation
-- **Batch Operations**: < 3000ms for 10 records
-- **Field Filtering**: < 500ms additional overhead
-- **Pagination**: < 200ms additional per offset
-
-#### **Unit & Integration Tests**
-
-```bash
-# Unit Tests (no API required)
 npm test                    # Run all tests
-npm run test:offline        # Run only offline tests (206 tests)
-npm run test:watch          # Watch mode for development
-
-# Integration Tests (requires API key and test data)
-npm run test:integration    # Run all integration tests (15 tests, 100% pass rate)
-npm run setup:test-data     # Create test data in your workspace
-```
-
-#### **Test Environment Setup**
-
-For E2E and integration tests, you need:
-
-1. **Create `.env` file** in project root:
-
-```bash
-# Required for E2E/Integration tests
-ATTIO_API_KEY=your_64_character_api_key_here
-PORT=3000
-LOG_LEVEL=debug
-NODE_ENV=development
-```
-
-2. **Verify API key** format (must be exactly 64 characters)
-3. **Run tests** to validate setup:
-
-```bash
-npm run build && npm run test:integration
+npm run test:offline        # Run only offline tests (no API required)
+npm run test:integration    # Integration tests (requires ATTIO_API_KEY)
+npm run e2e                 # E2E tests (requires ATTIO_API_KEY)
 ```
 
-See the [Testing Guide](./docs/testing.md) and [E2E Troubleshooting Guide](./docs/testing/e2e-troubleshooting.md) for detailed setup instructions.
+For E2E/integration tests, create `.env` with your `ATTIO_API_KEY`. See the [Testing Guide](./docs/testing.md) for detailed setup.
 
 ### **Available Scripts**
 

package/dist/api/attio-client.d.ts

@@ -48,19 +48,29 @@ export declare function createLegacyAttioClient(apiKey: string): AxiosInstance;
  */
 export declare function getAttributeSchema(objectSlug: string, attributeSlug: string): Promise<AttioAttributeSchema>;
 /**
- * Lists the available options for a select attribute.
+ * Lists the available options for a select attribute on an object.
  * @param objectSlug - The slug of the object.
  * @param attributeSlug - The slug of the select attribute.
+ * @param showArchived - Whether to include archived options.
  * @returns A list of available select options.
  */
-export declare function getSelectOptions(objectSlug: string, attributeSlug: string): Promise<AttioSelectOption[]>;
+export declare function getSelectOptions(objectSlug: string, attributeSlug: string, showArchived?: boolean): Promise<AttioSelectOption[]>;
+/**
+ * Lists the available options for a select attribute on a list.
+ * @param listId - The ID or slug of the list.
+ * @param attributeSlug - The slug of the select attribute.
+ * @param showArchived - Whether to include archived options.
+ * @returns A list of available select options.
+ */
+export declare function getListSelectOptions(listId: string, attributeSlug: string, showArchived?: boolean): Promise<AttioSelectOption[]>;
 /**
  * Lists the available statuses for a status attribute.
  * @param objectSlug - The slug of the object.
  * @param attributeSlug - The slug of the status attribute.
+ * @param showArchived - Whether to include archived statuses.
  * @returns A list of available statuses.
  */
-export declare function getStatusOptions(objectSlug: string, attributeSlug: string): Promise<AttioStatusOption[]>;
+export declare function getStatusOptions(objectSlug: string, attributeSlug: string, showArchived?: boolean): Promise<AttioStatusOption[]>;
 /**
  * Initializes the global API client with the provided API key
  *

package/dist/api/attio-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attio-client.d.ts","sourceRoot":"","sources":["../../src/api/attio-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAc,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG7C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EAGb,MAAM,oBAAoB,CAAC;AAa5B,eAAO,MAAM,eAAe,iBAAc,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAmCxC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;AACxE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;AAqEjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAqBd;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0DrE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CAoEzE"}
+{"version":3,"file":"attio-client.d.ts","sourceRoot":"","sources":["../../src/api/attio-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAc,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG7C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EAGb,MAAM,oBAAoB,CAAC;AAa5B,eAAO,MAAM,eAAe,iBAAc,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAmCxC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;AACxE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;AAqEjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAqBd;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0DrE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB9B;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB9B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CAoEzE"}