@withpica/mcp-server 2.56.0 → 2.57.0

package/CHANGELOG.md

@@ -11,6 +11,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.57.0] - 2026-05-18
+
+Closes the ADR-241 substrate sprint — agent-side orientation skill, dashboard coherence with SQL-side `NOT EXISTS`, and 4 sister bug fixes that the agents themselves filed via `pica_report_issue` over the preceding 72 hours.
+
+### Added
+
+- **`first-session` skill (ADR-241).** Agent-side counterpart of `set-up-workspace`. Five phases: identity recognition → reporting-discipline opening note → context load → priority ranking + routing → close-out sweep. Names the right specialist skill per priority class and hands the steering wheel over — does NOT invoke the specialist itself. Discoverable via `pica_skill_list` + the `skill://withpica/first-session/SKILL.md` Resource per the SEP-2640 bridge.
+- **`SERVER_INSTRUCTIONS` coaching line.** Directs the agent to call `pica_skill_get("first-session")` on the first user message of a session unless the prompt is already task-specific. Char budget bumped 2300 → 2400 to fit the addition; final length 2337.
+- **`pica_issue_agent_grant.scopes.items.enum`** — the 15 `VALID_SCOPES` are now declared inline in the JSON Schema, surfacing through `pica_tool_details` introspection. Closes ops_issue `3a65aa71` (agents trial-and-erroring on `write:works` / `write:credits` / `write:enrichment` which aren't valid; only `write:catalog` is).
+- **`pica_dashboard_attention` gains a `class` filter** taking one of `works_without_credits | works_without_registrations | audio_pending | unenriched_writers | recordings_without_splits | disputed_credits`. Specialist skills now have a single-call entry to the top-of-their-own-queue (ADR-242).
+- **`pica_count_explain` taxonomy mode** — omit `count_source` to get the full actionable-issue taxonomy as `sources[]` with `drill_down_skill` named per class. Machine-readable routing table that ADR-241's `first-session` skill reads to pick its next step.
+
+### Changed
+
+- **`pica_dashboard_briefing` / `_attention` / `pica_count_explain` are now coherent projections of a single shared source.** Implements ADR-242 § Decision: new `lib/services/dashboard-actionable.ts` (`getActionableIssues()` with a per-class registry); three projection helpers shape its output for the three tool handlers. `sum(count_explain.sources[].count) === briefing.critical_issues_total` for the same org/moment, by construction. Closes ops_issue `4042e806` (briefing 1495, count_explain 338, attention 0 — three tools, three numbers, no path through).
+- **`pica_works_query health_filter='needs_attention'` no longer errors.** Hardens `getWorksHealth()` with per-work try/catch; restores `needs_attention` routing in the assembled-truth path. Closes ops_issue `4da6a869`.
+- **`pica_split_sheet_generate` "No credits found" surfaces as 400, not 500.** Routes through the user-input-error classifier so agents see an actionable message instead of an opaque server error. Closes ops_issue `899a3d63`.
+- **`pica_submit_feedback` dedups by content-hash, not session-time.** Distinct content within the same session now passes; identical resubmissions still dedup within the rate-limit window. SDK errors propagate to `mcp_audit_log` via the error envelope (was silent generic error). Closes ops_issues `4bab716a` + `808e5fa0`.
+- **`pica_memory_save` accepts both kebab-case slugs and UUIDs.** Root cause: validator used `apiKey.keyId` (not a valid `user_id` FK) for the `user_id` field; row insert failed silently and surfaced as `"invalid id format"`. Closes ops_issue `315ef479`.
+
+### Dependencies
+
+- `@withpica/mcp-sdk` `^1.27.1` → `^1.28.0` (new `DashboardResource.actionableItems` + `CountExplainResource.taxonomy` methods).
+- `@withpica/mcp-utils` `^1.21.1` → `^1.22.0` (workspace-version-alignment fix; develop's Vercel deploy was failing since 2026-05-17 because the `^1.21.1` range that 2.56.1 introduced was not satisfied by the local `1.21.0` workspace, forcing CI/Vercel to pull a duplicate copy from npm registry and breaking type identity).
+
+### Database (staging applied; production applies on develop → main promote)
+
+- Migration `20260517220000_adr242_actionable_issues_rpcs.sql` — 4 Postgres functions (`dashboard_actionable_works_without_credits`, `..._works_without_registrations`, `..._recordings_without_splits`, `..._unenriched_writers`) using SQL-side `NOT EXISTS`. PICA builds for scale; the fetch-all + filter-in-JS pattern was rejected by the founder. All four `LANGUAGE sql STABLE SECURITY INVOKER SET search_path = ''` per the 2026-05-11 function-hardening sweep.
+
+## [2.56.1] - 2026-05-17
+
+### Changed
+
+- Brand consistency: "PICA" → "withPICA" in package metadata, keywords (added `"withpica"`, `"music-catalog"`, `"music-rights"`), README, JSDoc headers, and customer-visible tool descriptions: `pica_delete_my_account`, `pica_gdpr_export_my_data` (description + completion message), `pica_telegram_connect`, `pica_onboarding_complete` (description + `intent_notes` field), and the `new-catalog-setup` prompt.
+- Registered `pica_works_attest` and `pica_credits_send_for_attestation` in `REQUIRED_SCHEMAS_SOURCE` companion_calls (both tools declared workflow membership but weren't referenced — pre-existing drift caught by `lint:required-schemas`).
+
+### Fixed
+
+- **`pica_submit_feedback` + `pica_physical_assets_create` no longer leak SDK errors to the user (PRs #453 + #457, 2026-05-15).**
+  Both executors had naked SDK calls — when the upstream API errored, the
+  framework's outer catch in `tools/index.ts` JSON-stringified the error
+  body straight to the conversation (`{error: "UNKNOWN_ERROR", message: "..."}`).
+  Wrap each SDK call in `try/catch`: on throw, fire-and-forget
+  `pica.opsIssues.reportIssue({ kind: "tool_failure", ... })` with the
+  underlying message + status + parameter shape in `context`, return
+  neutral text (`"couldn't <verb> right now — the team has been alerted."`).
+  Input-validation early-returns are preserved — those carry actionable
+  text and aren't server failures. PR #457 added `tool_failure` to the
+  `OpsIssueExplicitKind` taxonomy and retagged both wrappers (PR #453
+  shipped as `kind: "data_issue"` because `tool_failure` didn't exist
+  yet). 12 new unit tests across `feedback.test.ts` (new file) +
+  `assets.test.ts`. **Note:** the auto-audit upsert path is bypassed
+  because returning `isError: true` logs as `result_status: "success"`
+  (`tools/index.ts:1859`) — the executor reports manually instead.
+
+### Added
+
+- **`pica_report_issue` accepts `kind: "tool_failure"` (PR #457, 2026-05-15).**
+  Sixth value in the agent-explicit kinds enum. Lets agents file SDK /
+  upstream-tool failures directly via the report-issue tool, mirroring
+  the new fail-quiet wrappers.
+
 ## [2.56.0] - 2026-05-14
 
 ### Added

package/README.md

@@ -1,10 +1,10 @@
-# PICA MCP Server
+# withPICA MCP Server
 
-Model Context Protocol (MCP) server for the PICA Platform. Enables **any MCP-compatible AI assistant** to interact with your PICA music catalog.
+Model Context Protocol (MCP) server for withPICA. Enables **any MCP-compatible AI assistant** to interact with your withPICA music catalog.
 
 ## What is MCP?
 
-The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data and functionality. With this MCP server, any MCP-compatible AI can interact with your PICA catalog.
+The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data and functionality. With this MCP server, any MCP-compatible AI can interact with your withPICA catalog.
 
 ## Compatible AI Assistants
 
@@ -89,9 +89,9 @@ npm link
 
 ## Configuration
 
-### Get Your PICA API Key
+### Get Your withPICA API Key
 
-1. Log into PICA at https://withpica.com
+1. Log into withPICA at https://withpica.com
 2. Go to Settings → API Keys
 3. Generate a new API key
 4. Copy the key for use below
@@ -123,7 +123,7 @@ The setup process is similar for any MCP-compatible tool:
 
 1. Configure the MCP server command: `npx -y @withpica/mcp-server`
 2. Set the `PICA_API_KEY` environment variable
-3. The AI can now access all PICA tools and resources
+3. The AI can now access all withPICA tools and resources
 
 ## Usage Examples
 
@@ -267,7 +267,7 @@ Make sure you've set the API key in your MCP server configuration:
 ## Architecture
 
 ```
-MCP Server for PICA
+MCP Server for withPICA
 ├── Protocol Handler (MCP standard)
 ├── Authentication (API key)
 ├── Tools (24 AI-callable functions)
@@ -281,7 +281,7 @@ MCP Server for PICA
 
 ## Security
 
-- All requests require a valid PICA API key
+- All requests require a valid withPICA API key
 - API keys are transmitted securely over HTTPS
 - Data access is scoped to your organization
 - No data is stored by the MCP server
@@ -301,4 +301,4 @@ MIT
 Built with:
 
 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
-- [@withpica/sdk](https://www.npmjs.com/package/@withpica/sdk) - PICA TypeScript SDK
+- [@withpica/sdk](https://www.npmjs.com/package/@withpica/sdk) - withPICA TypeScript SDK