Examples

The reference implementation ships two conformance fixtures to copy, a composite pack and the bootstrap pack. Copy transit for a discovery pack without a login and ledger for anything with a login or an irreversible write.

All four live in the SDK repository (examples/packs/* and packs/hcp-cli). The wrap packs spawn demo binaries from their own bin/, so an installed copy carries everything it runs.

transit#

hcpx install ./examples/packs/transit --json
hcpx activate transit --json
hcpx exec transit find --json -- query=Central
hcpx exec transit plan --json -- from=A to=B
hcpx exec transit show --json -- optionId=opt-1
hcpx exec transit status --json
hcpx exec transit follow --json -- runId=run-1

{ "ok": true, "pack_id": "transit", "verb_key": "plan", "result": { "ok": true, "verb": "plan", "from": "A", "to": "B", "optionId": "opt-1" } }

It has five commands, all read and all personal, and no stimuli. follow is a read an agent may poll rather than Sense. binding.mode: public skips connect, though the Principal is still attributed, and wrap.bin is a relative path resolved against the pack directory.

ledger#

hcpx install ./examples/packs/ledger --json
hcpx activate ledger --json
hcpx exec ledger setup.status --json
hcpx exec ledger setup.apply --json
hcpx exec ledger connect --json -- provider=demo
hcpx exec ledger list --json
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit confirm=true

{ "ok": false, "pack_id": "ledger", "verb_key": "transfer", "code": "confirm_required", "error": "confirm required", … }

Its land is local, a workspace directory rather than a tenant. setup.status (read) and setup.apply (write, -y) form the HCP/1.1 installer family; both are idempotent and open no wizard on the agent path. connect is write and needs pack.connect, separate from verb.exec.write.

transfer has confirm: "always" in Policy and --confirm in cli[], so in every access mode the runtime refuses it before the bin runs until the ask is satisfied, by confirm=true after the user agreed or by a person's approval. Its payment preview makes the approval card lead with the amount and payee (Access). The pack's hcp.eval.json proves this: three reads return what they should, and transfer is refused without confirmation and runs once confirmed (hcpx eval ./examples/packs/ledger). Its Skill's anti-patterns name real mistakes: env-flag mocks, transfer without confirm and operator bins on this pack.

echo#

This composite pack has no foreign binary, so it tests a runtime's JSON path without a sandbox allow-list.

{
  "id": "echo",
  "kind": "composite",
  "cliBin": "echo-hcp",
  "binding": { "mode": "public" },
  "verbs": {
    "echo.ping": { "description": "Ping the echo pack.", "cli": ["echo-hcp", "ping"] },
    "echo.say":  { "description": "Echo a message back.", "cli": ["echo-hcp", "say", "{{message}}"] }
  }
}

hcpx exec echo echo.say --json -- message=hi

Its dotted command names (echo.ping) show how a family reads on the wire and as an in-process tool name (echo__echo_ping).

hcp-cli#

The CLI is itself a composite pack with local Binding, installed into $HCP_HOME on first run. Its 18 commands are the CLI's own lifecycle operations, among them hcp.doctor, hcp.availability, hcp.list, hcp.search, hcp.install, hcp.activate, hcp.connect, hcp.exec, hcp.lint, hcp.generate, hcp.adopt, hcp.skill, and hcp.share, and they keep the hcp. prefix whichever name you run the CLI by.

hcpx exec hcp-cli hcp.doctor --json

Because the bootstrap is a pack, there is always something to exec against, and the CLI's own Skill is discoverable like any other. Store-mutating commands (install, activate) are write, and the in-process composite defers them to the CLI process that owns the store.

hcp-example#

@harnesscontextprotocol/example is the gold pack you can install as a package. Its CLI, hcp-example, is the protocol CLI's public read lattice (doctor, list, lint, skill, catalog) with public Binding, and the package ships conformance vectors and an eval file beside the three pack files. Like the other HCP packages it is a private preview on GitHub Packages, not on public npm.

hcpx install npm:@harnesscontextprotocol/example
hcp-example doctor --json

Use transit as the domain example and hcp-cli as the bootstrap; hcp-example shows how a pack ships as an npm package ("hcp": { "pack": "." } in package.json).

Writing your own#

Copy transit or ledger, change id, cliBin, wrap.bin, the verbs map and binding.mode, update the Policy rows and the Skill, and lint. Build a pack walks through it from hcpx init, and examples/standalone/transit, the copy with the demo binary inside the pack, an MIT licence and a relative wrap.bin, is the one to extract into its own repository.

Related#

• Pack classes
• Testing
• Implementations: packs and runtimes in the wild