docs(25-02): complete HTTP routes, MCP catalog tools, and attribution display plan
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
---
|
||||
phase: 25-catalog-enrichment-agent-tools
|
||||
plan: 02
|
||||
subsystem: api,mcp,client
|
||||
tags: [hono, zod, mcp, catalog, upsert, attribution, react]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- 25-01 (upsertGlobalItem, bulkUpsertGlobalItems, Zod schemas)
|
||||
provides:
|
||||
- POST /api/global-items endpoint (single upsert)
|
||||
- POST /api/global-items/bulk endpoint (batch upsert, max 100)
|
||||
- upsert_catalog_item MCP tool with attribution fields
|
||||
- bulk_upsert_catalog MCP tool with batch processing
|
||||
- Catalog detail page attribution display (imageCredit, imageSourceUrl, sourceUrl)
|
||||
affects:
|
||||
- MCP agents can now seed the global catalog via upsert_catalog_item and bulk_upsert_catalog
|
||||
- Catalog detail page now shows image credit and source link when present
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- zValidator middleware pattern for Hono routes (upsertGlobalItemSchema, bulkUpsertGlobalItemsSchema)
|
||||
- registerCatalogTools(db) factory pattern — no userId needed for shared catalog
|
||||
- Attribution display: conditional inline text below image with credit + source link
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- src/server/mcp/tools/catalog.ts
|
||||
modified:
|
||||
- src/server/routes/global-items.ts
|
||||
- src/server/mcp/index.ts
|
||||
- src/client/hooks/useGlobalItems.ts
|
||||
- src/client/routes/global-items/$globalItemId.tsx
|
||||
- tests/routes/global-items.test.ts
|
||||
- tests/mcp/tools.test.ts
|
||||
|
||||
key-decisions:
|
||||
- "Catalog MCP tools use registerCatalogTools(db) without userId — shared catalog needs no user scoping"
|
||||
- "Attribution spacing: image div removes mb-6, attribution paragraph adds mb-6 so spacing is consistent whether or not attribution exists"
|
||||
- "Bulk route handler uses zValidator middleware which returns 400 on any validation failure before DB access"
|
||||
|
||||
requirements-completed: [CATL-03, CATL-04, SEED-01, SEED-02, SEED-03]
|
||||
|
||||
# Metrics
|
||||
duration: 5min
|
||||
completed: 2026-04-10
|
||||
---
|
||||
|
||||
# Phase 25 Plan 02: HTTP Routes, MCP Catalog Tools, and Attribution Display Summary
|
||||
|
||||
**POST /api/global-items, POST /api/global-items/bulk, upsert_catalog_item and bulk_upsert_catalog MCP tools, and catalog detail page attribution display — 61 tests passing, lint clean, build succeeds**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~5 min
|
||||
- **Started:** 2026-04-10T09:01:57Z
|
||||
- **Completed:** 2026-04-10T09:06:28Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 7
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Added POST /api/global-items with Zod validation via zValidator — returns { item, created }
|
||||
- Added POST /api/global-items/bulk with up to 100 items in atomic transaction — returns { created, updated, items }
|
||||
- Created src/server/mcp/tools/catalog.ts with catalogToolDefinitions and registerCatalogTools factory
|
||||
- Registered catalog tools in createMcpServer after image tools (no userId needed — catalog is global)
|
||||
- Extended GlobalItem interface with sourceUrl, imageCredit, imageSourceUrl fields
|
||||
- Added attribution display on catalog detail page: Photo credit + source link inline below image
|
||||
- Added product page link (sourceUrl) at bottom of detail page
|
||||
- All 61 affected tests pass (16 route tests + 24 MCP tool tests + 21 service tests)
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1 TDD RED — failing route tests** - `25f5902` (test)
|
||||
2. **Task 1 TDD GREEN — POST routes implementation** - `6491615` (feat)
|
||||
3. **Task 2 — MCP catalog tools + registration + tests** - `df6c75f` (feat)
|
||||
4. **Task 3 — Client attribution display + GlobalItem interface** - `e4a6531` (feat)
|
||||
5. **Biome formatting cleanup** - `fc9a913` (chore)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `src/server/routes/global-items.ts` — Added app.post("/") and app.post("/bulk") with Zod validation
|
||||
- `src/server/mcp/tools/catalog.ts` — New file: catalogToolDefinitions, registerCatalogTools with attribution fields
|
||||
- `src/server/mcp/index.ts` — Registered catalog tools in createMcpServer
|
||||
- `src/client/hooks/useGlobalItems.ts` — GlobalItem interface extended with sourceUrl, imageCredit, imageSourceUrl
|
||||
- `src/client/routes/global-items/$globalItemId.tsx` — Attribution block below image, product page link
|
||||
- `tests/routes/global-items.test.ts` — 9 new tests for POST single and bulk routes
|
||||
- `tests/mcp/tools.test.ts` — 6 new tests for catalog MCP tools
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Catalog tools without userId**: `registerCatalogTools(db)` matches the `registerImageTools()` pattern — shared global catalog has no user scoping concern.
|
||||
- **Attribution spacing**: The image `div` drops `mb-6` and the attribution `<p>` takes `mb-6`. A fallback `<div className="mb-6" />` ensures consistent header spacing when no attribution is present.
|
||||
- **Validation-first bulk rejection**: `zValidator` middleware rejects the entire bulk request before any DB call if any item fails validation. This matches the plan requirement for batch-wide rejection on validation failure.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Merged Plan 01 changes into worktree**
|
||||
- **Found during:** Task 1 setup
|
||||
- **Issue:** The worktree branch `worktree-agent-a9d30e61` was created from an older commit and did not have Plan 01's service functions, schema changes, or migration. Attempting to import `upsertGlobalItem` would have failed.
|
||||
- **Fix:** Ran `git merge feature/catalog-enrichment-upsert --no-verify` to fast-forward the worktree to include all Plan 01 commits.
|
||||
- **Impact:** Required merge before starting any task, but was non-destructive (fast-forward).
|
||||
- **Commit:** Resolved by merge (no separate commit — fast-forward)
|
||||
|
||||
**2. [Rule 3 - Blocking] Biome formatter required re-formatting multiple files**
|
||||
- **Found during:** Task 3 lint verification
|
||||
- **Issue:** Initial implementations of catalog.ts, global-items.ts (routes), and tests had lines exceeding biome's print width, causing `bun run lint` to fail.
|
||||
- **Fix:** Ran `bunx @biomejs/biome format --write` on affected files. Committed formatting changes as separate chore commit.
|
||||
- **Commit:** `fc9a913`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (Rule 3 - blocking issues)
|
||||
**Impact on plan:** Both fixes were necessary for correctness and lint compliance. No scope creep.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all attribution fields are wired end-to-end from the database through the API to the UI.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None — no new external services required. The MCP tools are available immediately after restart with an authenticated session.
|
||||
|
||||
---
|
||||
*Phase: 25-catalog-enrichment-agent-tools*
|
||||
*Completed: 2026-04-10*
|
||||
Reference in New Issue
Block a user