mcp-quickbase 2.0.5 → 2.2.0

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

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

@@ -0,0 +1,177 @@
+# Plan: Relationship Management
+
+## Overview
+
+This document outlines the phased execution plan for implementing relationship management tools in the MCP Quickbase server. The plan follows a safety-first approach: read-only operations first, then write operations with explicit safety measures for destructive actions.
+
+## Phases
+
+### Phase 1: Foundation - Read Operations and Domain Setup
+
+**Objective:** Establish the relationships domain and implement the read-only `get_relationships` tool, enabling agents to explore table structures safely.
+
+**Deliverables:**
+- `src/tools/relationships/` directory structure
+- `src/tools/relationships/index.ts` with registration function
+- `src/tools/relationships/get_relationships.ts` tool implementation
+- `src/__tests__/tools/relationships.test.ts` with tests for get_relationships
+- Update to `src/tools/index.ts` to register relationship tools
+
+**Agent Assignments:**
+- implement-feature: Create directory structure and index.ts registration pattern
+- implement-feature: Implement GetRelationshipsTool with full type definitions
+- implement-feature: Update main tools/index.ts to include relationships
+
+**Acceptance Criteria:**
+- [ ] `get_relationships` tool is registered and callable
+- [ ] Returns correct relationship structure with foreignKeyField, lookupFields, summaryFields
+- [ ] **API response structure validated against TypeScript interfaces** - Confirm actual Quickbase API responses match documented structure before proceeding to Phase 2
+- [ ] Pagination (skip parameter) works correctly - Verify if API supports limit parameter and adjust if needed
+- [ ] Tool description clearly explains what information is returned
+- [ ] Unit tests cover success case, empty results, pagination, and API errors
+
+### Phase 2: Write Operations - Create and Update
+
+**Objective:** Implement non-destructive write operations that allow creating and enhancing relationships.
+
+**Deliverables:**
+- `src/tools/relationships/create_relationship.ts` tool implementation
+- `src/tools/relationships/update_relationship.ts` tool implementation
+- Extended tests in `src/__tests__/tools/relationships.test.ts`
+
+**Agent Assignments:**
+- implement-feature: Implement CreateRelationshipTool with lookup/summary field support
+- implement-feature: Implement UpdateRelationshipTool (additive operations only)
+
+**Acceptance Criteria:**
+- [ ] `create_relationship` tool creates relationships with optional lookup/summary fields
+- [ ] Tool description emphasizes this is a SAFE operation
+- [ ] **JSON Schema conditional validation enforced** - summary_accumulation_type is required when summary_field_id is provided
+- [ ] `update_relationship` tool adds fields to existing relationships
+- [ ] Update tool description clearly states "ADDITIVE ONLY"
+- [ ] Unit tests cover: basic creation, creation with lookups, creation with summary, validation errors
+- [ ] Unit tests cover: update adding lookups, update adding summary, relationship not found
+- [ ] Unit tests verify conditional validation: missing accumulation_type with summary_field_id fails validation
+
+### Phase 3: Destructive Operations with Safety Measures
+
+**Objective:** Implement the delete operation with comprehensive safety warnings and agent guidance.
+
+**Deliverables:**
+- `src/tools/relationships/delete_relationship.ts` tool implementation
+- Complete test coverage for delete scenarios
+- Final documentation updates
+
+**Agent Assignments:**
+- implement-feature: Implement DeleteRelationshipTool with safety-focused description
+- implement-feature: Ensure all tests pass and coverage threshold met
+- implement-feature: Update exports and verify tool registration
+
+**Acceptance Criteria:**
+- [ ] `delete_relationship` tool description starts with "WARNING: DESTRUCTIVE OPERATION"
+- [ ] Description explicitly lists what will be deleted (lookup fields, summary fields)
+- [ ] Description explicitly states data is permanently lost
+- [ ] Description recommends using `get_relationships` first to review impact
+- [ ] Description recommends confirming with user before proceeding
+- [ ] Unit tests cover: successful deletion, relationship not found, API errors
+- [ ] All four tools are registered and functional
+- [ ] Test coverage meets or exceeds 40% threshold (lines/functions/statements) and 20% branches per jest.config.js
+
+### Phase 4: Integration and Verification
+
+**Objective:** Verify complete integration, ensure all tests pass, and validate agent safety measures.
+
+**Deliverables:**
+- Passing test suite with coverage >= 40% (lines/functions/statements) and >= 20% branches per jest.config.js
+- All linting checks pass
+- Verified tool descriptions for agent safety
+
+**Agent Assignments:**
+- verify-task: Run full test suite and validate coverage
+- verify-task: Verify all tools are properly registered
+- verify-task: Review tool descriptions for clarity and safety warnings
+- commit-task: Commit all changes with descriptive message
+
+**Acceptance Criteria:**
+- [ ] `npm test` passes all tests
+- [ ] `npm run lint` shows no errors
+- [ ] All four relationship tools appear in tool registry
+- [ ] Delete tool description contains required safety warnings
+- [ ] Integration test validates end-to-end flow (if applicable)
+
+## Dependencies
+
+### Cross-Phase Dependencies
+
+```
+Phase 1 (Foundation)
+    |
+    +---> Phase 2 (Create/Update) [depends on domain setup]
+    |
+    +---> Phase 3 (Delete) [depends on domain setup, benefits from Phase 2 patterns]
+              |
+              +---> Phase 4 (Verification) [depends on all implementations]
+```
+
+### External Dependencies
+
+| Dependency | Type | Status |
+|------------|------|--------|
+| `src/tools/base.ts` (BaseTool) | Existing | Available |
+| `src/client/quickbase.ts` (QuickbaseClient) | Existing | Available |
+| `src/tools/registry.ts` (toolRegistry) | Existing | Available |
+| Quickbase Relationships API | External | Available |
+
+## Risk Mitigation
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| API schema differs from documentation | Medium | Medium | Start with get_relationships to validate response structure; adjust types as needed |
+| Agent uses delete without understanding consequences | Medium | High | Comprehensive warning in tool description; recommend user confirmation |
+| Test coverage falls below threshold | Low | Medium | Write tests concurrently with implementation; prioritize critical paths |
+| Validation complexity for summary fields | Medium | Low | Clear error messages when accumulation_type missing; follow existing field patterns |
+
+## Success Metrics
+
+- [ ] All four relationship tools implemented and registered
+- [ ] `get_relationships` returns accurate relationship data
+- [ ] `create_relationship` successfully creates relationships with lookup/summary fields
+- [ ] `update_relationship` adds fields without deleting existing ones
+- [ ] `delete_relationship` has prominent destructive operation warnings
+- [ ] Test coverage >= 40% lines/functions/statements, >= 20% branches (per jest.config.js)
+- [ ] No lint errors
+- [ ] Tool descriptions help agents understand when to use each tool
+- [ ] Destructive operations clearly marked and explain consequences
+
+## Implementation Notes
+
+### Tool Naming Convention
+
+Follow existing snake_case pattern:
+- `get_relationships` (not `getRelationships`)
+- `create_relationship` (not `createRelationship`)
+- `update_relationship` (not `updateRelationship`)
+- `delete_relationship` (not `deleteRelationship`)
+
+### Parameter Naming Convention
+
+Follow existing patterns:
+- `table_id` (not `tableId`)
+- `relationship_id` (not `relationshipId`)
+- `parent_table_id` (not `parentTableId`)
+- `lookup_field_ids` (not `lookupFieldIds`)
+
+### Error Message Format
+
+Include context for debugging:
+```typescript
+throw new Error(`Failed to get relationships for table ${tableId}: ${response.error?.message || 'Unknown error'}`);
+```
+
+### Logging Pattern
+
+Use existing logger:
+```typescript
+const logger = createLogger('GetRelationshipsTool');
+logger.info('Getting relationships for table', { tableId });
+```