QuickBase MCP Server

Instructions

Implementation Reference

• src/quickbase/client.ts:325-383 (handler)

  The core handler function that executes the tool logic: validates relationship integrity by checking if parent/child tables exist, if the foreign key field is a reference field, and scans child records for orphaned ones where foreign key values don't correspond to existing parent records.

  async validateRelationship(
    parentTableId: string,
    childTableId: string,
    foreignKeyFieldId: number
  ): Promise<{ isValid: boolean; issues: string[]; orphanedRecords: number }> {
    const issues: string[] = [];
    let orphanedRecords = 0;
  
    try {
      // Check if parent table exists
      await this.getTableInfo(parentTableId);
    } catch (error) {
      issues.push(`Parent table ${parentTableId} not found`);
    }
  
    try {
      // Check if child table exists
      await this.getTableInfo(childTableId);
    } catch (error) {
      issues.push(`Child table ${childTableId} not found`);
    }
  
    try {
      // Check if foreign key field exists
      const childFields = await this.getTableFields(childTableId);
      const foreignKeyField = childFields.find(field => field.id === foreignKeyFieldId);
      if (!foreignKeyField) {
        issues.push(`Foreign key field ${foreignKeyFieldId} not found in child table`);
      } else if (foreignKeyField.fieldType !== 'reference') {
        issues.push(`Field ${foreignKeyFieldId} is not a reference field`);
      }
  
      // Check for orphaned records (child records with invalid parent references)
      const childRecords = await this.getRecords(childTableId, {
        select: [3, foreignKeyFieldId], // Record ID and foreign key
        where: `{${foreignKeyFieldId}.XEX.''}`
      });
  
      for (const record of childRecords) {
        const foreignKeyValue = record[foreignKeyFieldId]?.value;
        if (foreignKeyValue) {
          try {
            await this.getRecord(parentTableId, foreignKeyValue);
          } catch (error) {
            orphanedRecords++;
          }
        }
      }
  
         } catch (error) {
       issues.push(`Error validating relationship: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
  
    return {
      isValid: issues.length === 0 && orphanedRecords === 0,
      issues,
      orphanedRecords
    };
  }

• src/tools/index.ts:467-479 (registration)

  Registers the 'quickbase_validate_relationship' tool in the MCP tools array with its name, description, and JSON input schema.

  {
    name: 'quickbase_validate_relationship',
    description: 'Validate the integrity of a table relationship',
    inputSchema: {
      type: 'object',
      properties: {
        parentTableId: { type: 'string', description: 'Parent table ID' },
        childTableId: { type: 'string', description: 'Child table ID' },
        foreignKeyFieldId: { type: 'number', description: 'Foreign key field ID to validate' }
      },
      required: ['parentTableId', 'childTableId', 'foreignKeyFieldId']
    }
  },

• src/tools/index.ts:96-100 (schema)

  Zod schema for input validation of the tool parameters: parentTableId, childTableId, foreignKeyFieldId.

  const ValidateRelationshipSchema = z.object({
    parentTableId: z.string().describe('Parent table ID'),
    childTableId: z.string().describe('Child table ID'),
    foreignKeyFieldId: z.number().describe('Foreign key field ID to validate')
  });