mcp-quickbase 2.1.0 → 2.2.0

package/.sdd/tickets/RELS_relationship-management/tasks/RELS.1001_domain-setup.md

@@ -0,0 +1,96 @@
+# Task: [RELS.1001]: Domain Setup and Directory Structure
+
+## Status
+- [x] **Task completed** - acceptance criteria met
+- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
+- [x] **Verified** - by the verify-task agent
+
+**Note on "Tests pass"**:
+- If tests were created/modified, you MUST run them and show output
+- "Tests pass" means tests were EXECUTED and all passed
+- "Tests pass - N/A" is only valid for documentation-only tickets
+- Test file existence alone does NOT satisfy this requirement
+
+## Agents
+- implement-feature
+- unit-test-runner
+- verify-task
+- commit-task
+
+## Summary
+Create the relationships domain directory structure and registration pattern following the existing codebase patterns for domains like tables, fields, and records.
+
+## Background
+This is the foundation task for the relationship management feature. The MCP Quickbase server organizes tools into domain-specific directories (apps, tables, fields, records, etc.). This task establishes the relationships domain structure and registration pattern that all subsequent relationship tools will use.
+
+This implements Phase 1 foundation work from plan.md.
+
+## Acceptance Criteria
+- [x] Directory `src/tools/relationships/` exists
+- [x] File `src/tools/relationships/index.ts` exists with `registerRelationshipTools()` function
+- [x] Registration function accepts `QuickbaseClient` parameter
+- [x] Registration pattern follows existing domain patterns (see `src/tools/fields/index.ts` or `src/tools/tables/index.ts`)
+- [x] Exports are structured for future tool additions
+- [x] File structure validated by TypeScript compilation (`npm run build` succeeds)
+
+## Technical Requirements
+- Follow existing domain registration pattern from other tool directories
+- Use TypeScript with strict type checking
+- Export a `registerRelationshipTools(client: QuickbaseClient)` function
+- Prepare for 4 tools: get_relationships, create_relationship, update_relationship, delete_relationship
+- No actual tool implementations yet - this is structure only
+
+## Implementation Notes
+Study existing patterns:
+- `src/tools/fields/index.ts` - Shows registration pattern with toolRegistry
+- `src/tools/tables/index.ts` - Shows how to organize domain exports
+
+Pattern to follow:
+```typescript
+import { QuickbaseClient } from '../../client/quickbase';
+import { toolRegistry } from '../registry';
+
+export function registerRelationshipTools(client: QuickbaseClient): void {
+  // Tools will be registered here in subsequent tasks
+}
+
+// Future exports
+// export { GetRelationshipsTool } from './get_relationships';
+// export { CreateRelationshipTool } from './create_relationship';
+// export { UpdateRelationshipTool } from './update_relationship';
+// export { DeleteRelationshipTool } from './delete_relationship';
+```
+
+## Dependencies
+- None - this is the first task in the sequence
+- Existing infrastructure: BaseTool, QuickbaseClient, toolRegistry
+
+## Risk Assessment
+- **Risk**: Directory structure doesn't match existing patterns
+  - **Mitigation**: Study at least 2 existing domain directories before implementing
+- **Risk**: Registration function signature incompatible with main tools/index.ts
+  - **Mitigation**: Review how other domains are registered in src/tools/index.ts
+
+## Files/Packages Affected
+- src/tools/relationships/ (new directory)
+- src/tools/relationships/index.ts (new file)
+
+## Deliverables Produced
+
+Documents created in `deliverables/` directory:
+
+- None
+
+## Verification Notes
+Verify-task agent should confirm:
+- Directory structure matches existing domain patterns
+- index.ts compiles without errors
+- Registration function signature is correct
+- No actual tools registered yet (that happens in subsequent tasks)
+- Code follows existing naming conventions (snake_case for tools, camelCase for functions)
+
+## Verification Audit
+<!-- Audit log maintained by verify-task agent for enterprise compliance -->
+| Date | Agent | Decision | Notes |
+|------|-------|----------|-------|
+| 2025-12-28 | verify-task | PASS | All 6 acceptance criteria met, TypeScript compilation successful, tests passing (86/86), no .sdd references in production code |

package/.sdd/tickets/RELS_relationship-management/tasks/RELS.1002_get-relationships-tool.md

@@ -0,0 +1,142 @@
+# Task: [RELS.1002]: Implement GetRelationshipsTool
+
+## Status
+- [x] **Task completed** - acceptance criteria met
+- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
+- [x] **Verified** - by the verify-task agent
+
+**Note on "Tests pass"**:
+- If tests were created/modified, you MUST run them and show output
+- "Tests pass" means tests were EXECUTED and all passed
+- "Tests pass - N/A" is only valid for documentation-only tickets
+- Test file existence alone does NOT satisfy this requirement
+
+## Agents
+- implement-feature
+- unit-test-runner
+- verify-task
+- commit-task
+
+## Summary
+Implement the `get_relationships` tool to query all table-to-table relationships for a given table, including support for pagination and complete relationship metadata.
+
+## Background
+This is the first read-only relationship tool, enabling agents to safely explore table structures and understand data connections. It's critical to validate the actual Quickbase API response structure before proceeding to write operations in Phase 2.
+
+This implements Phase 1 from plan.md: Foundation - Read Operations.
+
+## Acceptance Criteria
+- [x] Tool name is `get_relationships` (snake_case)
+- [x] Tool extends BaseTool with proper TypeScript types
+- [x] Returns relationship structure with foreignKeyField, lookupFields, summaryFields
+- [x] Pagination support via skip parameter works correctly
+- [x] API response structure validated against TypeScript interfaces
+- [x] Tool description clearly explains what information is returned
+- [x] Tool registered in relationships/index.ts
+- [x] Unit tests cover: success case, empty results, pagination, API errors
+- [x] All tests pass with `npm test`
+
+## Technical Requirements
+- Endpoint: GET `/tables/{tableId}/relationships`
+- Query parameters: skip (optional, for pagination)
+- Response includes both parent and child relationships
+- Return metadata: totalRelationships, numRelationships, skip
+- Use QuickbaseClient.request() method for API calls
+- Follow BaseTool pattern from existing tools
+- TypeScript interfaces for GetRelationshipsParams and GetRelationshipsResult
+
+## Implementation Notes
+From architecture.md:
+
+```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;
+  };
+}
+
+interface Relationship {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  isCrossApp: boolean;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+
+interface FieldInfo {
+  id: number;
+  label: string;
+  type: string;
+}
+```
+
+Tool description format (from architecture.md):
+```
+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.
+```
+
+Use logging pattern:
+```typescript
+const logger = createLogger('GetRelationshipsTool');
+logger.info('Getting relationships for table', { tableId });
+```
+
+## Dependencies
+- RELS.1001 - Domain setup must be complete
+- Existing: BaseTool, QuickbaseClient, toolRegistry
+
+## Risk Assessment
+- **Risk**: API response structure differs from documentation
+  - **Mitigation**: Add logging to inspect actual responses; adjust interfaces as needed
+- **Risk**: Pagination parameter not supported by API
+  - **Mitigation**: Test with skip parameter; verify behavior matches expectations
+- **Risk**: Cross-app relationships have different structure
+  - **Mitigation**: Include isCrossApp flag and handle limited details appropriately
+
+## Files/Packages Affected
+- src/tools/relationships/get_relationships.ts (new file)
+- src/tools/relationships/index.ts (update exports and registration)
+- src/__tests__/tools/relationships.test.ts (new file)
+
+## Deliverables Produced
+
+Documents created in `deliverables/` directory:
+
+- None
+
+## Verification Notes
+Verify-task agent should confirm:
+- Tool name follows snake_case convention
+- TypeScript interfaces match API response structure
+- API response structure is validated before Phase 2 proceeds (critical!)
+- Pagination works as expected
+- Error messages include table ID context for debugging
+- Tests cover all critical paths from quality-strategy.md:
+  - Returns array of relationships with complete structure
+  - Pagination works (skip parameter honored)
+  - Empty array returned for tables with no relationships
+  - Table not found (404)
+  - Unauthorized (401)
+  - Forbidden (403)
+  - Network error
+  - Table with many relationships
+  - Cross-app relationships handled
+
+## Verification Audit
+<!-- Audit log maintained by verify-task agent for enterprise compliance -->
+| Date | Agent | Decision | Notes |
+|------|-------|----------|-------|
+| 2025-12-28 | verify-task | PASS | All 9 acceptance criteria met, 100 tests passing, 100% coverage on get_relationships.ts |

package/.sdd/tickets/RELS_relationship-management/tasks/RELS.1003_register-phase1-tools.md

@@ -0,0 +1,105 @@
+# Task: [RELS.1003]: Register Relationship Tools in Main Index
+
+## Status
+- [x] **Task completed** - acceptance criteria met
+- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
+- [x] **Verified** - by the verify-task agent
+
+**Note on "Tests pass"**:
+- If tests were created/modified, you MUST run them and show output
+- "Tests pass" means tests were EXECUTED and all passed
+- "Tests pass - N/A" is only valid for documentation-only tickets
+- Test file existence alone does NOT satisfy this requirement
+
+## Agents
+- implement-feature
+- unit-test-runner
+- verify-task
+- commit-task
+
+## Summary
+Update the main tools index to register relationship tools, making them accessible through the MCP server.
+
+## Background
+The relationship tools are implemented but need to be registered in the main tools/index.ts file so they appear in the tool registry and can be called by agents through the MCP interface.
+
+This completes Phase 1 integration from plan.md.
+
+## Acceptance Criteria
+- [x] `src/tools/index.ts` imports `registerRelationshipTools` from relationships domain
+- [x] Registration function called in `initializeTools()`
+- [x] Relationship tools exported from main index for external use
+- [x] TypeScript compilation succeeds (`npm run build`)
+- [x] Integration test confirms tools appear in toolRegistry
+- [x] `get_relationships` tool is callable through MCP
+
+## Technical Requirements
+- Import registration function from relationships domain
+- Call registration in proper sequence with other domains
+- Export relationship tools for external use
+- Follow existing pattern from other domain registrations
+
+## Implementation Notes
+From architecture.md integration points:
+
+```typescript
+import { registerRelationshipTools } from './relationships';
+
+export function initializeTools(client: QuickbaseClient, cacheService: CacheService): void {
+  // ... existing registrations ...
+
+  // Register relationship management tools
+  registerRelationshipTools(client);
+
+  // ...
+}
+
+export * from './relationships';
+```
+
+Study existing registrations for:
+- Import statement placement
+- Registration function call order
+- Export pattern for domain tools
+
+## Dependencies
+- RELS.1001 - Domain setup complete
+- RELS.1002 - GetRelationshipsTool implemented
+- Existing: src/tools/index.ts, initializeTools function
+
+## Risk Assessment
+- **Risk**: Registration breaks existing tool initialization
+  - **Mitigation**: Add registration after existing ones; run full test suite
+- **Risk**: Circular dependency issues
+  - **Mitigation**: Follow same import pattern as other domains
+
+## Files/Packages Affected
+- src/tools/index.ts (update imports, registration, exports)
+- src/__tests__/tools/relationships.test.ts (add integration test)
+
+## Deliverables Produced
+
+Documents created in `deliverables/` directory:
+
+- None
+
+## Verification Notes
+Verify-task agent should confirm:
+- Tools registration doesn't break existing tests
+- Full test suite passes (`npm test`)
+- Build completes without errors (`npm run build`)
+- Linting passes (`npm run lint`)
+- Integration test confirms get_relationships appears in toolRegistry.getAllTools()
+- Tool can be retrieved via toolRegistry.getTool('get_relationships')
+- No TypeScript compilation errors
+
+Integration test pattern from quality-strategy.md:
+- Tool appears in toolRegistry.getAllTools()
+- Tool can be retrieved by name via toolRegistry.getTool()
+- Execute returns proper ApiResponse structure
+
+## Verification Audit
+<!-- Audit log maintained by verify-task agent for enterprise compliance -->
+| Date | Agent | Decision | Notes |
+|------|-------|----------|-------|
+| 2025-12-28 | verify-task | PASS | All 6 acceptance criteria met, 100 tests passing, build successful |

package/.sdd/tickets/RELS_relationship-management/tasks/RELS.2001_create-relationship-tool.md

@@ -0,0 +1,151 @@
+# Task: [RELS.2001]: Implement CreateRelationshipTool
+
+## Status
+- [x] **Task completed** - acceptance criteria met
+- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
+- [x] **Verified** - by the verify-task agent
+
+**Note on "Tests pass"**:
+- If tests were created/modified, you MUST run them and show output
+- "Tests pass" means tests were EXECUTED and all passed
+- "Tests pass - N/A" is only valid for documentation-only tickets
+- Test file existence alone does NOT satisfy this requirement
+
+## Agents
+- implement-feature
+- unit-test-runner
+- verify-task
+- commit-task
+
+## Summary
+Implement the `create_relationship` tool to create new table-to-table relationships with optional lookup and summary fields.
+
+## Background
+This is the first write operation for relationships. It allows creating new relationships between tables, optionally including lookup fields (to display parent data in child records) and summary fields (to aggregate child data in parent records). The tool must emphasize this is a SAFE operation that doesn't modify existing data.
+
+This implements Phase 2 from plan.md: Write Operations - Create and Update.
+
+## Acceptance Criteria
+- [x] Tool name is `create_relationship` (snake_case)
+- [x] Tool extends BaseTool with proper TypeScript types
+- [x] Creates basic relationships (parent + child table only)
+- [x] Supports optional lookup_field_ids parameter
+- [x] Supports optional summary field parameters
+- [x] JSON Schema conditional validation: summary_accumulation_type required when summary_field_id provided
+- [x] Tool description emphasizes this is a SAFE operation
+- [x] Tool registered in relationships/index.ts
+- [x] Unit tests cover all parameter combinations and validation scenarios
+- [x] All tests pass with `npm test`
+
+## Technical Requirements
+- Endpoint: POST `/tables/{tableId}/relationships`
+- Parameters follow flat structure from architecture.md
+- Support all summary accumulation types: SUM, COUNT, AVG, MAX, MIN
+- Support optional summary_where filter
+- Build request body from flat parameters
+- Return complete relationship structure including created fields
+- Conditional validation: summary_accumulation_type is required if summary_field_id is provided
+
+## Implementation Notes
+From architecture.md:
+
+```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
+}
+
+interface CreateRelationshipResult {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+```
+
+JSON Schema must use conditional validation:
+```typescript
+paramSchema = {
+  type: 'object',
+  properties: { /* ... */ },
+  required: ['table_id', 'parent_table_id'],
+  // Add conditional validation
+  if: {
+    properties: { summary_field_id: { type: 'number' } },
+    required: ['summary_field_id']
+  },
+  then: {
+    required: ['summary_accumulation_type']
+  }
+};
+```
+
+Tool description (from architecture.md):
+```
+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.
+```
+
+## Dependencies
+- RELS.1001 - Domain setup complete
+- RELS.1002 - GetRelationshipsTool provides validation pattern
+- RELS.1003 - Registration infrastructure ready
+
+## Risk Assessment
+- **Risk**: Validation complexity for conditional summary parameters
+  - **Mitigation**: Use JSON Schema conditional validation; clear error messages
+- **Risk**: Creating relationship that already exists
+  - **Mitigation**: Handle API error gracefully; include helpful error message
+- **Risk**: Tables in different applications
+  - **Mitigation**: API will reject; surface error message clearly
+
+## Files/Packages Affected
+- src/tools/relationships/create_relationship.ts (new file)
+- src/tools/relationships/index.ts (update exports and registration)
+- src/__tests__/tools/relationships.test.ts (extend tests)
+
+## Deliverables Produced
+
+Documents created in `deliverables/` directory:
+
+- None
+
+## Verification Notes
+Verify-task agent should confirm tests cover all critical paths from quality-strategy.md:
+
+Happy Path:
+- Basic relationship creation (parent + child only)
+- With lookup field IDs
+- With summary field (all accumulation types: SUM, COUNT, AVG, MAX, MIN)
+- 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 (validated by JSON Schema)
+- Tables in different apps
+
+Edge Cases:
+- Creating relationship that already exists
+- Summary field with WHERE filter
+
+Verify conditional validation works:
+- Providing summary_field_id without summary_accumulation_type MUST fail validation
+- Error message clearly explains missing accumulation_type
+
+## Verification Audit
+<!-- Audit log maintained by verify-task agent for enterprise compliance -->
+| Date | Agent | Decision | Notes |
+|------|-------|----------|-------|
+| 2025-12-28 | verify-task | PASS | All 10 acceptance criteria met, 123 tests passing, 100% line/branch/statement coverage on create_relationship.ts |

package/.sdd/tickets/RELS_relationship-management/tasks/RELS.2002_update-relationship-tool.md

@@ -0,0 +1,145 @@
+# Task: [RELS.2002]: Implement UpdateRelationshipTool
+
+## Status
+- [x] **Task completed** - acceptance criteria met
+- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
+- [x] **Verified** - by the verify-task agent
+
+**Note on "Tests pass"**:
+- If tests were created/modified, you MUST run them and show output
+- "Tests pass" means tests were EXECUTED and all passed
+- "Tests pass - N/A" is only valid for documentation-only tickets
+- Test file existence alone does NOT satisfy this requirement
+
+## Agents
+- implement-feature
+- unit-test-runner
+- verify-task
+- commit-task
+
+## Summary
+Implement the `update_relationship` tool to add lookup and summary fields to existing relationships. This tool is ADDITIVE ONLY - it will not delete existing fields.
+
+## Background
+This tool enhances existing relationships by adding new lookup or summary fields. It's critical that agents understand this is additive only - fields can only be removed by using separate field deletion tools. The tool description must clearly state "ADDITIVE ONLY" to prevent confusion.
+
+This completes Phase 2 from plan.md: Write Operations - Create and Update.
+
+## Acceptance Criteria
+- [x] Tool name is `update_relationship` (snake_case)
+- [x] Tool extends BaseTool with proper TypeScript types
+- [x] Adds lookup fields to existing relationships
+- [x] Adds summary fields to existing relationships
+- [x] JSON Schema conditional validation: summary_accumulation_type required when summary_field_id provided
+- [x] Tool description clearly states "ADDITIVE ONLY"
+- [x] Tool description explains how to remove fields (use field deletion tools)
+- [x] Tool registered in relationships/index.ts
+- [x] Unit tests cover additive behavior and all error scenarios
+- [x] All tests pass with `npm test`
+
+## Technical Requirements
+- Endpoint: POST `/tables/{tableId}/relationships/{relationshipId}`
+- Parameters similar to create_relationship but require relationship_id
+- Support adding lookup_field_ids
+- Support adding summary field with accumulation type
+- Conditional validation: summary_accumulation_type required if summary_field_id provided
+- Return updated relationship structure
+- Does NOT delete existing fields (API behavior, verify in tests)
+
+## Implementation Notes
+From architecture.md:
+
+```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
+}
+
+interface UpdateRelationshipResult {
+  id: number;
+  parentTableId: string;
+  childTableId: string;
+  foreignKeyField: FieldInfo;
+  lookupFields: FieldInfo[];
+  summaryFields: FieldInfo[];
+}
+```
+
+JSON Schema must use same conditional validation as create_relationship:
+```typescript
+if: {
+  properties: { summary_field_id: { type: 'number' } },
+  required: ['summary_field_id']
+},
+then: {
+  required: ['summary_accumulation_type']
+}
+```
+
+Tool description (from architecture.md):
+```
+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.
+```
+
+## Dependencies
+- RELS.1001 - Domain setup complete
+- RELS.2001 - CreateRelationshipTool provides pattern for summary validation
+- Existing: Field deletion tools (mentioned in description)
+
+## Risk Assessment
+- **Risk**: Agents expect update to replace fields instead of adding
+  - **Mitigation**: Clear "ADDITIVE ONLY" in description; test and document behavior
+- **Risk**: Adding fields that already exist
+  - **Mitigation**: Handle API response appropriately; test edge case
+- **Risk**: Empty update (no fields to add)
+  - **Mitigation**: Allow but may be no-op; test and document behavior
+
+## Files/Packages Affected
+- src/tools/relationships/update_relationship.ts (new file)
+- src/tools/relationships/index.ts (update exports and registration)
+- src/__tests__/tools/relationships.test.ts (extend tests)
+
+## Deliverables Produced
+
+Documents created in `deliverables/` directory:
+
+- None
+
+## Verification Notes
+Verify-task agent should confirm tests cover all critical paths from quality-strategy.md:
+
+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 (validated by JSON Schema)
+
+Edge Cases:
+- Adding fields that already exist (verify additive behavior)
+- Empty update (no fields to add)
+
+Verify conditional validation works:
+- Providing summary_field_id without summary_accumulation_type MUST fail validation
+
+Verify additive behavior:
+- Adding new lookup fields doesn't remove existing ones
+- Adding summary field doesn't affect existing lookups
+- Result includes ALL fields (existing + newly added)
+
+## Verification Audit
+<!-- Audit log maintained by verify-task agent for enterprise compliance -->
+| Date | Agent | Decision | Notes |
+|------|-------|----------|-------|
+| 2025-12-28 | verify-task | PASS | All 10 acceptance criteria met, 143 tests passing, 100% coverage on relationships tools |