mcp-quickbase 2.1.0 → 2.2.0

package/.sdd/tickets/RELS_relationship-management/README.md

@@ -0,0 +1,98 @@
+# Ticket: Relationship Management
+
+**Ticket ID:** RELS
+**Status:** Planning Complete
+**Created:** 2025-12-28
+
+## Summary
+
+Implement full support for managing table-to-table relationships in the MCP Quickbase server. This includes four tools: `get_relationships`, `create_relationship`, `update_relationship`, and `delete_relationship`. Special attention is given to tool descriptions that clearly communicate destructive behavior to AI agents, ensuring they request user confirmation before performing irreversible operations.
+
+## Problem Statement
+
+The MCP Quickbase server currently lacks support for managing table-to-table relationships through the Quickbase API. Relationships are fundamental to Quickbase applications, enabling linked records, lookup fields (displaying parent data in child records), and summary fields (aggregating child data in parent records). Without this capability, agents cannot:
+
+- Explore existing table structures and data connections
+- Create new relationships when building applications
+- Enhance relationships with additional calculated fields
+- Remove relationships when refactoring applications
+
+## Proposed Solution
+
+Add a new `relationships` domain to the tools directory following existing patterns. Implement four tools mapping directly to the Quickbase Relationships API:
+
+| Tool | Operation | Safety Level |
+|------|-----------|--------------|
+| `get_relationships` | List all relationships for a table | Safe (read-only) |
+| `create_relationship` | Create new relationship with optional lookup/summary fields | Safe (creates new) |
+| `update_relationship` | Add lookup/summary fields to existing relationship | Safe (additive only) |
+| `delete_relationship` | Delete entire relationship including all lookup/summary fields | **DESTRUCTIVE** |
+
+### Key Design Decisions
+
+1. **Agent-Safety-First Descriptions**: Tool descriptions explicitly warn about destructive operations and recommend user confirmation
+2. **Flat Parameter Structure**: Simple, snake_case parameters following existing conventions
+3. **Separate Domain Directory**: `src/tools/relationships/` with domain index and individual tool files
+
+## Relevant Agents
+
+- **ticket-planner** (planning phase) - Completed
+- **task-creator** (task generation) - Next step
+- **implement-feature** (implementation) - Phases 1-3
+- **verify-task** (verification) - Phase 4
+- **commit-task** (commit) - Phase 4
+
+## Deliverables
+
+### Code Deliverables
+
+- `src/tools/relationships/index.ts` - Domain registration
+- `src/tools/relationships/get_relationships.ts` - GET tool
+- `src/tools/relationships/create_relationship.ts` - POST tool
+- `src/tools/relationships/update_relationship.ts` - POST tool (update)
+- `src/tools/relationships/delete_relationship.ts` - DELETE tool
+- `src/__tests__/tools/relationships.test.ts` - Unit tests
+- Updated `src/tools/index.ts` - Registration integration
+
+### Documentation Deliverables
+
+Planning documents in [planning/](planning/):
+- Comprehensive tool descriptions with safety warnings
+- API endpoint mappings
+- Type definitions
+
+## Planning Documents
+
+- [analysis.md](planning/analysis.md) - Problem analysis, API research, success criteria
+- [architecture.md](planning/architecture.md) - Solution design, component interfaces, data flow
+- [plan.md](planning/plan.md) - 4-phase execution plan with agent assignments
+- [quality-strategy.md](planning/quality-strategy.md) - Testing approach, coverage requirements
+- [security-review.md](planning/security-review.md) - Security assessment, destructive operation safeguards
+
+## Phase Overview
+
+| Phase | Objective | Tools |
+|-------|-----------|-------|
+| 1 | Foundation & Read Operations | `get_relationships` |
+| 2 | Write Operations (Non-Destructive) | `create_relationship`, `update_relationship` |
+| 3 | Destructive Operations with Safety | `delete_relationship` |
+| 4 | Integration & Verification | All tools tested and registered |
+
+## Tasks
+
+See [tasks/](tasks/) for all ticket tasks (to be created by task-creator agent).
+
+## API Reference
+
+**Quickbase Relationships API Endpoints:**
+
+| Method | Endpoint | Tool |
+|--------|----------|------|
+| GET | `/v1/tables/{tableId}/relationships` | `get_relationships` |
+| POST | `/v1/tables/{tableId}/relationships` | `create_relationship` |
+| POST | `/v1/tables/{tableId}/relationships/{relationshipId}` | `update_relationship` |
+| DELETE | `/v1/tables/{tableId}/relationships/{relationshipId}` | `delete_relationship` |
+
+## Next Step
+
+**Recommended:** Run `/sdd:review RELS` to validate planning documents before creating tasks.

package/.sdd/tickets/RELS_relationship-management/planning/analysis.md

@@ -0,0 +1,190 @@
+# Analysis: Relationship Management
+
+## Problem Definition
+
+The MCP Quickbase server currently lacks support for managing table-to-table relationships through the Quickbase API. Relationships are a fundamental feature in Quickbase that allow linking records between tables, creating lookup fields (to display parent data in child records), and summary fields (to aggregate child data in parent records). Without relationship management capabilities, agents cannot:
+
+1. Query existing relationships between tables
+2. Create new relationships to link tables
+3. Add lookup/summary fields to existing relationships
+4. Delete relationships when no longer needed
+
+This gap significantly limits the utility of the MCP server for database schema management and application configuration tasks.
+
+## Context
+
+### Why This Work Is Needed
+
+Quickbase applications commonly have complex table structures with multiple relationships. Common use cases include:
+
+- **Project Management**: Projects (parent) -> Tasks (child) with lookup fields for project name, summary fields for task counts
+- **CRM**: Customers (parent) -> Orders (child) with summary fields for total revenue
+- **Inventory**: Warehouses (parent) -> Products (child) with lookup fields for location info
+
+Agents need to understand and modify these relationships to:
+- Explore application schemas
+- Create new tables with proper relationships
+- Add calculated fields that span relationships
+- Refactor application structure
+
+### Quickbase Relationships API
+
+The Quickbase RESTful API provides four endpoints for relationship management:
+
+| Operation | Method | Endpoint | Description |
+|-----------|--------|----------|-------------|
+| Get Relationships | GET | `/v1/tables/{tableId}/relationships` | List all relationships for a table |
+| Create Relationship | POST | `/v1/tables/{tableId}/relationships` | Create a new relationship with optional lookup/summary fields |
+| Update Relationship | POST | `/v1/tables/{tableId}/relationships/{relationshipId}` | Add lookup/summary fields to existing relationship |
+| Delete Relationship | DELETE | `/v1/tables/{tableId}/relationships/{relationshipId}` | Delete relationship and all associated lookup/summary fields |
+
+## Existing Solutions
+
+### Industry Patterns
+
+Other database management tools handle relationships similarly:
+- **Airtable API**: Provides link fields and rollup fields with similar semantics
+- **Notion API**: Relations and rollups follow a comparable pattern
+- **Microsoft Power Platform**: Dataverse relationships use similar parent-child paradigms
+
+### Codebase Patterns
+
+The existing codebase has established patterns for tool implementation:
+
+1. **Tool Structure** (`src/tools/base.ts`):
+   - Tools extend `BaseTool<TParams, TResult>`
+   - Implement `name`, `description`, `paramSchema`, and `run()` method
+   - Use `QuickbaseClient` for API calls
+
+2. **Domain Organization** (`src/tools/index.ts`):
+   - Tools grouped by domain (apps, tables, fields, records, files, reports)
+   - Each domain has `index.ts` with `register*Tools()` function
+   - Exports tool classes and registration function
+
+3. **API Client Pattern** (`src/client/quickbase.ts`):
+   - Uses `request()` method with `RequestOptions`
+   - Supports GET, POST, PUT, DELETE, PATCH methods
+   - Automatic retry, caching (for GET), and rate limiting
+
+4. **Type Definitions**:
+   - Interfaces for params and results defined in tool files
+   - JSON Schema for `paramSchema` used by MCP protocol
+   - Zod validation happens in base class
+
+## Current State
+
+The codebase currently supports:
+- **Apps**: create, update, list tables
+- **Tables**: create, update, get fields
+- **Fields**: create, update
+- **Records**: create, update, query, bulk operations
+- **Files**: upload, download
+- **Reports**: run
+
+Relationships are **not** currently supported. The `getTableFields` tool returns field information but does not include relationship metadata.
+
+## Research Findings
+
+### API Response Structures
+
+From the Quickbase API documentation (via Microsoft Learn connector reference):
+
+**Relationship Object**:
+```typescript
+interface Relationship {
+  id: number;                    // Relationship ID (foreign key field ID)
+  parentTableId: string;         // Parent table DBID
+  childTableId: string;          // Child table DBID
+  foreignKeyField: {             // Reference field in child table
+    id: number;
+    label: string;
+    type: string;
+  };
+  isCrossApp: boolean;           // Whether cross-app relationship
+  lookupFields: Array<{          // Lookup fields from parent
+    id: number;
+    label: string;
+    type: string;
+  }>;
+  summaryFields: Array<{         // Summary fields in parent
+    id: number;
+    label: string;
+    type: string;
+  }>;
+}
+```
+
+**Get Relationships Response**:
+```typescript
+interface GetRelationshipsResponse {
+  relationships: Relationship[];
+  metadata: {
+    skip: number;
+    totalRelationships: number;
+    numRelationships: number;
+  };
+}
+```
+
+### Destructive Operation Warning
+
+**DELETE Relationship is highly destructive**:
+- Deletes ALL lookup fields associated with the relationship
+- Deletes ALL summary fields associated with the relationship
+- Data in those fields is permanently lost
+- The reference field itself is NOT deleted
+- Cannot be undone
+
+This is the most destructive operation in this feature set and requires special handling for agent safety.
+
+### Key Constraints
+
+1. **Same-App Only**: Relationships can only be created between tables in the same app (cross-app relationships are read-only)
+2. **Reference Field Persistence**: The reference (foreign key) field remains after relationship deletion
+3. **Additive Updates**: Updating relationships only adds fields; existing fields are not deleted
+4. **Summary Field Complexity**: Summary fields require accumulation type (SUM, COUNT, AVG, MAX, MIN) and optional WHERE filter
+
+## Constraints
+
+### Technical Constraints
+
+1. **Quickbase API Limits**: Standard rate limiting applies (handled by existing client)
+2. **Table ID Required**: All operations require the child table ID
+3. **Relationship ID**: Required for update/delete; equals the foreign key field ID
+4. **Field Types**: Lookup/summary field types are determined by source fields
+
+### Business Constraints
+
+1. **Destructive Operations**: Must warn agents clearly about data loss
+2. **User Confirmation**: Destructive operations should request user confirmation
+3. **Consistency**: Must follow existing tool patterns and naming conventions
+
+### Time Constraints
+
+1. Focus on core CRUD operations first
+2. Advanced features (cross-app relationship viewing) can be deferred
+
+## Success Criteria
+
+### Functional Requirements
+
+- [ ] `get_relationships` tool lists all relationships for a table with complete metadata
+- [ ] `create_relationship` tool creates relationships with optional lookup/summary fields
+- [ ] `update_relationship` tool adds lookup/summary fields to existing relationships
+- [ ] `delete_relationship` tool removes relationships with appropriate warnings
+
+### Non-Functional Requirements
+
+- [ ] Tool descriptions clearly indicate destructive operations
+- [ ] Delete operation description strongly warns about data loss
+- [ ] All tools follow existing codebase patterns (BaseTool, naming, types)
+- [ ] Unit test coverage >= 35% (existing threshold)
+- [ ] All tools include parameter validation via JSON Schema
+- [ ] Error messages are actionable and specific
+
+### Agent Safety Requirements
+
+- [ ] Destructive tool descriptions include "DESTRUCTIVE" or "WARNING" labels
+- [ ] Delete tool description explains exactly what will be lost
+- [ ] Descriptions help agents understand when each tool is appropriate
+- [ ] Create/Update operations clearly explain their non-destructive nature

package/.sdd/tickets/RELS_relationship-management/planning/architecture.md

@@ -0,0 +1,413 @@
+# Architecture: Relationship Management
+
+## Overview
+
+This feature adds a new `relationships` domain to the MCP Quickbase server, following the established patterns used by other domains (apps, tables, fields, etc.). The implementation consists of four tools mapping directly to the Quickbase Relationships API endpoints, with special attention to tool descriptions that clearly communicate destructive behavior to AI agents.
+
+## Design Decisions
+
+### Decision 1: Separate Relationships Domain
+
+**Context:** Relationships could be implemented as part of the `tables` domain or as a new domain.
+
+**Decision:** Create a new `src/tools/relationships/` domain directory.
+
+**Rationale:**
+- Follows existing pattern where each API resource area has its own domain
+- Provides clear separation of concerns
+- Allows for future expansion (e.g., cross-app relationship tools)
+- Consistent with how `fields`, `records`, `files`, `reports` are organized
+
+### Decision 2: Agent-Safety-First Tool Descriptions
+
+**Context:** The delete operation is highly destructive, and agents may use tools without fully understanding consequences.
+
+**Decision:** Implement a description format that:
+1. Starts with clear action statement
+2. Includes WARNING label for destructive operations
+3. Lists exactly what will be deleted/lost
+4. Suggests safer alternatives where applicable
+5. Recommends user confirmation for destructive operations
+
+**Rationale:**
+- MCP tool descriptions are the primary way agents understand tool behavior
+- Explicit warnings reduce risk of unintended data loss
+- Following patterns from other enterprise API tools
+- Aligns with user requirement for "clearly indicate potentially destructive changes"
+
+### Decision 3: Flat Parameter Structure
+
+**Context:** The API has nested structures for summary fields (accumulationType, where, label).
+
+**Decision:** Use flat parameter structures with clear naming:
+```typescript
+{
+  summary_field_id: number;
+  summary_label: string;
+  summary_accumulation_type: string;
+  summary_where?: string;
+}
+```
+
+**Rationale:**
+- Matches existing tool patterns (e.g., `create_field`)
+- Simpler for agents to construct
+- Reduces nesting complexity in JSON Schema
+- Clear parameter names are self-documenting
+
+### Decision 4: TypeScript Interfaces for API Types
+
+**Context:** Need to represent Quickbase API response types.
+
+**Decision:** Define interfaces in each tool file for params and results, following existing patterns.
+
+**Rationale:**
+- Consistent with existing codebase (see `create_table.ts`, `create_field.ts`)
+- Keeps related types close to their usage
+- Enables strong typing throughout
+
+## Technology Choices
+
+| Component | Choice | Rationale |
+|-----------|--------|-----------|
+| Language | TypeScript | Existing codebase uses TypeScript with strict mode |
+| Validation | Zod (via base class) | Already integrated in BaseTool |
+| HTTP Client | QuickbaseClient | Existing client with retry, caching, rate limiting |
+| Testing | Jest | Existing test framework |
+| Linting | ESLint + Prettier | Existing configuration |
+
+## Component Design
+
+### Directory Structure
+
+```
+src/tools/relationships/
+  index.ts                    # Domain registration and exports
+  get_relationships.ts        # GET /relationships tool
+  create_relationship.ts      # POST /relationships tool
+  update_relationship.ts      # POST /relationships/{id} tool
+  delete_relationship.ts      # DELETE /relationships/{id} tool
+```
+
+### Component 1: GetRelationshipsTool
+
+**Responsibilities:**
+- Query all relationships for a given table
+- Support pagination (skip parameter)
+- Return relationship metadata including lookup and summary fields
+
+**Interface:**
+```typescript
+interface GetRelationshipsParams {
+  table_id: string;      // Required: Child table ID (DBID)
+  skip?: number;         // Optional: Pagination offset
+}
+
+interface GetRelationshipsResult {
+  relationships: Relationship[];
+  metadata: {
+    totalRelationships: number;
+    numRelationships: number;
+    skip: number;
+  };
+}
+```
+
+**Description Format:**
+```
+Gets all table-to-table relationships for a specified table. Returns both relationships
+where this table is the child (has reference fields pointing to parents) and where this
+table is the parent (has child tables referencing it). Use this tool to explore table
+structure and understand data connections before modifying relationships.
+```
+
+### Component 2: CreateRelationshipTool
+
+**Responsibilities:**
+- Create new relationship between tables
+- Optionally create lookup fields during creation
+- Optionally create summary field during creation
+
+**Interface:**
+```typescript
+interface CreateRelationshipParams {
+  table_id: string;              // Required: Child table ID
+  parent_table_id: string;       // Required: Parent table ID
+  foreign_key_label?: string;    // Optional: Label for reference field
+  lookup_field_ids?: number[];   // Optional: Parent field IDs to create as lookups
+  summary_field_id?: number;     // Optional: Child field ID to summarize
+  summary_label?: string;        // Optional: Label for summary field
+  summary_accumulation_type?: string;  // Required if summary_field_id: SUM/COUNT/AVG/MAX/MIN
+  summary_where?: string;        // Optional: Quickbase query filter for summary
+}
+
+// Note: JSON Schema validation must enforce that summary_accumulation_type is required
+// when summary_field_id is provided. Use conditional validation in paramSchema.
+
+interface CreateRelationshipResult {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+```
+
+**Description Format:**
+```
+Creates a new table-to-table relationship linking a child table to a parent table.
+This creates a reference field in the child table. Optionally creates lookup fields
+(to display parent data in child records) and/or a summary field (to aggregate child
+data in parent records). Relationships can only be created between tables in the same
+application. This operation is SAFE and does not modify existing data.
+```
+
+### Component 3: UpdateRelationshipTool
+
+**Responsibilities:**
+- Add lookup fields to existing relationship
+- Add summary field to existing relationship
+- Does NOT delete existing fields (additive only)
+
+**Interface:**
+```typescript
+interface UpdateRelationshipParams {
+  table_id: string;              // Required: Child table ID
+  relationship_id: number;       // Required: Relationship ID (foreign key field ID)
+  lookup_field_ids?: number[];   // Optional: Additional parent field IDs for lookups
+  summary_field_id?: number;     // Optional: Child field ID to summarize
+  summary_label?: string;        // Optional: Label for summary field
+  summary_accumulation_type?: string;  // Required if summary_field_id
+  summary_where?: string;        // Optional: Quickbase query filter
+}
+
+// Note: JSON Schema validation must enforce that summary_accumulation_type is required
+// when summary_field_id is provided. Use conditional validation in paramSchema.
+
+interface UpdateRelationshipResult {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+```
+
+**Description Format:**
+```
+Adds lookup fields and/or summary fields to an existing relationship. This operation
+is ADDITIVE ONLY - it will not delete existing lookup or summary fields. Use this to
+enhance relationships with additional calculated fields. To remove fields from a
+relationship, you must delete them individually using the field deletion tools.
+```
+
+### Component 4: DeleteRelationshipTool
+
+**Responsibilities:**
+- Delete entire relationship
+- Clearly warn about data loss in description
+- Return confirmation of what was deleted
+
+**Interface:**
+```typescript
+interface DeleteRelationshipParams {
+  table_id: string;        // Required: Child table ID
+  relationship_id: number; // Required: Relationship ID to delete
+}
+
+interface DeleteRelationshipResult {
+  relationshipId: number;
+  deleted: boolean;
+}
+```
+
+**Description Format (Critical for Agent Safety):**
+```
+WARNING: DESTRUCTIVE OPERATION - Permanently deletes an entire table-to-table
+relationship INCLUDING ALL LOOKUP AND SUMMARY FIELDS associated with it. All data
+in those fields will be permanently lost and CANNOT be recovered. The reference
+field in the child table will NOT be deleted (it will remain and may need to be
+manually deleted using field deletion tools if no longer needed). Before using
+this tool:
+1. Use get_relationships to see what fields will be deleted
+2. Confirm with the user that they want to proceed
+3. Consider if you only need to delete specific fields instead
+
+Only use this tool when you are certain the entire relationship should be removed.
+```
+
+### Shared Types
+
+```typescript
+interface FieldInfo {
+  id: number;
+  label: string;
+  type: string;
+}
+
+interface Relationship {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  isCrossApp: boolean;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+```
+
+## Data Flow
+
+### Get Relationships Flow
+
+```
+Agent Request
+    |
+    v
+GetRelationshipsTool.execute(params)
+    |
+    v
+BaseTool.validateParams(params)
+    |
+    v
+QuickbaseClient.request({
+  method: 'GET',
+  path: `/tables/${tableId}/relationships`,
+  params: { skip }
+})
+    |
+    v
+Transform API Response
+    |
+    v
+Return GetRelationshipsResult
+```
+
+### Create Relationship Flow
+
+```
+Agent Request
+    |
+    v
+CreateRelationshipTool.execute(params)
+    |
+    v
+BaseTool.validateParams(params)
+    |
+    v
+Build Request Body (parentTableId, lookupFieldIds, summaryFields)
+    |
+    v
+QuickbaseClient.request({
+  method: 'POST',
+  path: `/tables/${tableId}/relationships`,
+  body: requestBody
+})
+    |
+    v
+Transform API Response
+    |
+    v
+Return CreateRelationshipResult
+```
+
+### Delete Relationship Flow
+
+```
+Agent Request
+    |
+    v
+DeleteRelationshipTool.execute(params)
+    |
+    v
+BaseTool.validateParams(params)
+    |
+    v
+QuickbaseClient.request({
+  method: 'DELETE',
+  path: `/tables/${tableId}/relationships/${relationshipId}`
+})
+    |
+    v
+Return DeleteRelationshipResult (confirmation)
+```
+
+## Integration Points
+
+### Tool Registration
+
+Update `src/tools/index.ts`:
+```typescript
+import { registerRelationshipTools } from './relationships';
+
+export function initializeTools(client: QuickbaseClient, cacheService: CacheService): void {
+  // ... existing registrations ...
+
+  // Register relationship management tools
+  registerRelationshipTools(client);
+
+  // ...
+}
+
+export * from './relationships';
+```
+
+### API Endpoints
+
+All tools use the existing `QuickbaseClient.request()` method with these endpoints:
+
+| Tool | Method | Path |
+|------|--------|------|
+| get_relationships | GET | `/tables/{tableId}/relationships` |
+| create_relationship | POST | `/tables/{tableId}/relationships` |
+| update_relationship | POST | `/tables/{tableId}/relationships/{relationshipId}` |
+| delete_relationship | DELETE | `/tables/{tableId}/relationships/{relationshipId}` |
+
+### Caching Behavior
+
+- GET requests are cached by `QuickbaseClient` by default
+- Create/Update/Delete requests skip cache and may invalidate related cached data
+- Consider adding `skipCache: true` for relationship queries if stale data is problematic
+
+## Performance Considerations
+
+### Rate Limiting
+
+- Existing rate limiter (10 req/sec default) handles all requests
+- Relationship operations are typically low-volume
+- No special performance optimizations needed
+
+### Response Size
+
+- `get_relationships` may return large responses for tables with many relationships
+- Pagination (skip parameter) is available for large result sets
+- No need for custom pagination handling beyond exposing skip parameter
+
+## Maintainability
+
+### Code Organization
+
+- Each tool in its own file with params/result interfaces
+- Shared types can be extracted to a types file if needed later
+- Registration pattern keeps index.ts clean
+
+### Error Handling
+
+- Use existing `ApiResponse` pattern with success/error states
+- Throw descriptive errors that bubble up through BaseTool
+- Include table ID and relationship ID in error context
+
+### Documentation
+
+- Tool descriptions serve as primary documentation for agents
+- JSDoc comments on interfaces for developer documentation
+- README update for human users
+
+### Testing Strategy
+
+- Unit tests for each tool following existing patterns
+- Mock QuickbaseClient for isolation
+- Test success, validation errors, API errors, and edge cases
+- Specific tests for destructive operation handling