harvest_repo

Call it

curl -X POST https://shpbl.com/api/public/v1/tools/harvest_repo \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer shpbl_mcp_…' \
  -d '{}'

Same handler over MCP. The free lane needs no key; a Practitioner key is what keeps a run.

Required arguments

• repo

  A GitHub repository: `owner/repo` or a URL.

Optional arguments

• key

  Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header.

• github_token

  Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key.

• cml_license

  Your perpetual copy's licence key, if you hold one. It changes retention, never depth.

• governor_key

  Operator passphrase for SHPBL's own copy. Resolved by the server; it changes only where the harvest is staged, never what is proposed.

• part

  Walk mode only: which batch to return, 1 to 2000. Batch 1 carries the protocol and the manifest; walk them all in order.

• include

  Optional path filter — only paths containing this text are harvested.

• estimate

  Return the size of the walk only — batch count, total characters, largest batch, split files — with no source.

• ledger_digest

  The ledger folded so far, handed back by a previous session so this batch continues the same run instead of starting over.

• budget

  Characters per batch — a whole number from 10,000 to 120,000. Defaults to 90000; lower it for a smaller context window, raise it only if the client can carry it. Out-of-range values are refused in plain words, not silently clamped.

• brief

  Walk mode only: skip the harvest protocol preamble on batch 1 and spend the payload on source. Use it once you already hold the method — `method_protocol` (free) returns it verbatim.

• mode

  `harvest` (the default when nothing else in the call implies a walk) is the shortcut: proposals, your decision, then the seed modules for what you approved. `walk` is the older batched ledger walk of the whole tree, which reads and classifies but composes nothing. Send it explicitly whenever you also send `part`, `ledger_digest`, `budget` or `brief`.

• grants

  Harvest mode: how many capability proposals to rank, 1 to 200. There is no fixed shallow ceiling any more — a sophisticated repository can support far more than a couple of dozen higher-order compositions, and the safeguard against a weak proposal is the approval and the Capability Contract, not a small number here.

• quality_floor

  Harvest mode: drop proposals scoring below this, 0 to 1. The score is a discovery aid for ordering what to read first — it is never evidence that a capability deserves to exist.

• novelty_threshold

  Harvest mode: how different a proposal must be from the higher-ranked ones already chosen, 0 to 1, measured on bound capabilities and title vocabulary. 0 suppresses only exact duplicates; 0.4 is firm de-duplication of near-identical variants.

• suppress_duplicates

  Harvest mode: drop proposals whose proposed composition is identical to a higher-ranked one. Default true.

• per_affordance

  Harvest mode: how many proposals one host affordance may produce, 1 to 200.

• pages

  Harvest mode: how many source pages to read for evidence, 1 to 12 (about 90,000 characters each). Proposals are cut only from what was actually read.

• approve

  Harvest mode: the grant ids the person approved. Only these are emitted. Omit it on the first call — the proposals have to be put to them first. An id nobody proposed refuses the whole set rather than emitting the rest.

• decline

  Harvest mode: the grant ids the person explicitly said no to. Only these are recorded as declined; anything they were not asked about stays open and is re-offered, never written down as a refusal.

• approved_by

  The name of the person who approved them. Required with `approve`. An agent, a model, a vendor, a policy or a default is refused, not recorded.

• host_license

  What the target repository's licence permits for this reuse, and any obligation it attaches — for example `MIT, attribution required`. Required with `approve`; SHPBL records your declaration and does not verify it.

• reuse_permitted

  Required with `approve`: the person's explicit statement that reuse of this upstream project is permitted for this composition. Absence is never a yes, and SHPBL does not infer permission from a detected licence file. Recording your declaration is not legal verification and nothing here is legal advice.

• upstream_project

  The upstream project the reuse is declared against. Defaults to the repository being harvested.

• reuse_obligations

  The obligations the licence attaches that must be preserved in the artifact — attribution, notice retention, share-alike, and so on. Recorded against every emitted artifact and carried into its manifest.

• carry_notice_files

  Licence or notice files from the host that must be copied into the artifact. Detected candidates are reported to you if you omit this.