relentless_insert

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: []
      }
    }
  }