CHANGELOG.md•5.34 kB
# Changelog
## [Unreleased] - 2025-10-16
### Fixed
- **Enhanced Error Messages and Validation**
- Added comprehensive input validation for all create tools
- 400 errors now include helpful format examples and common issues
- Logs now include full parameter details for debugging
- Validation prevents bad requests before hitting API:
- Count parameters must be >= 1
- Cron expressions must have exactly 5 fields
- Options format must include options array
- Maximum 150 options enforced client-side
- Error responses include concrete examples of correct format
- **Improved Tool Descriptions for AI Clarity**
- Added prominent "IMPORTANT PARAMETER FORMATS" section to all create tools
- Top-level descriptions now include complete JSON examples
- Explicitly states object vs string requirements (NOT a string)
- Shows exact format needed for complex parameters
- **Why this matters**: MCP protocol may not clearly expose nested Zod schemas
- AI callers can now see format requirements without parsing nested schema
- **CRITICAL: Schema Consistency Across All Tools**
- Fixed inconsistent parameter formats that were confusing AI callers
- **`criteria` parameter**: Now consistently uses object format `[{description: string}]` across all tools:
- `create_webset.searchCriteria`
- `create_search.criteria`
- `create_monitor.criteria`
- **`entity` parameter**: Consistently uses object format `{type: string}`
- **`options` parameter**: Consistently uses object array format `[{label: string}]`
- Updated TypeScript types to match actual Websets API response formats
- **Impact**: AI assistants (Claude, Cursor, etc.) will no longer get confused about parameter formats
- **Enhanced Tool Descriptions with Examples**
- Added inline JSON examples to all complex parameter descriptions
- Examples show exact object structures expected by the API
- Prevents common mistakes like passing strings instead of objects
- **Monitor Tool Enhancement**
- Added missing parameters to `create_monitor`:
- `criteria`: Filter criteria for scheduled searches
- `entity`: Entity type configuration
- `behavior`: Append vs override behavior for new items
- Now fully aligned with Websets API monitor capabilities
- **BREAKING FIX**: `create_enrichment` tool - Removed invalid `name` parameter that was causing API errors
- The Exa API only accepts `description` (required) and optional `format`, `options`, `metadata`
- The `title` field is auto-generated by the API based on description and format
- Updated tool to match official API documentation
### Added
- **New Documentation: TOOL_SCHEMAS.md**
- Comprehensive reference guide for all tool parameters
- Exact JSON examples for every tool
- Common mistakes section with ❌ wrong vs ✅ correct examples
- Helps AI callers understand exact schema requirements
- Referenced prominently in README for easy discovery
- **Enhanced enrichment creation** with optional parameters:
- `format`: Specify data type (text, date, number, options, email, phone, url)
- `options`: Define multiple choice options when format is 'options'
- `metadata`: Add custom key-value pairs to enrichments
- **New Item Management Tools**:
- `get_item`: Get a specific item from a webset with all enrichment data
- **New Search Operations Tools**:
- `create_search`: Create new searches independently of webset creation
- `get_search`: Get search details, status, and progress
- `cancel_search`: Cancel running search operations
- **New Enrichment Management Tools**:
- `get_enrichment`: Get enrichment details and status
- `update_enrichment`: Update enrichment metadata
- `delete_enrichment`: Delete enrichments and their data
- `cancel_enrichment`: Cancel running enrichment operations
### Changed
- Improved tool organization following MCP best practices:
- Action-oriented naming (consistent `action_resource` pattern)
- Organized tools into logical categories (Webset, Item, Search, Enrichment, Monitor)
- All tools now follow stateless and idempotent design principles
- Updated documentation:
- README now organized by tool categories
- Added comprehensive examples for new enrichment features
- Updated API parameter documentation to match actual Exa API
### Developer Notes
- Total tools: **16** (increased from 8)
- All tools tested and verified working with Exa API
- Full TypeScript type safety maintained
- Consistent error handling across all tools
- Build size: 588.55 KB (stdio), 1.87 MB (shttp)
### Migration Guide
If you were using `create_enrichment` with the `name` parameter:
**Before:**
```json
{
"websetId": "webset_123",
"name": "Revenue",
"description": "Annual revenue in USD"
}
```
**After:**
```json
{
"websetId": "webset_123",
"description": "Annual revenue in USD"
}
```
The enrichment title will be automatically generated by the API. You can optionally specify format:
```json
{
"websetId": "webset_123",
"description": "Annual revenue in USD",
"format": "number"
}
```
Or use multiple choice with options:
```json
{
"websetId": "webset_123",
"description": "Select the industry sector",
"format": "options",
"options": [
{"label": "Technology"},
{"label": "Healthcare"},
{"label": "Finance"}
]
}
```