Relentless MCP Server

Instructions

Implementation Reference

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

  The handler function for the 'relentless_insert' tool. It validates the input data (optionally skipping validation), performs a POST request to the Relentless API to insert the data into the specified Notion database, handles retries and errors, and returns the API response.
  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)

  Input schema definition for the relentless_insert tool, specifying the expected parameters: database (string), data (object), and optional skipValidation (boolean).
  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)

  Registration of the 'relentless_insert' tool in the ListToolsRequestSchema handler, including name, description, and input schema.
  { 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/index.ts:176-185 (helper)

  Helper function to fetch the database schema from Relentless API, used for pre-insert validation in relentless_insert.
  async function getDatabaseSchema(dbName: string): Promise<DatabaseSchema | null> { try { const endpoint = `${RELENTLESS_API_BASE}/api/v1/public/db/${dbName}/schema` const schema = await relentlessRequest(endpoint, undefined, 1) // No retry for schema return schema as DatabaseSchema } catch (error) { console.error(`⚠️ Could not fetch schema for ${dbName}: ${error}`) return null } }
• src/database-validator.ts:50-127 (helper)

  validateWithSchema method from DatabaseValidator class, performs detailed validation of insert data against the database schema before insertion.
  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: [] } } }