@withpica/mcp-server 2.52.0 → 2.52.2

package/CHANGELOG.md

@@ -11,6 +11,99 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.52.2] - 2026-05-13
+
+### Changed
+
+- **Server-instructions polish — workspace deeplink hint after writes + paragraph trims (commits `5a2bca4a1`, `7a3e2c226`).**
+  Added a one-line coaching that agents share `https://withpica.com/workspace?type=<entity>&id=<id>` after every write tool so users get a clickable receipt back to the workspace — the cheapest version of the "chat ↔ workspace" tie-in (ADR-234), no per-tool sweep, agents construct the URL from the entity ID already in every write response. Two trims funded the addition: the `pica_execute` collision disclaimer compressed to one sentence (~120 chars saved) and the peer-MCP paragraph dropped its inline URI-scheme inventory (`gmail://` etc.) in favour of pointing at `docs/mcp-source-uri-conventions.md`, while gaining a load-bearing sentence that citations persist verbatim and propagate to applied entities (ADR-178 — `field_proposals.sources` jsonb + on-apply propagation to `recordings.field_sources`). Token budget restored 2400 → 2300, final length 2192/2300, headroom 108 chars.
+
+## [2.52.1] - 2026-05-13
+
+### Fixed
+
+- **`pica_import_analyze` TypeError (`parsed.rows` → `parsed.preview`) (PR #408, shipped 2026-05-13).**
+  Every successful analyze call returned `CSV analyze failed: Cannot read
+properties of undefined (reading 'slice')`. Three-layer contract drift:
+  the route returns `parsed: { headers, preview, totalRows, delimiter }`,
+  the SDK type declared `parsed: { headers, rows, totalRows }` (wrong
+  field, missing `delimiter`), and the MCP executor read `parsed.rows
+.slice(0, 3)`. The SDK's `request<T>()` JSON.parse-cast with no runtime
+  validation let TypeScript compile the lie. Aligned executor to read
+  `parsed.preview`; SDK type aligned in `@withpica/mcp-sdk@1.25.1`.
+
+## [2.52.0] - 2026-05-12
+
+Closes out the accumulated Unreleased buffer (some entries below shipped in
+2.49.0–2.51.0 but were never moved out of Unreleased; the `lint-changelog`
+script that lands in the next bump prevents this drift going forward).
+
+### Added
+
+- **File-delivery tools `pica_file_deliver` + `pica_file_revoke_delivery` (PR #385, shipped 2026-05-12 in `@withpica/mcp-server@2.52.0`).**
+  Agent-facing counterpart to the upload tools — symmetric with `pica_upload` /
+  `pica_upload_file`. Wraps the first-class `/admin/files/deliver` surface
+  (token + recipient_email + expiry + revocation) so agents can share files
+  out of PICA with audit-trail accountability and a kill switch. Default
+  expiry 48 hours; max 168 (one week). Registered in `discovery.uploads`
+  (now bidirectional), `metadata.ts`, `recovery-hints.ts` (deliver →
+  `rich_response`, revoke → `terminal`), and `lib/billing/tool-cost-model.data.ts`
+  (deliver → export/EXPORT, revoke → admin/ADMIN). Backed by new
+  `FilesResource` on `@withpica/mcp-sdk@1.25.0`.
+
+- **ADR-214 follow-up: cross-transport resource parity lint (`scripts/lint-resource-coverage.ts`).**
+  Asserts that `ResourceRegistry.listResources()` (stdio) and `UI_RESOURCE_DEFS` / the
+  anonymous-lobby handler (HTTP, `app/api/mcp/route.ts`) expose the same resource URIs.
+  Catches the W2 drift class — resources added to one transport only — before publish.
+  Four assertions: stdio-lobby ⊆ HTTP-lobby, HTTP-lobby ⊆ stdio-lobby,
+  stdio-authenticated \ ADR-152-carve-out ⊆ HTTP-authenticated, and the inverse
+  HTTP-authenticated ⊆ stdio-authenticated. Wired into `prepublishOnly` (after
+  `lint:agent-guide`) and `.github/workflows/mcp-tool-lint.yml`.
+
+  **Pre-existing drift detected:** `pica://schemas/sync-placement-required` is present
+  in `UI_RESOURCE_DEFS` (added in 2.47.0 per CHANGELOG) but absent from
+  `ResourceRegistry.listResources()`. The lint correctly flags this; see the PR for
+  the fix path.
+
+### Changed
+
+- **`metadata.test.ts` invariants tightened + counts re-baselined (PR #385).**
+  Four long-standing failures resolved as part of the file-delivery sweep:
+  (1) stale total-count assertion (175 → 242) reframed as a documented
+  tripwire — drift means a tool was added without a `TOOL_METADATA` entry;
+  (2) stale destructive-count assertion (12 → 17) — same shape, security-
+  relevant because the destructive-tool dispatcher routes on `risk`;
+  (3) `display_name` lowercase rule was over-strict — relaxed to "first
+  character lowercase" so legitimate acronyms (S3, GDPR, ISNI, PICA, Azure,
+  OAuth) pass per `.claude/rules/ui-components.md`'s proper-noun convention;
+  (4) `pica_storage_disconnect` had `risk: "destructive"` + `retry_safe: true`
+  in violation of the destructive-tool invariant — flipped `retry_safe` to
+  `false`. Two-step confirmation token remains the actual safety mechanism;
+  the tool's data-level idempotence claim stays true.
+
+- **Tool registry catch path now forwards `error_message` to the audit log (PR #308).**
+  When a tool throws, the registry calls `formatError()` and now passes the
+  parsed `message` through to `logToolExecution` as `error_message`. Pre-fix,
+  every error row in `mcp_audit_log` landed with `error_message=null` because
+  the wire shape stripped the field — even when the wrapper held the
+  underlying cause. Net effect for diagnostics: rows like the 116 silent
+  `pica_merge_duplicates` failures on 2026-04-09 (which couldn't be
+  attributed to any specific cause) will now carry the message going forward.
+  Sister change in `@withpica/mcp-utils` adds the field to `McpAuditEntry`.
+
+- **`pica_integrations_status` advertisement updated to current tools (PR #308).**
+  ADR-179 (commit `dc1bfca72`, 2026-04-21) folded the six per-source
+  `pica_enrich_*` tools into `pica_resolve_work` / `pica_resolve_person` /
+  `pica_resolve_recording` with a `sources:[...]` parameter, then removed
+  them. But `mcp-server/src/tools/integrations.ts` continued to advertise
+  the removed names in the `platformReads` list, the tool description, and
+  the summary prose. Agents reading the advertisement called names that no
+  longer existed → UNKNOWN*ERROR loops on every catalog-enrichment ask
+  routed through MLC/Spotify/MusicBrainz/YouTube/Discogs/ISNI. Now points
+  at the surviving tools with the correct source value. Two regression
+  tests in `integrations.test.ts` lock down that no removed
+  `pica_enrich*\*`tool name appears in the advertised`use_via` strings.
+
 ## [2.48.0] - 2026-05-03
 
 ### Changed

package/dist/prompts/creator-question-atlas.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Creator Question Atlas — ADR-226 Decision 1.
+ *
+ * Source-of-truth registry mapping natural creator questions to the
+ * canonical PICA tool / prompt resolution. Read by:
+ *
+ *   - lint Rule 11 (Phase 7) — to validate every `vernacular_kind:'creator-entry'`
+ *     tool's `Use when the user asks` block cites questions that resolve here
+ *   - the Atlas-taxonomy coupling lint (Decision 12, Phase 7) — `natural_domain`
+ *     must match `discovery.ts` CATEGORIES membership for the resolved tool
+ *   - `scripts/intent-resolution-eval.ts` — drives the eval harness corpus
+ *   - the Phase-3 description rewrite — `Use when the user asks` blocks pull
+ *     question + synonym strings from here
+ *
+ * Forward references to Phase-5-created tools/prompts are marked inline.
+ * Phase 7's lint extension reads those comments and skips them in the
+ * resolution check.
+ *
+ * `natural_domain` is required when `resolves_to.kind === 'tool'`. Omitted
+ * for prompt resolutions because prompts orchestrate cross-domain tools and
+ * don't fit a single `discovery.ts` category.
+ *
+ * Custody-related entries (49-50) intentionally surface routing only and
+ * carry no algorithmic detail — see `.claude/rules/ip-protection.md`.
+ */
+export type VernacularKind = "creator-entry" | "internal" | "specialist";
+export interface AtlasFallback {
+    message: string;
+    next_tool: string;
+}
+export type AtlasResolution = {
+    kind: "tool";
+    name: string;
+    default_args?: Record<string, unknown>;
+} | {
+    kind: "prompt";
+    name: string;
+};
+export interface AtlasEntry {
+    question: string;
+    synonyms: string[];
+    /** Required when `resolves_to.kind === 'tool'`; omitted for prompts. */
+    natural_domain?: string;
+    resolves_to: AtlasResolution;
+    fallback_when_empty?: AtlasFallback;
+}
+export declare const ATLAS: AtlasEntry[];
+//# sourceMappingURL=creator-question-atlas.d.ts.map

package/dist/prompts/creator-question-atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creator-question-atlas.d.ts","sourceRoot":"","sources":["../../src/prompts/creator-question-atlas.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,eAAe,CAAC;IAC7B,mBAAmB,CAAC,EAAE,aAAa,CAAC;CACrC;AAED,eAAO,MAAM,KAAK,EAAE,UAAU,EA0nB7B,CAAC"}