# Guide: Project an Existing Server

*Implementation guide. Within the prototype, the authoritative projection rules live in [`spec/04-projection.md`](../spec/04-projection.md). This draft defines the artifact and fixtures but provides no official generator or runner.*

## Contract of this guide

Input: a running upstream MCP server and a target Class Profile.

Output: profile verbs backed by upstream tools, plus a frozen mapping and scoped coverage manifest that make the adaptation reviewable.

A projection becomes conformant only after the same official suite used for a native implementation passes against published digests. This draft can produce and test experimental capsules, but not official passing Claims.

## Step 1 — Snapshot the upstream

Call `tools/list` and save the complete upstream tool surface and schemas as exact bytes. Until canonicalization is specified, record the serialization and a locally reproducible checksum only as experimental drift evidence. Any byte change makes the draft capsule stale under [`spec/04 §1`](../spec/04-projection.md#capsule) and requires review and another fixture exercise; do not present the local checksum as a portable artifact digest.

Select a target profile only when its class honestly describes the in-domain upstream surface. Classification is a mapping decision, not evidence of conformance.

## Step 2 — Draft the mapping

For every Core verb, identify:

- the upstream tool or tools called;
- argument translation;
- result translation back into profile objects;
- default handling;
- error translation; and
- the maximum risk of the composed path.

Three disciplines govern the draft:

1. **Advertise the exact profile surface.** Copy the profile's input schema and summary; keep translation private.
2. **Multi-call composition is allowed.** A projection may compute a correct result, such as free time, from several upstream calls.
3. **Stop when Core cannot be backed honestly.** Add local machinery such as tombstones when that preserves the contract; otherwise do not claim the baseline.

A model may draft this mapping once. A human or deterministic review process must then approve and freeze it. Regenerating a mapping per request is prohibited because inference drift destroys the meaning of earlier evidence.

## Step 3 — Freeze the capsule

The binding capsule records:

- target baseline and facet identifiers;
- target artifact digests once published;
- upstream identity, exact snapshot, serialization, and experimental checksum;
- per-verb transformations;
- risk propagation;
- scoped coverage and loss;
- generator and review provenance; and
- a receipt only after an official passing run exists.

Credentials, account state, device state, and local defaults do not belong in the capsule. While artifacts stay undigested, reuse requires byte-identical saved upstream snapshots and the same selected profile commit. Published reuse will key on canonical digests once that procedure exists.

## Step 4 — Account for scoped coverage

Coverage applies to every upstream tool and parameter **inside the mapped class domain**, not the vendor's entire universe. Give each in-domain item exactly one disposition:

- `mapped` — faithfully represented by a profile member;
- `approximated` — represented with an explicit, user-readable loss statement;
- `raw_only` — available only through separately permissioned passthrough; or
- `unmapped` — unavailable through the projection.

Aggregate plainly unrelated tools in `out_of_scope` with a count and short explanation. Do not bury load-bearing pagination, identity, or authorization inputs there. Declared loss is reviewable; silent loss invalidates the projection.

## Step 5 — Decide on passthrough

Passthrough is optional, disabled by default, and separately permissioned. Where offered, expose selected tools as `passthrough.<upstream_tool>` with their schemas unmodified. Profile verbs never quietly route through different passthrough semantics.

## Step 6 — Exercise the profile behavior

Run every applicable profile fixture through the projected MCP surface using an independent harness. Typical failures reveal real adaptation bugs:

- cancellation becomes hard deletion → add a projection-side tombstone layer;
- a patch clobbers omitted fields → merge before writing upstream;
- an unknown ID becomes an empty success → translate it to `-32602`; or
- a composed call weakens risk metadata → propagate the riskiest possible upstream effect.

Until the official runner exists, publish these results only as reproducible implementation feedback.

## Step 7 — Report the capsule

Report exact inputs: profile draft commit, saved upstream snapshot and checksum procedure, attempted suites, coverage totals, and known loss. Summarize coverage in user terms, for example: “14 in-domain features mapped, 3 approximated with disclosed limits, 2 raw-only, 1 unavailable.” Do not attach a receipt or make a conformance Claim without an official passing run against published digests.