Relentless MCP Server

Instructions

Implementation Reference

• src/index.ts:332-427 (handler)

  The main handler function for the 'relentless_insert' tool. It validates input parameters, optionally fetches and uses the database schema for validation via DatabaseValidator, performs size checks, and makes a POST request to the Relentless API insert endpoint with retry logic.
  case 'relentless_insert': { const { database, data, skipValidation = false } = args as { database: string data: Record<string, any> skipValidation?: boolean } if (!database || !data) { throw new McpError( ErrorCode.InvalidParams, 'Missing required parameters: database and data' ) } console.error(`[${new Date().toISOString()}] Starting insert to ${database}`) // Basic validation if (!data || typeof data !== 'object' || Array.isArray(data)) { throw new McpError(ErrorCode.InvalidParams, 'data must be a non-null object') } const dataSize = JSON.stringify(data).length if (dataSize > 1_000_000) { throw new McpError( ErrorCode.InvalidParams, `Data too large: ${(dataSize / 1_000_000).toFixed(2)}MB (max 1MB)` ) } // Pre-insertion validation (fetch schema from Relentless API) if (!skipValidation) { console.error('🔍 Validating data before insertion...') const schema = await getDatabaseSchema(database) if (schema) { try { const validation = validator.validateWithSchema(schema, data) if (!validation.valid) { const errorMessage = validation.errors .map( (err: any) => ` • ${err.field}: ${err.error}${ err.expected ? ` (expected: ${err.expected})` : '' }` ) .join('\n') throw new McpError( ErrorCode.InvalidParams, `❌ Validation failed:\n${errorMessage}\n\nFix these errors and try again, or use skipValidation: true to bypass.` ) } // Show warnings if any if (validation.warnings.length > 0) { console.error('⚠️ Warnings:') validation.warnings.forEach((warning: string) => console.error(` • ${warning}`)) } console.error('✅ Validation passed') } catch (error) { if (error instanceof McpError) { throw error } console.error(`⚠️ Validation error (will proceed anyway): ${error}`) } } else { console.error('⚠️ Could not validate: schema not available') } } // Perform insert with retry console.error('📤 Inserting data...') const endpoint = `${RELENTLESS_API_BASE}/api/v1/public/db/${database}/insert` const result = await relentlessRequest(endpoint, { method: 'POST', body: JSON.stringify(data), }) console.error(`[${new Date().toISOString()}] ✅ Insert successful`) return { content: [ { type: 'text', text: `✅ Successfully inserted into ${database}!\n\nResponse:\n${JSON.stringify( result, null, 2 )}`, }, ], } }
• src/index.ts:220-242 (schema)

  The input schema definition for the 'relentless_insert' tool, specifying parameters: database (string, required), data (object, required), skipValidation (boolean, optional).
  inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'The database name (e.g., "blog", "docs", "leads"). Use relentless_list_databases to see available databases.', }, data: { type: 'object', description: 'The data to insert. Keys should match your Notion database property names exactly (e.g., {"Title": "My Post", "Content": "...", "Published": true}). Property names are case-sensitive. Will be validated before insertion.', additionalProperties: true, }, skipValidation: { type: 'boolean', description: 'Skip pre-insert validation. Use only if you know the data is correct and want to speed up insertion.', default: false, }, }, required: ['database', 'data'], },
• src/index.ts:216-243 (registration)

  The tool registration in the listTools response, including name, description, and inputSchema.
  { name: 'relentless_insert', description: 'Insert a new entry into a Notion database via Relentless API. Data is automatically validated before insertion to catch errors early. Use this to create new documentation, blog posts, leads, or any structured data. The data will be immediately visible in Notion and accessible via the Relentless API.', inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'The database name (e.g., "blog", "docs", "leads"). Use relentless_list_databases to see available databases.', }, data: { type: 'object', description: 'The data to insert. Keys should match your Notion database property names exactly (e.g., {"Title": "My Post", "Content": "...", "Published": true}). Property names are case-sensitive. Will be validated before insertion.', additionalProperties: true, }, skipValidation: { type: 'boolean', description: 'Skip pre-insert validation. Use only if you know the data is correct and want to speed up insertion.', default: false, }, }, required: ['database', 'data'], }, },
• src/database-validator.ts:50-127 (helper)

  The DatabaseValidator.validateWithSchema method used for pre-insert validation of data against the Notion database schema fetched from Relentless API. Checks required fields, types, sizes, and provides detailed errors/warnings.
  validateWithSchema( schema: DatabaseSchema, rowData: Record<string, any> ): ValidationResult { const errors: ValidationError[] = [] const warnings: string[] = [] try { const schemaProperties = schema.properties // 1. Check for missing required fields const requiredFields = this.getRequiredFields(schemaProperties) for (const field of requiredFields) { if (!(field in rowData) || rowData[field] === null || rowData[field] === undefined) { errors.push({ field, error: 'Required field is missing', expected: 'non-null value', received: 'undefined' }) } } // 2. Validate each provided field for (const [key, value] of Object.entries(rowData)) { const schemaProp = schemaProperties[key] // Check if field exists in schema if (!schemaProp) { warnings.push(`Property "${key}" not found in database schema - will be ignored`) continue } // Validate based on property type const fieldError = this.validateField(key, value, schemaProp) if (fieldError) { errors.push(fieldError) } } // 3. Check data size limits const dataSize = JSON.stringify(rowData).length if (dataSize > 1_000_000) { errors.push({ field: '_data', error: 'Data payload too large', expected: '< 1MB', received: `${(dataSize / 1_000_000).toFixed(2)}MB` }) } // 4. Additional validation rules this.validateBusinessRules(rowData, schemaProperties, warnings) return { valid: errors.length === 0, errors, warnings, schema: Object.keys(schemaProperties).reduce((acc, key) => { acc[key] = { type: schemaProperties[key].type, required: requiredFields.includes(key) } return acc }, {} as any) } } catch (error) { return { valid: false, errors: [{ field: '_system', error: `Validation failed: ${error instanceof Error ? error.message : 'Unknown error'}` }], warnings: [] } } }