131 lines
6.3 KiB
Markdown
131 lines
6.3 KiB
Markdown
---
|
|
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*
|