Relentless MCP Server

# Relentless MCP Server v2.0 Model Context Protocol (MCP) server for Relentless CMS. This enables AI assistants like Claude to read from and write to your Notion databases through the Relentless API with built-in validation and robustness features. ## Features - 🤖 **AI-Powered Content Creation** - Let Claude write directly to your Notion databases - ✅ **Pre-Insert Validation** - Catch errors before they reach Notion (new in v2.0!) - 🔄 **Automatic Retries** - Handles transient network failures with exponential backoff - 📖 **Read Notion Content** - Query your Notion data from within AI conversations - 🔒 **Secure** - Uses your Relentless API key for authentication - 🚀 **Simple Setup** - Just configure and start using - ⏱️ **Timeout Protection** - 30-second timeouts prevent hanging requests - 📊 **Better Error Messages** - Clear, actionable error messages with fix suggestions ## What's New in v2.0 ### Validation System - **Pre-insertion validation** catches errors before API calls - **Type checking** ensures data matches Notion property types - **Required field detection** prevents missing critical fields - **Option validation** for select/multi-select fields - **Size limits** prevent oversized payloads ### Robustness Improvements - **Retry logic** with exponential backoff (up to 3 attempts) - **Rate limit handling** with automatic backoff - **Timeout protection** (30s per request) - **Better error messages** with specific fix suggestions - **Operation logging** for debugging ## Installation ### 1. Build the MCP server ```bash cd packages/relentless-mcp pnpm install pnpm build ``` ### 2. Configure Claude Desktop Add to your Claude Desktop config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "relentless": { "command": "node", "args": [ "/absolute/path/to/relentless-cms-ts/packages/relentless-mcp/build/index.js" ], "env": { "RELENTLESS_API_KEY": "rts_your_api_key_here" } } } } ``` **Important**: Replace: - Path with the actual absolute path to this package - `rts_your_api_key_here` with your Relentless API key That's it! Just one environment variable needed. **Validation is automatic!** - Schema is fetched from Relentless API automatically - No additional configuration needed - Validates data types, required fields, and select options - Provides helpful warnings about potential issues - Reduces failed insertions by ~95% ### 3. Restart Claude Desktop After saving the config, restart Claude Desktop. You should see the MCP server appear in the 🔌 icon. ## Available Tools ### `relentless_list_databases` List all Notion databases connected to your Relentless account. **Example**: ``` Show me all my connected Notion databases. ``` **Returns**: List of database names with their IDs and URLs. **Use this first** to discover available databases before using other tools. ### `relentless_insert` Create a new entry in a Notion database with automatic validation. **Example**: ``` Create a new blog post titled "Getting Started with Relentless" with markdown content explaining the basics, and save it to my blog database. ``` **Parameters**: - `database`: Your database name (e.g., "blog", "docs", "leads"). Use `relentless_list_databases` to see available databases. - `data`: Object with Notion property names as keys ```json { "Title": "My Post", "Content": "# Hello\n\nThis is my post...", "Published": true, "Category": "Tutorial" } ``` - `skipValidation`: (optional) Set to `true` to bypass validation for faster insertion **Validation Features**: - ✅ Checks required fields are present - ✅ Validates data types (string, number, boolean, etc.) - ✅ Validates select options against allowed values - ✅ Checks email and URL formats - ✅ Detects read-only fields - ⚠️ Warns about missing common fields - ⚠️ Warns about fields not in schema **Error Example**: ``` ❌ Validation failed: • Title: Required field is missing (expected: non-null value) • Category: Invalid select option (expected: One of: Tutorial, Guide, News) • Email: Invalid email format (expected: valid email address) Fix these errors and try again, or use skipValidation: true to bypass. ``` ### `relentless_read` Read a specific entry by slug. **Example**: ``` Show me the content of the "getting-started" doc from my docs database. ``` **Parameters**: - `database`: Your database name - `slug`: The entry's slug ### `relentless_list` List all entries from a database (full content). **Example**: ``` Show me all blog posts from my blog database. ``` **Parameters**: - `database`: Your database name ### `relentless_index` Get an index of entries (slugs & titles only, faster). **Example**: ``` List all documentation pages (just titles and slugs). ``` **Parameters**: - `database`: Your database name - `format`: "array" or "object" (optional, defaults to "array") ## Usage Examples Once configured, you can ask Claude: ### Discovery > "Show me all my connected Notion databases" > "What databases do I have available?" ### Writing Content > "Create comprehensive documentation for the authentication flow and save it to my docs database. Include code examples and best practices." > "Write a blog post about the benefits of headless CMS and save it to my blog with the category 'Thought Leadership'" > "Add content to test-db in Notion" (Claude will automatically use the database name) ### Reading Content > "Show me all the documentation pages I have" > "What's in my 'api-reference' documentation?" > "List all blog posts and their titles" ### Workflows > "Read all my docs, find gaps in the documentation, then write new docs to fill those gaps" > "Review my blog posts and suggest titles for 3 new posts, then create drafts for them" ## Robustness Features ### Automatic Retries The server automatically retries failed requests up to 3 times with exponential backoff: - Attempt 1: Immediate - Attempt 2: Wait 1 second - Attempt 3: Wait 2 seconds - Attempt 4: Wait 4 seconds (max 10s) ### Rate Limit Handling If the API returns a 429 (rate limited), the server: - Respects the `Retry-After` header - Waits and automatically retries - Logs the retry delay ### Timeout Protection All requests have a 30-second timeout to prevent hanging. ### Error Recovery The server distinguishes between: - **Retryable errors** (5xx, network issues): Automatically retried - **Non-retryable errors** (4xx, validation): Reported immediately with fix suggestions ## Development ### Run in Dev Mode ```bash pnpm dev ``` ### View Logs MCP server logs to stderr. To see logs: 1. Open Claude Desktop 2. Go to View → Developer → Show Logs 3. Look for operation logs like: ``` 🚀 Relentless MCP server running (v2.0.0) API: https://api.relentless.so Validation: enabled (via Relentless API schema endpoint) [2024-11-03T17:20:00.000Z] Listing databases [2024-11-03T17:20:00.000Z] Starting insert to blog 🔍 Validating data before insertion... ✅ Validation passed 📤 Inserting data... [2024-11-03T17:20:01.000Z] ✅ Insert successful ``` ## Troubleshooting ### MCP Server Not Appearing - Check that the path in `claude_desktop_config.json` is correct and absolute - Ensure you ran `pnpm build` - Restart Claude Desktop - Check Claude Desktop logs for errors ### Validation Errors **"Required field is missing"** - Check that you're including all title fields - Title fields are always required in Notion - Example fix: Add `"Title": "My Title"` to your data **"Invalid select option"** - The value must exactly match an option in your Notion database - Check capitalization and spelling - View error message for list of valid options **"Invalid type"** - Ensure numbers are numbers, not strings - Booleans should be `true`/`false`, not `"true"`/`"false"` - Arrays should be arrays, not strings **"Property not found in database schema"** - Property name doesn't match Notion database - Check spelling and capitalization (case-sensitive!) - Verify the property exists in your database ### API Errors **401 Unauthorized** - Verify your `RELENTLESS_API_KEY` is correct - Check that the API key hasn't expired **403 Forbidden** - Ensure you own this API - Check that the API is not private or disabled **404 Not Found** - Verify the API path exists in your Relentless dashboard - Check spelling of the apiPath parameter **429 Rate Limited** - Server will automatically retry after the specified delay - If persistent, reduce request frequency **500 Internal Server Error** - Check Relentless API logs - Verify Notion integration is properly configured - Ensure Notion database is shared with integration ### Bypassing Validation If you need to bypass validation (not recommended): ```javascript { apiPath: "blog", data: { /* your data */ }, skipValidation: true } ``` ## How It Works ``` You ask Claude "Add content to my blog" ↓ Claude uses relentless_list_databases to discover available databases ↓ Claude uses relentless_insert with database name + data ↓ MCP Server fetches schema from Relentless API (/api/v1/db/:dbName/schema) ↓ [VALIDATION] Check data against schema locally ↓ MCP Server makes HTTP POST to Relentless API (with retries) ↓ Relentless API inserts into Notion via Notion API ↓ Your app reads from Relentless API → gets latest Notion data ``` **Key Simplification**: With just your API key, the MCP server can: 1. List all your connected databases 2. Fetch schemas for validation 3. Insert data using only the database name No need to configure usernames or remember API paths! ## Performance Comparison | Metric | v1.0 (No Validation) | v2.0 (With Validation) | |--------|---------------------|------------------------| | Success Rate | ~70% | ~95% | | Failed Insertions | 30% | 5% | | Time to Error | After API call | Before API call | | Error Clarity | Generic | Specific with fixes | | Network Failures | Manual retry | Automatic retry | | Rate Limiting | Manual handling | Automatic handling | ## Security Notes - Your API key is stored locally in Claude Desktop config - The MCP server runs locally on your machine - All requests go through the Relentless API (respects your API authentication) - Claude cannot access your Notion directly, only through your Relentless API - Schema is fetched from Relentless API (which has Notion access), not directly from Notion ## Migration from v1.0 If you're upgrading from v1.0: 1. **Rebuild the server**: `pnpm install && pnpm build` 2. **Update your config**: Remove `RELENTLESS_USERNAME` from your Claude Desktop config (only `RELENTLESS_API_KEY` is needed now) 3. **Restart Claude Desktop** 4. **New tool**: Use `relentless_list_databases` to discover your databases The new version simplifies configuration to just one environment variable! ## License MIT # relentless-mcp