Reactive-Resume/docs/superpowers/specs/2026-07-07-applications-rest-mcp-parity-design.md

Application Tracker REST and MCP Parity

Status

Approved design for implementation planning. Campaign tracking is out of scope because the current app, database schema, changelog, guides, and tests do not ship a campaign field or campaign endpoint.

Goal

Make every shipped Application Tracker capability available outside the web UI through:

• the public REST/OpenAPI surface under /api/openapi;
• Reactive Resume MCP tools for agent-only workflows;
• the bundled resume-builder skill, so agents know the application tracker tools exist.

The result should let a user track applications through an MCP client alone: create records, import existing rows, move stages, log notes, manage contacts and follow-ups, attach sent documents, run AI copilot actions, and inspect pipeline health.

Current Shipped Capabilities

The current application tracker supports:

• application records with company, role, location, salary, source, source URL, job description, notes, tags, status, archive state, linked resume, sent resume PDF, cover-letter PDF, contacts, follow-up date/note, applied date, and activity timeline;
• fixed stages: saved, applied, screening, interview, offer, rejected;
• create, edit, archive/unarchive, mark rejected, move stage, delete;
• board, table, search, sort, tag filter, archived toggle, and command-palette open/create shortcuts;
• bulk table actions: move stage, add tag, archive, delete;
• CSV import with header mapping and a 500-row cap;
• insights from aggregate stage/source counts plus client-derived weekly application velocity;
• timeline notes and automatic created/stage activity entries;
• contacts embedded on each application;
• Application Copilot actions: job-posting autofill, resume match score, tailored resume copy, cover-letter draft, follow-up draft;
• PDF upload/remove for resume file and cover letter through the generic storage route.

Existing API Coverage

The app already routes most behavior through packages/api/src/features/applications:

• list, getById, create, import, update, addNote, delete;
• bulkUpdate, bulkDelete, stats, tags;
• ai.autofill, ai.matchScore, ai.draftMessage, ai.tailorResume.

These procedures are already authenticated and user-scoped through protectedProcedure and applicationService. The implementation should reuse them instead of adding a parallel controller or new business layer.

REST Design

Keep the existing application procedures and improve parity with the public OpenAPI surface.

Public Application Endpoints

Existing endpoints remain:

• GET /applications
• GET /applications/{id}
• POST /applications
• POST /applications/import
• PUT /applications/{id}
• POST /applications/{id}/notes
• DELETE /applications/{id}
• POST /applications/bulk-update
• POST /applications/bulk-delete
• GET /applications/stats
• GET /applications/tags
• POST /applications/ai/autofill
• POST /applications/{id}/ai/match-score
• POST /applications/{id}/ai/draft-message
• POST /applications/{id}/ai/tailor-resume

Add public document endpoints under the Applications tag:

• POST /applications/{id}/documents/{kind} where kind is resume or cover-letter.
  • Accept a PDF file via OpenAPI file upload.
  • Store through the existing storage service.
  • Update only the matching application fields:
    • resume: resumeFileUrl, resumeFileName;
    • cover letter: coverLetterUrl, coverLetterName.
  • Return the updated application.
• DELETE /applications/{id}/documents/{kind}.
  • Delete the owned storage object best-effort.
  • Clear only the matching application fields.
  • Return the updated application.

This makes the document upload/remove UI available through public REST without exposing the generic storage route, which remains tagged Internal because it also serves profile-picture use cases.

REST Behavior Details

• Use existing ownership checks: every application mutation must be scoped by userId.
• Reject non-PDF document uploads, matching the UI.
• Keep file size at the existing storage limit: 10MB.
• Preserve existing delete cleanup for uploaded documents when an application is deleted.
• Do not add server-side search/sort endpoints for board/table parity. The UI derives search and sort from list, and external clients can do the same. list already exposes status, tags, and archive filtering.
• Do not add campaign fields or endpoints.
• Regenerate or update docs/spec.json so the public API reference includes all application endpoints.

MCP Design

Add application tools to packages/mcp using the existing metadata pattern:

• add names to MCP_TOOL_NAME;
• add schemas/descriptions to TOOL_META;
• add behavior hints to TOOL_ANNOTATIONS;
• register handlers in registerTools;
• let buildMcpServerCard derive tool entries from TOOL_META;
• add focused tests so tool registration, annotations, and server card stay synchronized.

All MCP handlers should call the injected in-process oRPC RouterClient. They should not import database code or reimplement ownership checks.

MCP Tools

Read/discovery:

• list_applications: list applications, with optional status, tags, and includeArchived.
• read_application: read one full application by ID.
• list_application_tags: list distinct tags.
• get_application_stats: return aggregate stage/source counts.

Write:

• create_application: create an application.
• update_application: update editable fields, including stage, archive state, contacts, follow-up, tags, linked resume, source URL, job description, notes, and document URLs.
• add_application_note: append a timeline note.
• delete_application: permanently delete one application.
• bulk_update_applications: move, archive/unarchive, or add tags to multiple applications.
• bulk_delete_applications: permanently delete multiple applications.
• import_applications: bulk-create parsed application rows, matching the REST import shape.
• attach_application_document: attach a sent resume or cover letter PDF.
• remove_application_document: remove a sent resume or cover letter PDF.

AI:

• autofill_application_from_job: extract company, role, location, salary, and job description from a job posting URL or pasted job description.
• score_application_match: score the linked resume against the job description and persist match metadata.
• tailor_resume_for_application: create and link a tailored resume copy.
• draft_application_message: draft either a cover letter or follow-up message.

MCP Attachment Input

attach_application_document should support agent-only use. The tool should accept:

• id;
• kind: resume or cover-letter;
• fileName;
• contentType: application/pdf;
• dataBase64: PDF bytes encoded as base64.

The handler can decode the base64 and call the same shared application-document service used by the public REST file upload. This avoids forcing MCP clients to provide browser File objects while still giving agents the same document capability as the UI.

MCP Output Shape

Prefer JSON text outputs for data-bearing tools. Human-readable success strings are fine for destructive/simple tools only when no structured data is useful. For create/update/read/list/stats/AI tools, return JSON so agents can chain calls reliably.

Tool Annotations

• Read tools: read-only, idempotent, non-destructive.
• AI generation tools:
  • autofill_application_from_job is read-only but non-idempotent if it fetches a URL or calls AI.
  • draft_application_message is read-only but non-idempotent.
  • score_application_match and tailor_resume_for_application are write, non-idempotent.
• Delete tools are destructive.
• update_application, bulk_update_applications, and document remove are write/idempotent when the same input repeats, except tag append remains effectively idempotent because the service de-duplicates tags.
• create_application, import_applications, note append, and document attach are write/non-idempotent.
• openWorldHint should be false for closed account data tools and true only for job-posting autofill because it can fetch an external URL.

Skill Update

Update skills/resume-builder/SKILL.md in place.

Add concise guidance that Reactive Resume MCP can manage applications as well as resumes. The skill should tell agents:

• use application tools when the user wants to track job applications, import a spreadsheet, move an opportunity through stages, add notes/contacts/follow-ups, attach sent documents, or use Application Copilot;
• use list_applications before acting on existing records;
• use create_application or import_applications for new records;
• use tailor_resume_for_application after a linked resume and job description exist;
• review AI-generated cover letters and follow-ups before sending.

Do not turn the skill into a full API reference. Keep it short and point agents at MCP tools by name.

Documentation Updates

Update:

• docs/guides/using-the-mcp-server.mdx: add Application Tracker tools, examples, and troubleshooting notes.
• docs/use-cases/api-mcp-resume-automation.mdx: expand scope from resume-only automation to resume plus application tracking.
• docs/spec.json: refresh the public OpenAPI spec so docs show application routes.

The existing job application and CSV guides already describe the UI behavior accurately and should not need broad rewrites.

Testing Plan

Focused tests:

• API/service tests for attaching/removing resume and cover-letter documents, including ownership and storage cleanup.
• DTO/router tests for application document upload constraints if the route logic is not already covered through service tests.
• MCP tests that:
  • every MCP_TOOL_NAME has metadata and annotations;
  • server card includes the new tools;
  • registerTools registers application tools;
  • one read handler and one write handler call the expected oRPC client procedure;
  • base64 document attachment rejects non-PDF input.

Validation commands:

• pnpm --filter @reactive-resume/api test
• pnpm --filter @reactive-resume/mcp test
• pnpm --filter @reactive-resume/api typecheck
• pnpm --filter @reactive-resume/mcp typecheck
• pnpm exec turbo boundaries
• a focused Biome check on touched files; use a non-mutating check first unless formatting edits are intentionally being applied.

Non-Goals

• Custom stages.
• Campaign tracking.
• Server-side board/search/sort endpoints.
• A standalone application schema resource in MCP.
• New dependencies.
• Refactoring the application tracker UI.