mcp-quickbase 2.1.0 → 2.2.0

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 });
+```

package/.sdd/tickets/RELS_relationship-management/planning/quality-strategy.md

@@ -0,0 +1,335 @@
+# Quality Strategy: Relationship Management
+
+## Testing Philosophy
+
+This feature follows enterprise-grade testing principles with comprehensive coverage of both happy paths and error scenarios. Given the destructive nature of the delete operation, testing must verify that tool descriptions accurately communicate risks and that error handling prevents unintended data loss.
+
+Testing priorities:
+1. **Critical paths** - All CRUD operations must work correctly
+2. **Error handling** - API errors, validation errors, and edge cases
+3. **Safety verification** - Delete tool description contains required warnings
+4. **Integration** - Tools register correctly and are callable through MCP
+
+## Coverage Requirements
+
+**Minimum Thresholds (from jest.config.js):**
+- Line coverage: 40%
+- Function coverage: 40%
+- Statement coverage: 40%
+- Branch coverage: 20%
+
+**Target Thresholds:**
+- Line coverage: 80% for new relationship tools
+- Branch coverage: 70% for new relationship tools
+
+**Note:** The minimum thresholds are enforced by jest.config.js and represent hard requirements. The target thresholds are aspirational goals for new relationship tool code quality.
+
+**Coverage Focus Areas:**
+- All tool `run()` methods
+- Parameter validation paths
+- Error handling branches
+- Response transformation logic
+
+## Test Types
+
+### Unit Tests
+
+**Scope:** Individual tool classes with mocked QuickbaseClient
+
+**Tools:** Jest with ts-jest
+
+**Coverage Target:** >= 80% for new code
+
+**What to Test:**
+
+1. **Tool Properties**
+   - Correct `name` value
+   - Description is non-empty string
+   - `paramSchema` is valid JSON Schema object
+
+2. **Happy Path Execution**
+   - Successful API responses transformed correctly
+   - All response fields mapped properly
+   - Metadata included in results
+
+3. **Parameter Validation**
+   - Required parameters validated
+   - Invalid parameter types rejected
+   - Optional parameters handled correctly
+
+4. **Error Handling**
+   - API errors (4xx, 5xx) handled gracefully
+   - Network errors caught and reported
+   - Validation errors include helpful messages
+
+5. **Edge Cases**
+   - Empty relationship lists
+   - Relationships with no lookup/summary fields
+   - Large relationship counts (pagination)
+
+### Integration Tests
+
+**Scope:** Tool registration and end-to-end execution flow
+
+**Approach:** Test that tools are registered and callable through the registry
+
+**What to Test:**
+- All four tools appear in `toolRegistry.getAllTools()`
+- Tools can be retrieved by name via `toolRegistry.getTool()`
+- Execute returns proper `ApiResponse` structure
+
+### End-to-End Tests
+
+**Scope:** Not required for initial release
+
+**Note:** E2E tests against real Quickbase API would require test credentials and are deferred to future work.
+
+## Critical Paths
+
+The following paths MUST have comprehensive test coverage:
+
+### 1. Get Relationships
+
+**Happy Path:**
+- Returns array of relationships with complete structure
+- Pagination works (skip parameter honored)
+- Empty array returned for tables with no relationships
+
+**Error Cases:**
+- Table not found (404)
+- Unauthorized (401)
+- Forbidden (403)
+- Network error
+
+**Edge Cases:**
+- Table with many relationships (pagination needed)
+- Cross-app relationships have limited details
+
+### 2. Create Relationship
+
+**Happy Path:**
+- Basic relationship creation (parent + child only)
+- With lookup field IDs
+- With summary field (all accumulation types)
+- With both lookup and summary fields
+
+**Error Cases:**
+- Parent table not found
+- Invalid field IDs for lookups
+- Missing accumulation type when summary_field_id provided (must be validated via JSON Schema)
+- Tables in different apps
+
+**Edge Cases:**
+- Creating relationship that already exists
+- Summary field with WHERE filter
+
+### 3. Update Relationship
+
+**Happy Path:**
+- Add lookup fields to existing relationship
+- Add summary field to existing relationship
+- Add both lookup and summary fields
+
+**Error Cases:**
+- Relationship not found
+- Invalid lookup field IDs
+- Missing accumulation type when summary_field_id provided (must be validated via JSON Schema)
+
+**Edge Cases:**
+- Adding fields that already exist (additive behavior)
+- Empty update (no fields to add)
+
+### 4. Delete Relationship (CRITICAL - Extra Coverage Required)
+
+**Happy Path:**
+- Successful deletion returns relationship ID
+- All lookup/summary fields deleted
+
+**Error Cases:**
+- Relationship not found (404)
+- Unauthorized (401)
+- Forbidden (403)
+
+**Safety Verification:**
+- Tool description contains "WARNING"
+- Tool description contains "DESTRUCTIVE"
+- Tool description mentions lookup fields deletion
+- Tool description mentions summary fields deletion
+- Tool description mentions data loss is permanent
+- Tool description recommends `get_relationships` first
+- Tool description recommends user confirmation
+
+## Negative Testing Requirements
+
+### Invalid Inputs
+
+| Test Case | Input | Expected |
+|-----------|-------|----------|
+| Empty table_id | `""` | Validation error |
+| Missing table_id | `undefined` | Validation error |
+| Invalid table_id type | `123` (number) | Validation error |
+| Empty relationship_id (for update/delete) | `undefined` | Validation error |
+| Invalid accumulation_type | `"INVALID"` | API error or validation error |
+| Non-numeric field IDs | `["abc"]` | Validation error |
+
+### API Error Handling
+
+| Status Code | Scenario | Expected Behavior |
+|-------------|----------|-------------------|
+| 400 | Bad request | Return error with message |
+| 401 | Invalid token | Return auth error |
+| 403 | No permission | Return forbidden error |
+| 404 | Not found | Return not found error |
+| 429 | Rate limited | Retry (handled by client) |
+| 500 | Server error | Return server error |
+
+### Authorization Failures
+
+- Test with invalid/expired token (mocked)
+- Test access to table without permissions (mocked)
+
+### Resource Not Found
+
+- Non-existent table ID
+- Non-existent relationship ID
+- Non-existent parent table ID
+
+## Test Data Strategy
+
+### Mocking Approach
+
+All tests use mocked `QuickbaseClient`:
+
+```typescript
+jest.mock('../../client/quickbase');
+
+const mockClient = new QuickbaseClient(config) as jest.Mocked<QuickbaseClient>;
+mockClient.request = jest.fn().mockResolvedValue(mockResponse);
+```
+
+### Mock Response Templates
+
+```typescript
+// Relationship structure
+const mockRelationship = {
+  id: 123,
+  parentTableId: 'parent-table-id',
+  childTableId: 'child-table-id',
+  foreignKeyField: {
+    id: 123,
+    label: 'Related Parent',
+    type: 'numeric'
+  },
+  isCrossApp: false,
+  lookupFields: [
+    { id: 456, label: 'Parent Name', type: 'text' }
+  ],
+  summaryFields: [
+    { id: 789, label: 'Child Count', type: 'numeric' }
+  ]
+};
+
+// Get relationships response
+const mockGetResponse = {
+  success: true,
+  data: {
+    relationships: [mockRelationship],
+    metadata: {
+      totalRelationships: 1,
+      numRelationships: 1,
+      skip: 0
+    }
+  }
+};
+
+// Create/Update response
+const mockCreateResponse = {
+  success: true,
+  data: mockRelationship
+};
+
+// Delete response
+const mockDeleteResponse = {
+  success: true,
+  data: {
+    relationshipId: 123
+  }
+};
+
+// Error response
+const mockErrorResponse = {
+  success: false,
+  error: {
+    message: 'Table not found',
+    code: 404,
+    type: 'NotFoundError'
+  }
+};
+```
+
+## Quality Gates
+
+Before verification, all items must be checked:
+
+### Code Quality
+
+- [ ] All unit tests pass (`npm test`)
+- [ ] Coverage thresholds met (40% lines/functions/statements, 20% branches per jest.config.js)
+- [ ] No linting errors (`npm run lint`)
+- [ ] No TypeScript errors (`npm run build`)
+
+### Functional Completeness
+
+- [ ] All four tools implemented
+- [ ] All tools registered in toolRegistry
+- [ ] Parameter schemas match implementation
+- [ ] Response types match API responses
+
+### Critical Path Coverage
+
+- [ ] Get relationships: happy path + errors
+- [ ] Create relationship: all parameter combinations
+- [ ] Update relationship: additive behavior verified
+- [ ] Delete relationship: all error cases
+
+### Safety Verification
+
+- [ ] Delete tool description starts with WARNING
+- [ ] Delete tool description mentions DESTRUCTIVE
+- [ ] Delete tool description lists what is deleted
+- [ ] Delete tool description states data is permanent
+- [ ] Delete tool description recommends confirmation
+
+### Edge Cases
+
+- [ ] Empty results handled
+- [ ] Pagination works
+- [ ] Missing optional fields handled
+- [ ] API error messages preserved
+
+## Test File Organization
+
+```
+src/__tests__/tools/
+  relationships.test.ts           # All relationship tool tests
+    - describe('GetRelationshipsTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('execute - edge cases')
+    - describe('CreateRelationshipTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('validation')
+    - describe('UpdateRelationshipTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('additive behavior')
+    - describe('DeleteRelationshipTool')
+      - describe('tool properties')
+      - describe('tool description safety')  # CRITICAL
+      - describe('execute - success')
+      - describe('execute - errors')
+```

package/.sdd/tickets/RELS_relationship-management/planning/review-updates.md

@@ -0,0 +1,95 @@
+# Ticket Review Updates
+
+**Original Review Date:** 2025-12-28
+**Updates Completed:** 2025-12-28
+**Update Status:** Complete
+
+## Summary
+
+| Category | Issues Found | Issues Fixed |
+|----------|--------------|--------------|
+| Critical Issues | 0 | 0 |
+| Boundary Violations | 0 | 0 |
+| High-Risk Areas | 3 | 3 |
+| Gaps & Ambiguities | 5 | 3 |
+| Ticket Issues | 0 | 0 |
+
+## High-Risk Areas Addressed
+
+### Risk 1: API Response Structure Assumption (Low-Medium Risk)
+**Original Problem:** TypeScript interfaces based on documentation rather than live API testing. If actual API responses differ, tools may fail or return incorrect data.
+
+**Changes Made:**
+- **plan.md Phase 1**: Added explicit acceptance criterion requiring API response structure validation against TypeScript interfaces before proceeding to Phase 2
+- **plan.md Phase 1 deliverables**: Added task to validate actual API responses match documented interfaces
+
+**Result:** Phase 1 now includes explicit validation step to catch any documentation discrepancies early.
+
+### Risk 2: Test Coverage Threshold Discrepancy (Low Risk)
+**Original Problem:** Discrepancy between documented thresholds:
+- jest.config.js: 40% lines/functions/statements, 20% branches
+- quality-strategy.md: 35% minimum
+- plan.md: >= 35%
+
+**Changes Made:**
+- **quality-strategy.md**: Updated minimum thresholds to match jest.config.js exactly (40% lines/functions/statements, 20% branches)
+- **quality-strategy.md**: Clarified that 40% is the hard requirement from jest.config.js, with 80% as aspirational target for new relationship tools
+- **plan.md Phase 3**: Updated acceptance criteria from >= 35% to >= 40% for consistency
+- **plan.md Phase 4**: Updated acceptance criteria to reference jest.config.js thresholds (40% lines/functions/statements, 20% branches)
+
+**Result:** All documents now consistently reference jest.config.js as the authoritative source for coverage thresholds.
+
+### Risk 3: Conditional JSON Schema Validation for Summary Fields
+**Original Problem:** `summary_accumulation_type` documented as "Required if summary_field_id" but JSON Schema validation rules not explicitly defined.
+
+**Changes Made:**
+- **architecture.md CreateRelationshipParams**: Added explicit note about conditional validation requirement
+- **architecture.md UpdateRelationshipParams**: Added explicit note about conditional validation requirement
+- **plan.md Phase 2**: Added acceptance criterion to validate that summary field parameters enforce accumulation type requirement
+- **quality-strategy.md**: Added test case for missing accumulation type when summary_field_id is provided
+
+**Result:** Implementation requirements now explicitly state that JSON Schema must enforce conditional validation.
+
+## Gaps Filled
+
+### Gap 1: Cross-App Relationship Handling
+**Status:** Acknowledged as implementation-phase concern
+**Action:** No planning document changes needed; implementation will handle error messages as recommended in review
+
+### Gap 2: Relationship Field Type Validation
+**Status:** Acknowledged as implementation-phase concern
+**Action:** quality-strategy.md already includes tests for invalid field IDs
+
+### Gap 3: Summary Field Accumulation Type Validation
+**Status:** Fixed (see Risk 3 above)
+
+### Ambiguity 1: Reference Field Deletion Behavior
+**Changes Made:**
+- **architecture.md DeleteRelationshipTool description**: Enhanced to explicitly note that reference field remains and may need manual deletion
+
+**Result:** Tool description now clarifies cleanup steps after relationship deletion.
+
+### Ambiguity 2: Pagination Implementation
+**Changes Made:**
+- **plan.md Phase 1**: Added acceptance criterion to verify actual pagination behavior during implementation
+
+**Result:** Phase 1 will validate whether API supports limit parameter and adjust if needed.
+
+## Document Change Summary
+
+| Document | Lines Modified | Key Changes |
+|----------|----------------|-------------|
+| quality-strategy.md | ~8 | Updated coverage thresholds to match jest.config.js (40/40/40/20); added conditional validation test case |
+| architecture.md | ~6 | Added conditional validation notes to CreateRelationshipParams and UpdateRelationshipParams; enhanced DeleteRelationshipTool description |
+| plan.md | ~8 | Added API response validation to Phase 1; added conditional validation to Phase 2; updated Phase 3 and Phase 4 coverage thresholds; added pagination verification to Phase 1 |
+| analysis.md | 0 | No changes needed |
+| security-review.md | 0 | No changes needed |
+
+## Verification
+
+**Re-review Recommended:** Yes
+**Expected Result:** All low and low-medium risks should now be resolved
+
+## Next Steps
+1. Run `/sdd:review RELS_relationship-management` to verify all issues addressed
+2. If passes, proceed to `/sdd:create-tasks RELS_relationship-management`