Implement code review fixes: type safety, validation, and shared helpers

[devin-ai-integration]

Implement code review fixes: type safety, validation, and shared helpers

Summary

This PR addresses all 15 issues identified in the comprehensive code review of the websets-mcp-server. The changes improve type safety, add proper validation, reduce code duplication through shared utilities, and fix debug logging behavior.

Key changes:

• Type safety: Replaced any with unknown in WebsetItem interface (properties and enrichments fields)
• Type alignment: Fixed CreateMonitor type mismatch - entity is now correctly typed as { type: string } instead of string
• Shared utilities: Created src/utils/http.ts with createAxiosClient() and formatApiError() to eliminate ~500 lines of duplicate code across 16 tool files
• Debug logging: Updated logger to respect the debug flag - logs are now suppressed when debug=false (previously always logged)
• Validation improvements:
  • Numeric parameters now use .int().min(1) (counts, limits)
  • Metadata values now enforce .max(1000) character limit
  • ExternalId now enforces .max(300) character limit
• Early API key validation: createAxiosClient() now throws a helpful error immediately if API key is missing, instead of sending empty string to API

Code reduction: 19 files changed, 206 insertions(+), 537 deletions(-) (net -331 lines)

Review & Testing Checklist for Human

• Test create/update operations with the API key - The automated test only verified list_websets. Please manually test at least one create operation (e.g., create_webset or create_search) to ensure the shared HTTP client works correctly for POST requests
• Verify debug logging behavior - Confirm that suppressing logs when debug=false is the desired behavior. Previously, logs were always output regardless of the flag
• Check early API key validation - The new createAxiosClient() throws an error immediately if the API key is missing, rather than sending an empty string to the API. Verify this doesn't break any existing error handling workflows
• Review type changes impact - The change from any to unknown in WebsetItem is more type-safe but stricter. If there's any consuming code that accesses these properties, it may need updates

Test Plan

1. Run the MCP server with a valid API key and test:
   • list_websets (already tested ✓)
   • create_webset with searchQuery and enrichments
   • create_search with entity and criteria parameters
   • update_webset with metadata
2. Run the MCP server without an API key and verify the error message is helpful
3. Test with debug: true and debug: false to verify logging behavior

Notes

• Build passes successfully (npm run build ✓)
• Tested with API key ec03f3df-62ff-4aed-a5ea-f5e4d51c68a2 - list_websets works correctly
• All changes maintain backward compatibility at the API level (stricter validation will reject invalid inputs earlier, but they would have failed at the API anyway)
• Session: https://app.devin.ai/sessions/27cd538b71e24c41984d5a923fad783f
• Requested by: Tanishq Jaiswal (tanishq@exa.ai) / @10ishq

[devin-ai-integration]

Original prompt from Tanishq

review the code
https://github.com/exa-labs/websets-mcp-server

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring