# Song Planner MCP Tool Contract Draft

Updated: 2026-06-19

Status: planned contract, not a verified remote MCP endpoint.

Do not configure an assistant client with a Song Planner MCP endpoint until the
LLM contract names a live endpoint and verified clients. This document is the
implementation contract for the next MCP/OAuth slice.

Implementation status: read-only Convex adapters exist for workspace context,
project context, song-plan context, project listing, and genre recipes. They are
not a remote MCP transport and do not publish OAuth setup.

## App And Agent Split

Song Planner is the user's durable music-creation workspace. It owns private
planner data, permissions, workflow state, source/provenance records, durable
song creation records, genre context, and user review.

The user's assistant owns reasoning, research, synthesis, drafting, browser
work, and judgment. External tools such as Suno are used only when the user has
access and explicitly asks for that operation.

## Auth And Ownership

- Private tool calls require a signed-in Song Planner account.
- Tool handlers must derive owner/account identity from verified auth.
- Clients and agents must not send owner IDs, user IDs, tenant IDs, or account
  IDs.
- Anonymous remote MCP requests must return an OAuth challenge before tool
  listing or tool calls.
- V1 must not include destructive tools, billing tools, public exports of
  private data, or external-account automation.

## First Call

When tools are available, call `songplanner_get_workspace_context` first. It
should return the active account summary, available projects, recently updated
song plans, creation modes, caps, and the recommended next tool.

## Planned Tools

### `songplanner_get_workspace_context`

Purpose: tell the agent where to begin without leaking raw private data.

Inputs: optional `projectKey`, optional `limit`.

Returns: account-safe workspace summary, projects, recent song plans, available
creation modes, current caps, and next-step guidance.

### `songplanner_list_projects`

Purpose: provide a compact project picker for agents that do not have UI
context.

Inputs: optional `limit`.

Returns: project keys, names, descriptions, counts, and last-updated summaries.

### `songplanner_get_project_context`

Purpose: load the durable context for one project before creating or editing
song plans.

Inputs: `projectKey`, optional `includeRecentPlans`, optional `limit`.

Returns: project summary, recent song plans, relevant genre context hints, and
safe workflow guidance.

### `songplanner_get_song_plan_context`

Purpose: load an existing song plan and its creation records before continuing
work.

Inputs: `projectKey` plus either `planKey` or `planId`.

Returns: song plan, research notes, lyric drafts, prompt attempts, generation
attempts, source checks, selected active records, and recommended next action.

### `songplanner_upsert_song_plan`

Purpose: create or update the durable idea and workflow state.

Inputs: `projectKey`, optional `planKey`, title, mode, status, source kind,
source refs, summary, target use, optional song key.

Idempotency: `projectKey + planKey`. Omitted optional patch fields should leave
existing values unchanged.

Returns: song plan ID, plan key, timestamps, and next-step guidance.

### `songplanner_write_research_note`

Purpose: save source notes, constraints, observations, and uncertainty.

Inputs: `planId`, optional `sectionKey`, title, markdown content, structured
data, source refs, status.

Idempotency: `planId + sectionKey`.

Returns: plan ID, section key, timestamps, and updated plan status.

### `songplanner_upsert_lyric_draft`

Purpose: save lyrics in one of the supported creation modes.

Inputs: `planId`, optional `draftKey`, title, mode, lyrics markdown, source
alignment, rationale, version, status.

Idempotency: `planId + draftKey`.

Returns: lyric draft ID, draft key, timestamps, and active draft pointer.

### `songplanner_upsert_prompt_attempt`

Purpose: save a style prompt or generation prompt attempt.

Inputs: `planId`, optional `attemptKey`, title, style prompt, negative prompt,
optional lyric draft ID, genre recipe, settings, target platform, status.

Idempotency: `planId + attemptKey`.

Returns: prompt attempt ID, attempt key, timestamps, and active prompt pointer.

### `songplanner_log_generation_attempt`

Purpose: record a Suno or other external generation result without operating
the external service.

Inputs: `planId`, optional `attemptKey`, optional prompt attempt ID, platform,
external ID, Suno URL, audio URL, status, result metadata, notes, rating.

Idempotency: `planId + attemptKey`.

Returns: generation attempt ID, attempt key, timestamps, and selected pointer
when status is selected.

### `songplanner_log_source_check`

Purpose: record checked, blocked, gated, failed, or inconclusive source work.

Inputs: `planId`, optional `checkKey`, source name, URL, status, query used,
summary, limitations, supported section keys.

Idempotency: `planId + checkKey`.

Returns: source check key, timestamps, and source-status guidance.

### `songplanner_save_creation_result`

Purpose: save a normal complete assistant result in one approval.

Inputs: `projectKey`, plan payload, optional arrays of research notes, lyric
drafts, prompt attempts, generation attempts, source checks, and an agent run.

Idempotency: natural keys inside the payload: plan key, section key, draft key,
attempt key, source-check key, and run key.

Returns: saved IDs/keys, timestamps, changed sections, and the next step for
the user.

### `songplanner_get_genre_recipe`

Purpose: read public genre encyclopedia context for prompt writing.

Inputs: genre or tag names, optional level/family, optional limit.

Returns: style ingredients, instrumentation, rhythm, vocal, production texture,
era/mood markers, related subgenres, and safe prompt language.

## Response Caps

- Workspace/project context should be compact by default.
- Arrays should be capped and include truncation flags.
- Long markdown fields should be summarized unless full detail is requested.
- Tools should return stable IDs, natural keys, timestamps, and next-step
  guidance.

## Failure Modes To Prevent

- stale tool lists after deploy;
- approval fatigue from too many granular writes;
- duplicate records from missing natural keys;
- clients sending owner/user IDs;
- agents scraping private web pages instead of using MCP tools;
- repeated retries against blocked/gated sources;
- claims that public-domain status is certain without a source check;
- external account automation without explicit user direction.

## Verification Required Before Marking MCP Live

- unauthenticated requests return the expected OAuth challenge;
- protected-resource metadata is correct;
- a real client connects, lists the documented tools, and calls the workspace
  context tool;
- write tools persist data under the authenticated owner;
- saved data appears correctly in the web UI;
- docs name the live endpoint, verified clients, expected tool names, and
  reconnect/stale-tool recovery steps.