<!--
  Hand-written prose for the two published npm READMEs.

  `scripts/build-mcp-readmes.mjs` splices each block below onto a generated
  tool inventory and writes `mcp-server/README.md` and
  `mcp-server-directory/README.md`. Edit the prose HERE; never edit the
  generated files, which carry a do-not-edit banner and are checked by
  `node scripts/build-mcp-readmes.mjs --check`.

  Both intros live in this one file because the generator has one input for
  prose and one for structure. The markers below are load-bearing — the
  generator splits on them.
-->

<!-- readme:mcp-server -->

# @withpica/mcp-server

MCP server for **withPICA** — music catalog management through conversation. Works, recordings, credits, agreements, rights, royalties, enrichment and registration-ready exports, from Claude, ChatGPT, Cursor, or any MCP-compatible client.

> **Not the same product as `@picahq/mcp`.** That is Pica / picaos.com, an unrelated API-integrations tool that happens to share the short name. If your assistant starts talking about integrations it never set up, or asks you to paste credentials into a dashboard, you have the other one installed.

## Install

```bash
claude mcp add withpica -- npx --yes @withpica/mcp-server@latest
```

Or, in any client that reads an `mcpServers` config:

```json
{
  "mcpServers": {
    "withpica": {
      "command": "npx",
      "args": ["@withpica/mcp-server"]
    }
  }
}
```

## Signing in

**On stdio (this package), no API key is needed up front.** Say _"sign me in to withpica"_ in chat; `pica_sign_in` emails you a magic link, you click it, and your tools unlock. `PICA_API_KEY` in the environment also works and skips the link.

**On the hosted HTTP transport** (`https://withpica.com/api/mcp`) there is no in-chat sign-in — `pica_sign_in` and `pica_sign_out` are stdio-only, because the credential file they write would land on an ephemeral filesystem your client never reads. Connect over OAuth 2.1 instead (dynamic client registration + PKCE S256, discovery at `https://withpica.com/.well-known/oauth-protected-resource`), or send an API key as a Bearer token. A Bearer caller should call `pica_introduce_self` first: PICA stamps that declaration onto every audit row that follows, so the owner can later reconstruct what their agent did.

API keys are created and revoked at <https://withpica.com/settings?tab=connections>.

## How the tools are surfaced

Over HTTP the server advertises a small meta-tool surface by default — `pica_discover` → `pica_tool_details` → `pica_execute` — so a schema-constrained client is not handed the whole registry at once. Every tool stays callable by name. Add `?layered=0` to the endpoint for the eager list.

Over stdio the full set is listed directly.

`pica_skill_list` / `pica_skill_get` load methodologies (catalog-audit, register-my-works, prepare-for-sync) as needed, rather than at handshake.

## Safety

Read tools are annotated read-only and are safe to call freely. Write tools report what changed. Destructive tools (delete, merge) require a two-step confirmation token and an elevated scope that ordinary agent grants cannot hold.

## Environment variables

| variable       | required | meaning                                           |
| -------------- | -------- | ------------------------------------------------- |
| `PICA_API_KEY` | no       | skips the magic-link flow                         |
| `PICA_API_URL` | no       | API base URL (default `https://withpica.com/api`) |
| `DEBUG`        | no       | verbose logging to stderr (`true` / `1`)          |

## Links

- Connect guide: <https://withpica.com/connect>
- Machine-readable: <https://withpica.com/llms.txt>, <https://withpica.com/connect/llms.txt>
- Discovery: <https://withpica.com/.well-known/mcp.json>
- Support: support@withpica.com

<!-- readme:mcp-server-directory -->

# @withpica/mcp-server-directory

MCP server for the **withPICA public directory** — search over works, recordings and creators that rights holders have chosen to publish, plus one write: sending a licensing enquiry to an owner, when the user asks. Also hosted, no install: connect a remote MCP client to `https://withpica.com/api/mcp/directory`. No account, no API key, no setup.

## Install

```bash
claude mcp add withpica-directory -- npx --yes @withpica/mcp-server-directory@latest
```

## What it can answer

Who wrote this song. What the ISWC is. Which recordings exist of a work and what their ISRCs are. Which creators match a name, an ISNI or an IPI. Which published recordings sit in a tempo, key, energy or mood range. And, in one call, the rights chain for a work: writers, publishers, recording, audio.

Every entry is published deliberately by its rights holder, with attested credits and verified identifiers.

## REST, if you would rather not run a process

- `GET https://withpica.com/api/public/directory/works`
- `GET https://withpica.com/api/public/directory/people`
- `GET https://withpica.com/api/public/directory/search?q={query}`
- `GET https://withpica.com/api/public/directory/recordings`
- `GET https://withpica.com/api/public/directory/consent?iswc={iswc}`

100 requests/minute unauthenticated. Licensing keys unlock extended fields and their own limits.

## Before you train on any of this

withpica.com publishes a blanket TDM reservation at <https://withpica.com/.well-known/tdmrep.json> (`"tdm-reservation": 1`). Nothing here is licensed for text-and-data mining or model training by default.

The `consent` endpoint above is the granular counterpart: ask it about an identifier and it reports what the rights holders have actually cleared, and at what level. A work is cleared at a level only when every credited contributor has granted at least that level; one refusal blocks it. Read `no_assertion_published` literally — it means no permission is published for that identifier, which is not a maybe.

## Links

- Directory: <https://directory.withpica.com>
- Machine-readable: <https://withpica.com/directory/llms.txt>
- Support: support@withpica.com