# Publishing `@sequesign/mcp`

This package is developed in the Sequesign monorepo (`packages/sequesign-mcp`)
and **published from the standalone public repo [`Sequesign/mcp`](https://github.com/Sequesign/mcp)**,
where this directory's contents sit at the repo root. The monorepo copy is the
source of truth; `Sequesign/mcp` is a mirror that runs the release.

### Mirroring (monorepo → `Sequesign/mcp`)

The mirror is regenerated by the monorepo's `sync:mcp` script (the same idiom as
`sync:sdk`):

```sh
# from a monorepo checkout, with Sequesign/mcp cloned alongside it:
npm run sync:mcp -- ../mcp           # write the mirror into ../mcp
npm run sync:mcp -- ../mcp --check   # CI: report drift, exit 1 if out of sync
```

`sync:mcp` owns `src/`, `scripts/`, `server.json`, `manifest.json`, `README.md`,
`PUBLISHING.md`, `tsconfig.build.json`, `LICENSE`, `NOTICE`, the generated
`package.json` (repository rewritten to `Sequesign/mcp`, `publishConfig.access`
baked in) + `.gitignore`, and `.github/workflows/publish-mcp.yml`. It does **not**
touch `package-lock.json` or `.git`. Review, commit, and push the result in the
`Sequesign/mcp` checkout.

Channels:

| Channel | Artifact | Built by | Distributed via |
| --- | --- | --- | --- |
| **npm** | `@sequesign/mcp` (run with `npx`) | `npm run build` | npm registry |
| **MCP registry** | `server.json` metadata | committed | modelcontextprotocol.io |
| **Desktop Extension** | `sequesign.mcpb` | `npm run build:mcpb` | GitHub release asset |

The npm + registry channels are automated by `.github/workflows/publish-mcp.yml`
(in the `Sequesign/mcp` repo), triggered by pushing a `v*` tag. The registry
stores **metadata only** — the npm package is published first, and the registry
verifies the published package's `mcpName` equals `server.json`'s `name`.

## Prerequisite: the SDK must already be on npm

`@sequesign/mcp` depends on a **published** `@sequesign/sdk` (see the version in
`package.json`). The SDK is published the same way — mirrored from the monorepo
to the public [`Sequesign/sdk`](https://github.com/Sequesign/sdk) repo (via
`npm run sync:sdk`) and released by a tag-triggered workflow there. Publish the
SDK first; otherwise `npm install`/`npm ci` and the build here cannot resolve it.

## One-time account setup

1. **npm scope + auth.** Own the `@sequesign` npm scope with publish rights, then
   either add an npm **automation token** as the `NPM_TOKEN` repo secret, **or**
   configure npm **Trusted Publishing** for `Sequesign/mcp` + this workflow
   (npm ≥ 11.5.1 — no token; then delete the `NODE_AUTH_TOKEN` line). Either way
   `--provenance` attaches a signed build-provenance attestation (`id-token: write`).
2. **Registry namespace.** We use `io.github.Sequesign/sequesign`. Ownership of
   `io.github.Sequesign/*` is proven automatically by `mcp-publisher login
   github-oidc` (the repo is under the `Sequesign` org). The casing **must** be
   `Sequesign` (the registry matches the GitHub owner claim case-sensitively;
   lowercase 403s). No DNS or secret required.

## Cutting a release

0. **Refresh the lockfile** (the publish workflow runs `npm ci`, which requires a
   committed `package-lock.json` that pins the *published* `@sequesign/sdk`). With
   the SDK already live on npm:
   ```sh
   npm install            # resolves @sequesign/sdk from npm, writes package-lock.json
   git add package-lock.json
   ```
   This is only needed when dependencies (incl. the SDK version) change.
1. Bump versions so they agree (the registry rejects a `server.json` version
   that isn't the published npm version):
   - `package.json` → `version`
   - `server.json` → `version` **and** `packages[0].version`
2. Keep `mcpName` (`package.json`) == `name` (`server.json`) == `io.github.Sequesign/sequesign`.
3. Commit, tag, push:
   ```sh
   git tag v0.1.0 && git push origin v0.1.0
   ```
   The workflow builds, publishes `@sequesign/mcp` to npm with provenance, then
   registers `server.json`.

## Desktop Extension (`.mcpb`) — manual, per release

```sh
npm run build:mcpb   # prints the SHA-256
```

Upload `sequesign.mcpb` (note its SHA-256 in the release notes) as a GitHub
release asset.

`scripts/build-mcpb.mjs` works in both layouts: it resolves the
`registry/schemas/profiles` assets from the installed `@sequesign/sdk` package
(which ships them in its `files`) via `createRequire`, so in `Sequesign/mcp`
(where the SDK is an installed npm dependency) it needs only `npm ci` first — no
monorepo and no workspace SDK build. Run `npm ci && npm run build:mcpb`.