MCP Coverage Gap and Tool Build Queue

North star (PRINCIPLES.md #7): every action a human can take in the dashboard must have an MCP-tool equivalent. The product's main surface is the collaborative job-market matrix; MCP lets an agent operate that same workspace table instead of creating a parallel workflow. The practical target is: a human can ask an agent to add an internet job offer, enrich and evaluate it against the workspace criteria, inspect or adjust the CVL tree, tailor the application material, and keep the row state understandable from the dashboard.

1. Inventory of current MCP tools

Source: mcp/src/tools/ (registered in tools/index.ts).

1a. Status of the section.* → node.* rename, tailor unification, get_cv_typst, delete_node, set_selection, translate

All renames and missing tools have now landed:

Remaining gaps (not yet resolved):

• tailored.promote is missing from MCP. Always adds as new variant; no mode arg.
• cv_profile.replace / cl_profile.replace — no tool exposes per-language full-tree replace; needed to seed a fresh language from agent code.
• mcp/test/tools.test.ts — confirm tests were updated alongside the renames; stale assertions against sections.create / sections.update op kinds would be a regression.

PDF posture is locked: client-only rendering. No analyze_pdf tool. No server-side Typst. Agents use get_cv_typst for source (compile locally), or download_file for cached PDF bytes from R2. See §5.1.

2. Inventory of human capabilities (v2 + v1 reference)

Walked through ui/src/routes, ui/src/lib/components/toolbar/modals/, ui/src/lib/components/cvl/, and ui/src/lib/components/dashboard/.

Capability areas:

A. Workspace lifecycle

A1. Create workspace (POST /api/workspaces). A2. List workspaces — v1 had a landing-page list; v2 home page is a stub. No GET /api/workspaces. A3. Rename workspace name / slug — v2 calls PUT /api/workspaces from layout but route does not exist (PARITY-AUDIT §3.1). A4. Delete workspace — DELETE /api/workspaces/:id not ported (PARITY-AUDIT 4.13). A5. Resolve / "switch" workspace by slug — GET /api/workspaces/:id accepts both id and slug; no list-and-pick tool for agents that don't already hold an id.

B. Job lifecycle

B1. Add by URL — POST /api/workspaces/:id/jobs with {url}. Pipeline auto-advance is unimplemented client-side (PARITY-AUDIT 4.1). B2. Add manually — same endpoint, with {title, organization, ...}. B3. Bulk import (CSV/JSON wizard) — UI is a 36-LoC stub (PARITY-AUDIT 4.10). B4. Bulk URL paste (JobImport modal) — stubbed, blocked on scrape.ts lift status. B5. JobRadar (job-board scraping) — stubbed, blocked on radar.ts lift. B6. Edit job fields — PATCH /api/workspaces/:id/jobs/:jobId. B7. Delete job — DELETE /api/workspaces/:id/jobs/:jobId. B8. Move status / phase — _statusOnly flag on PATCH; kanban DnD ports the gesture. B9. Archive job — represented by terminal status; no separate archive op.

C. PDF / file handling

C1. Upload CV / CL / misc — POST /api/workspaces/:id/files returns 501 (PARITY-AUDIT 4 / §3 row "File upload"). Op files.upload exists in catalog. C2. Download tailored CV/CL or attachment — GET /api/files/:fileId?workspace=… works. C3. Delete file — DELETE /api/files/:fileId?workspace=… works (ref-count + R2 cascade). C4. Render tailored CV/CL to PDF — happens client-side via Typst WASM (lib/domain/src/typst.ts + typst-client.ts); there is no server endpoint and no MCP tool. Agents cannot get PDF bytes. C5. PDF analysis (read-the-PDF) — no v1 or v2 surface; CV upload is treated as opaque bytes (this is consistent with how v1 worked).

D. CV / CL editing (the L0/L1/L2 tree)

D1. Personal info edits — pending design (PARITY-AUDIT §5.1: tree-of-choices says PersonalInfo collapses into a Node). D2. Header layout (drag chip bar, H toggles) — InfoEditor stub. D3. Format edits (font, colors, conventions, link styling, ortho, dateFormat) — FormatEditor stub. D4. Section / Node CRUD — node.create / update / delete / move. D5. Bullet / item CRUD — same Node ops at deeper depth. D6. Selection: which children render, in which order, max-count — selection.update op. D7. Variants: snapshot a tailored output, promote variant L2 → L1 / L0 — tailored.snapshot, tailored.promote. D8. Per-language replace (seed a new lang) — cv_profile.replace / cl_profile.replace. D9. Profile narrative (markdown blob injected into every tailoring prompt) — page is a stub; no Y.Doc root or REST path exists.

E. Pipeline

E1. Trigger extraction (URL → fields) — v1 /api/extract-fields endpoint, now 410 Gone with note "moved to MCP" — but no MCP tool actually exists. E2. Trigger enrichment (salary estimation, commute) — /api/commute lifted; salary.ts not lifted (PARITY-AUDIT 4.2). E3. Trigger evaluation — /api/evaluate 410s with note "moved to realtime worker"; not implemented in the worker either, no MCP tool. E4. Trigger tailoring — tailor_cv / tailor_cl only persist; no tool that actually runs the tailoring chain. (Per principle #8 LLM is client-side; the agent is the LLM here, so trigger semantics on MCP = "run my own LLM and call tailor_*". This is okay but the agent needs the input context — there is no tool that returns "everything tailoring needs": job + quarry + cascade chain + format + language + narrative.) E5. Monitor pipeline state — no read tool returns per-job stage / led status. E6. Cancel pipeline run — n/a, no run state on the server side.

F. Cascade / BYOK

F1. List providers / capabilities — v2 has PROVIDERS config in @cv/domain; no MCP read tool. F2. Set provider keys (BYOK) — PATCH /api/workspaces/:id/cloud-keys. Note: cloud_keys writes are blocked over the WebSocket op channel for secret-leak reasons (validate.ts); the cloud_keys.update op is reserved for service-binding (i.e. MCP) callers. F3. Read cascade chain — GET /api/chain?workspace=… returns unmasked keys. No MCP tool wraps it (and probably shouldn't, see "cross-cutting"). F4. Edit chain order / promote provider — Models tab UI; no REST endpoint yet (it patches cloud_keys.chains via the cloud-keys PATCH). F5. Health check a provider — POST/GET /api/health-log records timeline; no actual "ping this provider with my key" endpoint, no MCP tool.

G. Notes / scoring / annotations

G1. Workspace notes (collaborative ProseMirror) — v2 dropped the editor; /api/notes returns 410 (PARITY-AUDIT 4.6). G2. Set scoring criterion — set_score_criterion (existing). G3. Set evaluations — evaluate_job (existing). G4. Set scoring config (aggregation mode, weights) — settings.update via Y.Doc; no granular MCP tool.

H. Views

H1. List views — list_views (existing). H2. Set active view — set_active_view (existing). H3. Create / edit / delete a view (groups, rules, sort) — Views modal in UI; no MCP tool. H4. Column visibility, widths, layout — layout.update op exists; no MCP tool. H5. Kanban config (phases, statuses, swimlanes) — Kanban modal; no MCP tool. H6. Order state mutations (column / group / job manual order) — order_state.update op; no MCP tool.

I. Export

I1. Export to xlsx / csv — prepareExportData + exportToExcel in @cv/domain/export; UI button is a console.warn no-op (PARITY-AUDIT row "Export"). I2. Render PDF — see C4. I3. Raw Typst source — stackToTypst lifted; no endpoint or tool.

J. Multi-language

J1. Switch active lang — handled in format.lang; UI in CvGenerator chip list. J2. Add a new lang — UI uses a prompt() (PARITY-AUDIT row "Language switching"); no MCP tool. J3. See L1 deltas — implicit in tree structure; no read tool exposes "delta of lang X vs base." J4. Promote L2 → L1 / L0 — tailored.promote op exists, no MCP tool.

3. Gap matrix

Severity:

• P0 — blocks the chat-first workflow ("paste URL → ingest → tailor → export PDF" must work end-to-end via MCP).
• P1 — high-value editing or read capability the agent needs to be useful.
• P2 — nice-to-have, used rarely or by humans only.

Counts (updated): After 2122c85 and 15657aa, delete_node, set_selection, and translate are now "done". D4 delete (P0), D6 selection (P0), and translate (unlisted in original) are closed. P0 count drops to 10. Remaining P0 = 10, P1 = 21, P2 = 14.

4. Build queue (updated state)

Original top-10, with completed items marked. Ordered by north-star impact.

Implicit (deferred): set_chain_order + list_providers — important for BYOK flows, but agents will mostly receive keys out-of-band. Defer until P0 list is closed.

5. Cross-cutting concerns

5.1 PDF rendering boundary [LOCKED 2026-04-26]

Decision: client-only rendering. No server-side Typst on Cloudflare Workers.

Typst WASM (~25MB) loads from CDN, fonts preload into a virtual filesystem, stackToTypst() produces the source, $typst.pdf() produces bytes in the browser. Server-side Typst on Cloudflare Workers would burn CPU budget and fights PRINCIPLES.md #8 (client compute is the default).

Agent PDF access paths:

• PDF bytes: agents pull from the most recent cached client render stored in R2 via download_file / GET /api/files/:fileId.
• Typst source: agents call get_cv_typst which returns the source text directly. Agents can compile locally (e.g., typst CLI on the user's machine via Claude Code).

There is no render_pdf tool that produces bytes on-demand from the server. get_cv_typst (build queue #8, shipped at commit c04203e) is the correct approach for agent-driven PDF generation.

OCR / vision posture [LOCKED 2026-04-26]: CareerVector does NOT build OCR or PDF extraction. Agents (Claude, GPT-4o, Gemini, etc.) have vision built-in; when a user uploads a reference PDF, the agent reads it itself via the file URL. CareerVector exposes three pathways for the agent: structured Node tree, Typst source as text, and file bytes. Files are uniform — get_file(fileId) does not distinguish "rendered output" from "user-uploaded reference." A PDF is a PDF. There is no analyze_pdf tool and none will be added.

5.2 URL ingestion / scrape.ts

scrape.ts already lives at lib/domain/src/scrape.ts (with tests/scrape.test.ts). The lift is done. What's missing is the wiring: extract_fields tool, plus the client-side JobImport modal calling it. Build queue #2 is unblocked on the import side.

5.3 Output bytes — URL vs base64

MCP tools return text content. Both modes are legal:

• base64 in structuredContent: simple, no URL plumbing, works without auth. Agents (Claude) handle base64 cleanly. Bad for files > a few MB (token cost in the agent's context window).
• URL the agent fetches: forces the agent (or its host) to be allowed to make HTTP requests to our domain. Fine for Claude Code, less fine for sandboxed agents.

Recommendation: thresholded. For files ≤ 1 MB, return base64 in structuredContent. For larger (typical tailored PDFs are 50–200 KB so we're rarely there), return {url, expiresAt} and let the agent fetch. Document the threshold in the tool's description so agents can plan.

5.4 Streaming / long-running jobs

Tailoring takes 30–60 s. PDF compile is faster (<5 s on the client; unknown on the server). Options:

1. Block. Tool waits until done, returns the result. Simple. Risks: MCP transport timeouts (varies by client), agent UX (no progress indicator).
2. Job-id + poll. Tool returns {jobId}; agent polls get_job_status(jobId) until done. Familiar pattern; fits well with the singleflight compute_lock pattern already in v1. Adds infra (a job table or D1 row).
3. Realtime fan-out. Mutation triggers a DO broadcast; agent subscribes via WebSocket. Powerful but MCP transports don't generally do WebSockets — the agent host would need an extra capability.

Recommendation: for tailoring, since the agent IS the LLM (per principle #8), the tool only persists the result — it's not waiting on a server-side LLM call. So tailoring tools (tailored_snapshot, tailor_cv) can block trivially (write completes in ms). For PDF rendering, recommend block (option 1) with a documented soft cap of ~30 s. For extract_fields: same logic — the agent runs the LLM, so the tool just persists, no wait. Job-id pattern not needed yet.

5.5 Workspace identity / agent default workspace

Per principle #5, possessing the workspace ID is the access credential. There is no default workspace and no auth.

Three patterns make sense:

1. Agent connection pinned to one workspace. The MCP server URL includes the workspace id (?ws=<id> or as a header). Every tool call inherits it; tools could omit wsId from args.
2. Tools always require wsId. Current state. Predictable but verbose.
3. Hybrid: connection-level default, tool-level override. Best of both.

Recommendation: keep current behavior (tools take wsId). Add a MCP_DEFAULT_WORKSPACE env var on the worker for single-tenant deployments (per agent install). Document in tool descriptions: "If your MCP host is configured with a default workspace, you may omit wsId." list_workspaces (P1) is the resolution mechanism for new agents that don't know the slug.

For the BYOK keys sensitive case: the cloud-keys.update op is intentionally allowed only over the service binding (i.e. MCP, not the public WS) per validate.ts. So a set_byok_keys tool can write keys without the leak risk. Read paths must remain masked through MCP — never expose /api/chain (unmasked) via a tool.

6. Things needing user input before #1 starts

1. Notes editor decision. v1 had a 1057-LoC ProseMirror editor; v2 dropped it. Is this intentional (= remove /api/notes + don't add an MCP tool) or a port miss? Not on the critical path either way, but a "decide once, document" item.
2. Server-side PDF rendering posture. LOCKED 2026-04-26 — client-only. See §5.1. No action needed.
3. Profile narrative storage. Where does the markdown blob live? A new Y.Doc root (profile.narrative), an extension of cv_profile's root Node, or a workspace settings field? Tree-of-choices is silent. Decide before #5 (get_tailoring_context) — without it, the tool returns an empty narrative and tailoring quality stays degraded.
4. PDF analysis (vision). LOCKED 2026-04-26 — NOT building OCR/vision. Agent reads PDFs itself. No analyze_pdf tool. See §5.1.
5. MCP per-host default workspace. Confirm pattern in §5.5 ("env var per worker install, tools still take wsId for explicitness") matches Julian's deploy model.

7. Out of scope (this doc)

• Implementation. This is a plan.
• New product features beyond v1 / v2 today. Greenfield restraint per task brief.
• Touching files owned by other agents.

End of MCP-COVERAGE.md.