Audit and repair any public GitHub repo. Free survey; paid source, unified diffs and a pull request.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
The gate between discovery and creation, and the human checkpoint in front of it. Register one Build Intent — what you found in the host, what SHPBL already possesses, what new software becomes possible, why neither parent does it alone, and the tests that would prove it — and this returns the mechanical verdict: the invariants it passed, whether it rests on SHPBL's licensed reusable capability, whether this caller may execute the foundry, the terminal state to report, and where an authorised artifact may come to rest. THE CHECKPOINT BLOCKS: without `human_decision` carrying an attributed decision from the person, this returns the proposal in the words to say to them and nothing else — no verdict, no read, no record — and you end your turn and wait. No answer yet is NOT_YET_ASKED, never DECLINED. A decision attributed to you, to a model, to a policy or to a default is refused where the server can recognise it as such; any other name is recorded and attributed, not verified, and the authorization says which — `account` when the name matches the key's account holder, `attested` otherwise. DECLINED and NEEDS_EXPLANATION are successful outcomes: record them, build the approved siblings, and do not report a declined proposal as a failed step. Free to call at every level. Every COMPOSE, SPECIALIZE and CREATE must pass through this before any source is written; never assume authority and never write a refused artifact yourself.
The Build Intent record; every field it asks for is part of the evidence, and each field carries its own description in this schema. Required: `build_intent_id`, `proposed_artifact_id`, `proposed_name`, `display_name`, `what_it_gives_you`, `why_this_repo`, `proposed_type`, `host_repository`, `host_source_paths`, `host_behavior`, `host_problem`, `new_behavior`, `novelty_statement`, `planned_interface`. `display_name`, `what_it_gives_you` and `why_this_repo` are quality gates, not presentation: if you cannot name the software and say what new ability it gives this repository and why this repository, the proposal is refused. Tests are mandatory in effect: at least one entry across `planned_unit_tests`, `planned_behavior_tests` and `planned_integration_tests` (the aliases `planned_tests`, `unit_tests`, `behavior_tests` and `integration_tests` are folded into those three). Every path in `host_source_paths` is resolved against the real tree before anything is authorised — a path that is not there refuses the intent.
Your SHPBL Practitioner key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` header.
The licence key from a purchased Complete Master Library. Perpetual rights to that release count as execution authority on their own — no subscription needed.
Optional GitHub token (Contents: read) so the gate can read the host tree and prove the cited paths exist. Not needed if you pass `host_source_manifest`.
Governor authority. Only a Governor-resolved call may stage an artifact for SHPBL's global corpus.
The person's decision on this proposal. Step 9 is a blocking checkpoint: without an attributed human decision this tool returns the words to say and nothing else, and you end your turn there. Do not send a decision the person did not make.
The `HOST-SOURCE-MANIFEST.json` from `pin_source` or `tools/source-manifest.mjs`, as JSON text or an object. Offline runs must send this: the gate recomputes its digest and resolves every cited path against its entries. An edited or invented digest is refused.
The gate between discovery and creation, and the human checkpoint in front of it. Register one Build Intent — what you found in the host, what SHPBL already possesses, what new software becomes possible, why neither parent does it alone, and the tests that would prove it — and this returns the mechanical verdict: the invariants it passed, whether it rests on SHPBL's licensed reusable capability, whether this caller may execute the foundry, the terminal state to report, and where an authorised artifact may come to rest. THE CHECKPOINT BLOCKS: without `human_decision` carrying an attributed decision from the person, this returns the proposal in the words to say to them and nothing else — no verdict, no read, no record — and you end your turn and wait. No answer yet is NOT_YET_ASKED, never DECLINED. A decision attributed to you, to a model, to a policy or to a default is refused where the server can recognise it as such; any other name is recorded and attributed, not verified, and the authorization says which — `account` when the name matches the key's account holder, `attested` otherwise. DECLINED and NEEDS_EXPLANATION are successful outcomes: record them, build the approved siblings, and do not report a declined proposal as a failed step. Free to call at every level. Every COMPOSE, SPECIALIZE and CREATE must pass through this before any source is written; never assume authority and never write a refused artifact yourself.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL Practitioner key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` header. |
| intent* | object | The Build Intent record; every field it asks for is part of the evidence, and each field carries its own description in this schema. Required: `build_intent_id`, `proposed_artifact_id`, `proposed_name`, `display_name`, `what_it_gives_you`, `why_this_repo`, `proposed_type`, `host_repository`, `host_source_paths`, `host_behavior`, `host_problem`, `new_behavior`, `novelty_statement`, `planned_interface`. `display_name`, `what_it_gives_you` and `why_this_repo` are quality gates, not presentation: if you cannot name the software and say what new ability it gives this repository and why this repository, the proposal is refused. Tests are mandatory in effect: at least one entry across `planned_unit_tests`, `planned_behavior_tests` and `planned_integration_tests` (the aliases `planned_tests`, `unit_tests`, `behavior_tests` and `integration_tests` are folded into those three). Every path in `host_source_paths` is resolved against the real tree before anything is authorised — a path that is not there refuses the intent. |
| cml_license | string | The licence key from a purchased Complete Master Library. Perpetual rights to that release count as execution authority on their own — no subscription needed. |
| github_token | string | Optional GitHub token (Contents: read) so the gate can read the host tree and prove the cited paths exist. Not needed if you pass `host_source_manifest`. |
| governor_key | string | Governor authority. Only a Governor-resolved call may stage an artifact for SHPBL's global corpus. |
| human_decision | object | The person's decision on this proposal. Step 9 is a blocking checkpoint: without an attributed human decision this tool returns the words to say and nothing else, and you end your turn there. Do not send a decision the person did not make. |
| host_source_manifest | any | The `HOST-SOURCE-MANIFEST.json` from `pin_source` or `tools/source-manifest.mjs`, as JSON text or an object. Offline runs must send this: the gate recomputes its digest and resolves every cited path against its entries. An edited or invented digest is refused. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"intent"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL Practitioner key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` header."
},
"intent": {
"type": "object",
"properties": {
"inputs": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 60
},
"outputs": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 60
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string",
"default": "medium"
},
"unit_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"maxItems": 100,
"description": "Alias for `planned_unit_tests`."
},
"state_model": {
"type": "string",
"default": "",
"maxLength": 2000
},
"dependencies": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"default": [],
"maxItems": 60
},
"display_name": {
"type": "string",
"maxLength": 120,
"minLength": 3
},
"duplicate_of": {
"type": "string",
"maxLength": 120
},
"host_problem": {
"type": "string",
"maxLength": 4000,
"minLength": 10
},
"new_behavior": {
"type": "string",
"maxLength": 4000,
"minLength": 10
},
"claim_ceiling": {
"type": "string",
"default": "",
"maxLength": 600
},
"host_behavior": {
"type": "string",
"maxLength": 4000,
"minLength": 10
},
"planned_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"maxItems": 300,
"description": "Alias. An unclassified list of planned tests: each entry is filed as unit, behaviour or integration from its own wording, and counts towards the test invariant."
},
"proposed_name": {
"type": "string",
"maxLength": 200,
"minLength": 3
},
"proposed_type": {
"enum": [
"COMPOSE",
"SPECIALIZE",
"CREATE"
],
"type": "string"
},
"why_this_repo": {
"type": "string",
"maxLength": 2000,
"minLength": 25
},
"behavior_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"maxItems": 100,
"description": "Alias for `planned_behavior_tests`."
},
"cml_parent_ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120
},
"default": [],
"maxItems": 50
},
"license_status": {
"enum": [
"compatible",
"incompatible",
"unknown"
],
"type": "string",
"default": "unknown"
},
"opportunity_id": {
"type": "string",
"maxLength": 120
},
"behaviour_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"maxItems": 100,
"description": "Alias for `planned_behavior_tests`."
},
"build_intent_id": {
"type": "string",
"maxLength": 120,
"minLength": 3
},
"host_repository": {
"type": "string",
"maxLength": 300,
"minLength": 3
},
"host_test_paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"default": [],
"maxItems": 200
},
"parent_behavior": {
"type": "string",
"default": "",
"maxLength": 4000
},
"cml_parent_paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 50
},
"failure_semantics": {
"type": "string",
"default": "",
"maxLength": 2000
},
"host_source_paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 200,
"minItems": 1
},
"integration_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"maxItems": 100,
"description": "Alias for `planned_integration_tests`."
},
"novelty_statement": {
"type": "string",
"maxLength": 4000,
"minLength": 10
},
"planned_interface": {
"type": "string",
"maxLength": 4000,
"minLength": 3
},
"provenance_status": {
"enum": [
"complete",
"partial",
"missing"
],
"type": "string",
"default": "partial"
},
"reuse_declaration": {
"type": "object",
"required": [
"upstream_project",
"license",
"reuse_permitted",
"declared_by"
],
"properties": {
"note": {
"type": "string",
"default": "",
"maxLength": 2000
},
"license": {
"type": "string",
"maxLength": 200,
"minLength": 2,
"description": "The licence as detected in the tree or as stated by the upstream project — e.g. `MIT`, `Apache-2.0`, `AGPL-3.0`."
},
"declared_by": {
"type": "string",
"maxLength": 160,
"minLength": 2,
"description": "The person who made that declaration. A model, an agent, a policy or a default is refused."
},
"obligations": {
"type": "array",
"items": {
"type": "string",
"maxLength": 600,
"minLength": 2
},
"default": [],
"maxItems": 40,
"description": "What must be preserved: attribution, notice retention, source disclosure, licence propagation."
},
"license_files": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"default": [],
"maxItems": 40,
"description": "The licence and notice files found in the scoped tree."
},
"reuse_permitted": {
"type": "boolean",
"description": "The human declaration. False is a legal answer and stops the composition; absent is not an answer at all."
},
"upstream_project": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "The project the behaviour is being reused from, as `owner/repo` or its published name."
},
"carry_into_artifact": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"default": [],
"maxItems": 40,
"description": "The licence and notice files copied into the artifact's `LICENSES/` folder."
},
"declaration_version": {
"type": "string",
"const": "SHPBL-REUSE-DECLARATION/1.0.0",
"default": "SHPBL-REUSE-DECLARATION/1.0.0"
}
},
"additionalProperties": false
},
"what_it_gives_you": {
"type": "string",
"maxLength": 2000,
"minLength": 25
},
"parent_limitations": {
"type": "string",
"default": "",
"maxLength": 4000
},
"planned_unit_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 100,
"description": "The unit tests that would prove it. One of the three planned-test arrays must be non-empty or the gate fails."
},
"capability_contract": {
"type": "object",
"required": [
"artifact_id",
"capability_name",
"behavioral_promise",
"host_repository",
"host_behaviors",
"owned_capabilities",
"inputs",
"outputs",
"failure_behavior",
"provenance_behavior",
"claims"
],
"properties": {
"seams": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"what"
],
"properties": {
"kind": {
"enum": [
"state",
"io",
"model",
"randomness",
"network",
"filesystem",
"persistence",
"time",
"concurrency"
],
"type": "string"
},
"port": {
"type": "string",
"default": "",
"maxLength": 200
},
"what": {
"type": "string",
"maxLength": 1000,
"minLength": 5
},
"test_strategy": {
"enum": [
"real",
"recorded",
"injected-fake"
],
"type": "string",
"default": "recorded"
}
},
"additionalProperties": false
},
"default": [],
"maxItems": 40
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"statement",
"kinds",
"observable_acceptance"
],
"properties": {
"kinds": {
"type": "array",
"items": {
"enum": [
"happy-path",
"failure-path",
"boundary",
"lifecycle",
"provenance",
"integration"
],
"type": "string"
},
"maxItems": 6,
"minItems": 1
},
"claim_id": {
"type": "string",
"maxLength": 120,
"minLength": 2
},
"statement": {
"type": "string",
"maxLength": 2000,
"minLength": 10,
"description": "What the capability does, stated so it can be observed."
},
"requirement": {
"enum": [
"required",
"optional"
],
"type": "string",
"default": "required",
"description": "Optional claims may remain incomplete without blocking green — but only if they were marked optional before the build began."
},
"host_evidence": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"default": [],
"maxItems": 60
},
"lifecycle_stage": {
"type": "string",
"default": "",
"maxLength": 120
},
"owned_capabilities": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"default": [],
"maxItems": 60
},
"observable_acceptance": {
"type": "string",
"maxLength": 2000,
"minLength": 10,
"description": "How anyone else would tell whether this claim holds. Not 'it works' — the observation that decides it."
}
},
"additionalProperties": false
},
"maxItems": 200,
"minItems": 1
},
"inputs": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 80,
"minItems": 1
},
"outputs": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 80,
"minItems": 1
},
"approval_id": {
"type": "string",
"default": "",
"maxLength": 160
},
"approved_by": {
"type": "string",
"default": "",
"maxLength": 160
},
"artifact_id": {
"type": "string",
"maxLength": 160,
"minLength": 3
},
"host_behaviors": {
"type": "array",
"items": {
"type": "object",
"required": [
"behavior",
"source_paths"
],
"properties": {
"behavior": {
"type": "string",
"maxLength": 2000,
"minLength": 10,
"description": "What the host repository already does, in behavioural terms."
},
"source_lines": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"default": [],
"maxItems": 60
},
"source_paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 60,
"minItems": 1,
"description": "The host files this behaviour was read from. A behaviour with no cited path is prose, not evidence."
},
"must_preserve": {
"type": "string",
"default": "",
"maxLength": 2000,
"description": "The mechanics of this host behaviour the artifact must actually reconstruct, not merely reference."
},
"source_symbols": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"default": [],
"maxItems": 60,
"description": "The functions, classes or exports inside those files, where you can name them."
}
},
"additionalProperties": false
},
"maxItems": 60,
"minItems": 1
},
"capability_name": {
"type": "string",
"maxLength": 160,
"minLength": 3,
"description": "What a person calls it."
},
"host_repository": {
"type": "string",
"maxLength": 300,
"minLength": 3
},
"contract_version": {
"type": "string",
"const": "SHPBL-CAPABILITY-CONTRACT/1.0.0",
"default": "SHPBL-CAPABILITY-CONTRACT/1.0.0"
},
"failure_behavior": {
"type": "string",
"maxLength": 4000,
"minLength": 10,
"description": "What it does when it cannot do what it promised. Silence is not failure behaviour."
},
"lifecycle_stages": {
"type": "array",
"items": {
"type": "object",
"required": [
"stage",
"what_happens"
],
"properties": {
"stage": {
"type": "string",
"maxLength": 120,
"minLength": 2
},
"entered_from": {
"type": "string",
"default": "",
"maxLength": 120
},
"what_happens": {
"type": "string",
"maxLength": 1000,
"minLength": 5
}
},
"additionalProperties": false
},
"default": [],
"maxItems": 40
},
"behavioral_promise": {
"type": "string",
"maxLength": 4000,
"minLength": 40,
"description": "The whole promise, complete. If the promise names six lifecycle stages, all six are in scope for green."
},
"owned_capabilities": {
"type": "array",
"items": {
"type": "object",
"required": [
"capability_id"
],
"properties": {
"role": {
"enum": [
"lead",
"support"
],
"type": "string",
"default": "support"
},
"primitive": {
"type": "string",
"default": "",
"maxLength": 80
},
"unit_class": {
"enum": [
"PURE",
"SEAMED",
"PORTED",
"UNKNOWN"
],
"type": "string",
"default": "UNKNOWN"
},
"capability_id": {
"type": "string",
"maxLength": 200,
"minLength": 2
},
"what_it_contributes": {
"type": "string",
"default": "",
"maxLength": 2000
}
},
"additionalProperties": false
},
"maxItems": 60,
"minItems": 1
},
"provenance_behavior": {
"type": "string",
"maxLength": 4000,
"minLength": 10,
"description": "What lineage the artifact itself records at runtime, and what it can answer about where it came from."
},
"optional_enhancements": {
"type": "array",
"items": {
"type": "string",
"maxLength": 600,
"minLength": 3
},
"default": [],
"maxItems": 60,
"description": "Declared before the build. An enhancement invented afterwards to explain a gap is not optional, it is missing."
}
},
"additionalProperties": false
},
"planned_regressions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 100
},
"composite_parent_ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120
},
"default": [],
"maxItems": 50
},
"proposed_artifact_id": {
"type": "string",
"maxLength": 120,
"minLength": 3
},
"own_library_candidates": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"default": [],
"maxItems": 100
},
"planned_behavior_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 100,
"description": "The behaviour tests that would prove it."
},
"planned_integration_tests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"default": [],
"maxItems": 100,
"description": "The integration tests that would prove it."
},
"specialization_ancestor_ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120
},
"default": [],
"maxItems": 50
}
},
"description": "The Build Intent record; every field it asks for is part of the evidence, and each field carries its own description in this schema. Required: `build_intent_id`, `proposed_artifact_id`, `proposed_name`, `display_name`, `what_it_gives_you`, `why_this_repo`, `proposed_type`, `host_repository`, `host_source_paths`, `host_behavior`, `host_problem`, `new_behavior`, `novelty_statement`, `planned_interface`. `display_name`, `what_it_gives_you` and `why_this_repo` are quality gates, not presentation: if you cannot name the software and say what new ability it gives this repository and why this repository, the proposal is refused. Tests are mandatory in effect: at least one entry across `planned_unit_tests`, `planned_behavior_tests` and `planned_integration_tests` (the aliases `planned_tests`, `unit_tests`, `behavior_tests` and `integration_tests` are folded into those three). Every path in `host_source_paths` is resolved against the real tree before anything is authorised — a path that is not there refuses the intent.",
"additionalProperties": false
},
"cml_license": {
"type": "string",
"maxLength": 80,
"minLength": 8,
"description": "The licence key from a purchased Complete Master Library. Perpetual rights to that release count as execution authority on their own — no subscription needed."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) so the gate can read the host tree and prove the cited paths exist. Not needed if you pass `host_source_manifest`."
},
"governor_key": {
"type": "string",
"maxLength": 200,
"minLength": 8,
"description": "Governor authority. Only a Governor-resolved call may stage an artifact for SHPBL's global corpus."
},
"human_decision": {
"type": "object",
"required": [
"decision"
],
"properties": {
"reason": {
"type": "string",
"maxLength": 2000,
"description": "What they said, where they gave a reason. Recorded verbatim in BUILD-APPROVAL.json."
},
"decision": {
"type": "string",
"maxLength": 40,
"minLength": 3,
"description": "Exactly one of APPROVED, DECLINED, NEEDS_EXPLANATION, NOT_YET_ASKED or HUMAN_APPROVAL_DELEGATED. Use NOT_YET_ASKED while you have not put the proposal to the person — never DECLINED, which is their answer, not the absence of one."
},
"decided_by": {
"type": "string",
"maxLength": 120,
"description": "The person who made this decision, as they identify themselves. An agent, a model, a policy or a default is not a person and is refused."
},
"delegation_scope": {
"type": "string",
"maxLength": 600,
"description": "For HUMAN_APPROVAL_DELEGATED only: the authority the named person delegated for this run. Delegation without a scope is refused."
}
},
"description": "The person's decision on this proposal. Step 9 is a blocking checkpoint: without an attributed human decision this tool returns the words to say and nothing else, and you end your turn there. Do not send a decision the person did not make.",
"additionalProperties": false
},
"host_source_manifest": {
"anyOf": [
{
"type": "string",
"maxLength": 4000000,
"minLength": 2
},
{
"type": "object",
"additionalProperties": {}
}
],
"description": "The `HOST-SOURCE-MANIFEST.json` from `pin_source` or `tools/source-manifest.mjs`, as JSON text or an object. Offline runs must send this: the gate recomputes its digest and resolves every cited path against its entries. An edited or invented digest is refused."
}
},
"additionalProperties": false
}The harvest lane: read what a repository can already do, then offer codeless capability nominations that fuse those affordances with owned SHPBL primitive capabilities — DREAM, EVOLUTION, MEMORY, DEFENSE, BRAIN and the rest of the canonical forty, plus the S-Tier artifacts. Each nomination names host evidence, proposed capability bodies, Capability Contract slots, a test plan, and honest limits. It contains no implementation; approved materialization belongs to `harvest_repo`. Free calls return host affordances, then stop before library correlation; nominations require a Practitioner key (7-day free trial).
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| repo* | string | A GitHub repository: `owner/repo` or a URL. |
| pages | number | How many source pages to read for affordance evidence, 1 to 12 (about 90,000 characters each). More pages means more of the tree is read; the grants are cut from whatever was read. |
| grants | number | How many codeless capability nominations to return, 1 to 200. Ranked by measured fit and capability standing. |
| include | string | Optional path filter — only paths containing this text are read for affordances. |
| github_token |
Audit any GitHub repository and get back one complete result: a report (inventory, languages, spine files, risk signals), the capabilities found in it (name, signature, file and line, stated contract, dependencies), and how it stands against SHPBL's anonymous corpus of audited repositories. Works with no key: every caller gets the whole diagnosis of their own repository. A free run stops at the composition boundary — neither library is searched, so no library rows, candidates, parents or proposed architecture are returned — and nothing is retained (no pull request, no export, no recorded run). A Practitioner key (7-day free trial) continues past that boundary: both libraries searched, candidates identified and composed, and the result written back to your own repository. Whatever a run finds is yours. Follow with `fix_repo` for verbatim source and diffs, `harvest_repo` for the whole tree.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL key (shpbl_mcp_…), if you have one. Optional — without it the audit runs at the free depth. Also read from the `Authorization: Bearer …` header. |
| repo* | string | A GitHub repository: `owner/repo`, a github.com URL, or `owner/repo#branch`. |
| brief | boolean | Default true: keep the audit compact and do not include the full method protocol. Set false to include the protocol block. |
| as_free | boolean | Run at the free depth even when the key carries a paid tier, so you can see exactly what a caller without a subscription is handed. Costs no allowance and changes nothing else about the audit. |
The repair: verbatim source of the files you name — or the repository's spine when you name none — paginated for your context window, with the remediation protocol your model writes the diffs against. Free to run with no key: every file you name, paginated, plus the ordered remediation protocol — repair of what is already there. A free repair stops before either library is searched, so it proposes no composed capability, no candidates and no reuse. A Practitioner key (7-day free trial) crosses that boundary and makes the repair persist — `write_to_repo` opens the branch and the pull request.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL key (shpbl_mcp_…), if you have one. Optional — without it the repair returns one file at the free depth. Also read from the `Authorization: Bearer …` header. |
| part | integer | Which page of source to return. Page 1 reports the total and carries the protocol. |
| repo* | string | A GitHub repository: `owner/repo` or a URL. |
| brief | boolean | Skip the remediation protocol preamble and return source with a one-line reminder instead. Use it once you already hold the method — `method_protocol` (free) returns it whenever you need it again. |
| paths | array | Paths to read, from the evaluation. Omit to read the repository's spine. |
| own_library | array |
The harvest shortcut: point it at a repository you hold a licence to reuse — one you do not own and will never open a pull request against — and it goes straight to the capabilities. It reads what that repository can already do, fuses those affordances with the owned SHPBL capability library, ranks and names the results as proposals a person can read, stops for your decision on each one, and then emits the seed modules for exactly the ones you approved into your own `.shpbl/` library. That is the gauntlet's steps 8, 9 and 10 without the audit, the repair plan or the pull request. It never writes to the target repository. Pass `approve` with `approved_by` and `host_license` to collect the approved grants; pass `mode: "walk"` for the older batched ledger walk of the whole tree (`estimate`, `part`, `ledger_digest`, `budget` belong to that mode). Free calls report what the repository can do and what is offerable against it, then stop at the composition boundary; grants need a Practitioner key (7-day free trial).
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| mode | string | `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`. |
| part | number | Walk mode only: which batch to return, 1 to 2000. Batch 1 carries the protocol and the manifest; walk them all in order. |
Read one long SHPBL document, paged for a context window: `volume` (the complete text of a volume of The Strategic Master Library), `catalog_outline` (the Collective catalog's parts, component classes, agent-kit steps and verification axes), `report_template` (the branded audit report HTML to fill in), or `standing_order` (the prompt that governs a run). Requires a Practitioner key.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| part | number | 1-based page of the document, up to 60. |
| volume | string | Required for `document: volume` — the volume slug or its number, 1 through 7. |
| section | string | For `document: catalog_outline` — only parts or sections whose name contains this text. |
| document* | string | Which document to read. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"document"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"part": {
"type": "number",
"default": 1,
"description": "1-based page of the document, up to 60."
},
"volume": {
"type": "string",
"minLength": 1,
"description": "Required for `document: volume` — the volume slug or its number, 1 through 7."
},
"section": {
"type": "string",
"minLength": 2,
"description": "For `document: catalog_outline` — only parts or sections whose name contains this text."
},
"document": {
"enum": [
"volume",
"catalog_outline",
"report_template",
"standing_order"
],
"type": "string",
"description": "Which document to read."
}
},
"additionalProperties": false
}Everything published on shpbl.com in one read: the editions and their prices and licences, the seven volumes of The Strategic Master Library with their seals and read links, the public downloads with byte sizes, and the case studies of real audit runs with each verdict, and `pools` — the canonical reconciliation of every count this server quotes, so two totals are never mistaken for a contradiction and never added together. Scope it with `sections`, or pass `volume` (slug or 1-7) or `case_study` (slug) for one record in full. Free — no key, no allowance.
| Argument | Type | Description |
|---|---|---|
| volume | string | One volume in full, by slug or by number 1-7. Its complete text is a `library_document` call. |
| sections | array | Which sections to return. Omit for all of them: facts, volumes, editions, downloads, case_studies, pools. `pools` is the canonical reconciliation of every count this server quotes — read it before comparing two totals. |
| case_study | string | One case study in full, by slug — what the run got right and what it learned. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"volume": {
"type": "string",
"minLength": 1,
"description": "One volume in full, by slug or by number 1-7. Its complete text is a `library_document` call."
},
"sections": {
"type": "array",
"items": {
"enum": [
"facts",
"volumes",
"editions",
"downloads",
"case_studies",
"pools"
],
"type": "string"
},
"minItems": 1,
"description": "Which sections to return. Omit for all of them: facts, volumes, editions, downloads, case_studies, pools. `pools` is the canonical reconciliation of every count this server quotes — read it before comparing two totals."
},
"case_study": {
"type": "string",
"minLength": 1,
"description": "One case study in full, by slug — what the run got right and what it learned."
}
},
"additionalProperties": false
}Search the Collective Master Library for a capability in plain words, before writing new code. `scope: "catalog"` (Practitioner) searches the engineered components — class, what each does, API surface, line counts, verification marks. `scope: "composites"` searches capabilities earlier runs invented for one host by fusing library parts, each citing its sealed report. Pass `ids` for whole rows by component ID, with siblings and declared twins. Multi-word queries match term by term and rank; with no exact hit you get the closest rows, labelled as such.
| Argument | Type | Description |
|---|---|---|
| ids | array | Up to 20 component IDs (e.g. `STIER-S-84`, `BLD-ENG-303`) returned in full instead of a search. |
| key | string | Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| pack | string | Vault only: restrict to one vertical pack, e.g. `fintech-v1`. Substring match. |
| page | number | 1-based page of results. A page past the end is refused, never returned empty. |
| limit | number | Alias for `page_size`, 1 to 50. Given both, `page_size` wins. |
| query | string | Plain-words capability, name, ID or API symbol. Omit to page the whole pool. |
| scope |
Lists real repository names so a run never starts on a guessed one, and answers whether a repository can be written to. Pass `github_token` to see everything that token can see, or `owner` to list a public account's repositories; with neither, it lists the repositories the SHPBL GitHub App is installed on for this key — the same ones a pull request can be opened on. Pass `repo: "owner/name"` to ask about one target instead of reading the whole list. Free — costs no allowance.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL key (shpbl_mcp_…), only needed to list App-connected repositories. Optional if sent as the Authorization header. |
| page | integer | Which page of the connected-repository list to return, 1-based. Use this rather than a higher `limit` past 100; the response names the next page when there is one. |
| repo | string | Ask about one target, `owner/repo`: whether this key may open a pull request on it. Call this before offering to write. |
| limit | integer | How many repositories to return (default 30, max 100). |
| owner | string | A GitHub user or organisation to list the public repositories of, when no token is available. |
| github_token | string | A GitHub token (PAT or fine-grained) to list with. Never stored, never logged — used for this call only. |
Return the SHPBL disciplines verbatim — evaluation, remediation and harvest — plus the component classes' verification axes and the reporting style. Free and unmetered. Fetch it once, then call `fix_repo` or `harvest_repo` with `brief: true` so their payload is source rather than repeated instructions.
| Argument | Type | Description |
|---|---|---|
| stage | string | One stage only: `evaluate`, `fix` or `harvest`. Omit for all three. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"stage": {
"enum": [
"evaluate",
"fix",
"harvest"
],
"type": "string",
"description": "One stage only: `evaluate`, `fix` or `harvest`. Omit for all three."
}
},
"additionalProperties": false
}Build `HOST-SOURCE-MANIFEST.json` for canonical step 1 from a GitHub repository, online, with no clone and no download: every file's Git blob identity, the byte length, the head commit, and the `SHPBL-SOURCE-DIGEST/1` digest over the pinned tree. Write the returned JSON to your run folder as `HOST-SOURCE-MANIFEST.json` and step 1 passes the gate. Free and unmetered. If the run is offline instead, do not call this — run `node tools/source-manifest.mjs <repo-dir|repo.zip>` from the edition, which produces the same manifest from a directory or straight out of the repository ZIP. Never invent the digest or the commit.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL key, if you have one. Optional — this tool is free; a key only helps reach a private repository through a connected GitHub App install. |
| repo* | string | A GitHub repository: `owner/repo`, a github.com URL, or `owner/repo#branch`. |
| label | string | What to call the target in the manifest. Defaults to `owner/repo@branch`. |
| github_token | string | Optional GitHub token (Contents: read) for a private repository. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL key, if you have one. Optional — this tool is free; a key only helps reach a private repository through a connected GitHub App install."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo`, a github.com URL, or `owner/repo#branch`."
},
"label": {
"type": "string",
"maxLength": 200,
"description": "What to call the target in the manifest. Defaults to `owner/repo@branch`."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository."
}
},
"additionalProperties": false
}Read the canonical twelve-step run contract, or check a run bundle against it. Call it with no `files` to get the contract itself: every step's id, the artifacts it must produce, the exact condition that closes it, the terminal word to report when it does not, the instruction-precedence order, the retention rule and the two legal ends of step 12. Call it with `files` — a map of run-folder paths to their text — to get the machine verdict: which step blocked, which predicate refused and why. This is the identical implementation the offline `tools/run-gate.mjs` in every edition is bundled from, so the two cannot disagree about whether a bundle satisfies the contract. What they do not share is evidence: the offline gate checks the bundle you hand it, while a connected run can also confirm against the real repository tree that the files cited exist and say what the bundle claims. Same rules, one with a witness. Free, unmetered, read-only, stateless. Never infer a step, reorder one, or declare a run finished on your own reading — run the gate and report its word.
| Argument | Type | Description |
|---|---|---|
| files | object | The run bundle as `path: text`, relative to the run folder (for example `STEP-LEDGER.json`). Send the canonical outputs you have; the gate says what is missing. Bounded: at most 400 entries and 8 MB of text in one call, and identical diagnostics are collapsed to one line with a count rather than repeated per entry. Omit this to read the contract without evaluating anything. |
| through_step | integer | Evaluate gates through this step only. Defaults to 12. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"files": {
"type": "object",
"description": "The run bundle as `path: text`, relative to the run folder (for example `STEP-LEDGER.json`). Send the canonical outputs you have; the gate says what is missing. Bounded: at most 400 entries and 8 MB of text in one call, and identical diagnostics are collapsed to one line with a count rather than repeated per entry. Omit this to read the contract without evaluating anything.",
"additionalProperties": {
"type": "string"
}
},
"through_step": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Evaluate gates through this step only. Defaults to 12."
}
},
"additionalProperties": false
}One runner for an entire SHPBL repository audit and repair: survey, opening library comparison, evaluation, repair, the batched harvest, closing library comparison, the branded HTML report, and the write-back path. STRICT SEQUENCE: call it once with no `step` for the run card, then `step: 1`, `step: 2`, one step per turn, in order. Do the returned step, report one line to the person, then call the next. Never call two steps in one turn, never attempt the whole run at once, and never infer a finding you were not handed. From `step: 2` on you must pass `ledger_digest`; every 3 steps (adjustable with `checkpoint_interval`, max 10, only when the person asks for fewer pauses) the run pauses and you must ask the person before continuing, then pass `continue_ack: "continue"`. The final step hands over the report template and the write-back path. Your own model does all reading and writing. This full conductor requires a Practitioner key (7-day free trial). The free lane provides repository evaluation, not a partial or full gauntlet.
| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| repo* | string | A GitHub repository: `owner/repo`, a URL, or `owner/repo#branch`. |
| step | number | 0 to 2000. 0 (default) returns the run card and the plan with no source. 1…N walk the harvest batches, one per turn and in order. N+1 closes the run with the report template and the write-back path. Do not skip ahead. |
| budget | number | Characters per harvest step — a whole number from 10,000 to 120,000. Defaults to a moderate 45,000 so each step stays readable and cheap; raise it toward 90,000 only if the person asks for fewer, heavier steps. |
Runs SHPBL's own audit against the running server and returns one pass/fail/unavailable line per verification axis: the registered tool surface against the priced tier table, version agreement across the published files, subscription-register reachability, catalog reachability, repository-write authority, and billing wiring. Free, unmetered, read-only — nothing is written and no model is called. Use it to prove the server is live and consistent before starting a run, or when a tool answered in a way that looks wrong.
| Argument | Type | Description |
|---|---|---|
| verbose | boolean | Include the full tool-to-tier table and the axis definitions in the answer. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"verbose": {
"type": "boolean",
"default": false,
"description": "Include the full tool-to-tier table and the axis definitions in the answer."
}
},
"additionalProperties": false
}Report the tiers of this MCP server and — from the `key` argument or the same `Authorization` header the gated tools read — that key's tier, status and month-to-date usage. This is the authoritative answer to "am I connected, and what do I have".
| Argument | Type | Description |
|---|---|---|
| key | string | Optional SHPBL subscription key. Omit it if your client sends the key as a request header. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"key": {
"type": "string",
"maxLength": 120,
"description": "Optional SHPBL subscription key. Omit it if your client sends the key as a request header."
}
},
"additionalProperties": false
}Call this first, once, when a person connects. Returns the welcome, the full tool menu with one line per tool, the exact sentences a person can say to start a run, the support address, and the link to the user's manual. Free, unmetered, no key. Read it to the person in your own words — warmly and briefly — then ask what they would like to point it at.
| Argument | Type | Description |
|---|---|---|
| name | string | The person's first name, if you know it, so the greeting can use it. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"description": "The person's first name, if you know it, so the greeting can use it."
}
},
"additionalProperties": false
}Land finished work in a repository as a pull request: pass the files you wrote (full new contents, not diffs) and this opens a branch and a PR for the human to review and merge. Nothing is ever pushed to the default branch. Requires a SHPBL Practitioner key and the SHPBL GitHub App installed on that repository (or a one-off `github_token`). The caller chooses the repository — ask which one, or call `list_repos` first; never assume. Where things go: Harvest output belongs under `.shpbl/` in **the caller's own repository** — the person who asked for the run — and never in the repository that was harvested. Those are frequently not the same repository: a run may read a public open-source project, or a repository the caller merely has access to, and writing a harvest back into a source repository would be putting our output into somebody else's software. Sources a run may read: public repositories that carry a proper open-source license, the caller's own repositories, or private repositories the caller has access to. The server never reads a repository the caller has no right to read, and it never absorbs customer harvests back into the public library. - `.shpbl/README.md` — the index of their capability library (this tool scaffolds it when it is absent). - `.shpbl/<run-seal>/LEDGER.md` — the folded ledger for one run. - `.shpbl/<run-seal>/REPORT.html` — the branded report, if one was produced. - `.shpbl/<capability-name>/` — a capability kept as source, one folder each. - `.shpbl/COMPOSITES.md` — your own composites: capabilities this run invented for your repository by fusing parts that did nothing alone. Record each as `- <name> — <what it fuses> — <why neither part sufficed>`. These are yours and stay private; SHPBL's global composites ledger is fed only by Governor-keyed published runs, so never send yours anywhere and never expect them to appear there. If the harvested repository is not the caller's own, the harvest still lands in the caller's `.shpbl/` and the source is named in provenance. Ask the person which of their repositories is the home for their library if it is not obvious, and stop for that answer rather than guessing. Give each kept capability a one-line contract in `.shpbl/README.md`, in the form `- <name> — <path> — <contract>`. That index is what makes the library reusable: on the next run, read it and pass those entries as `own_library` to `evaluate_repo`, `fix_repo` or `run_gauntlet`, and the run will tell you which concerns you already solved before citing anything new. Those entries stay yours — they are held for the call and never stored by SHPBL. Repairs are the exception: write the repaired file at its own path, never under `.shpbl/`.
| string |
| Optional GitHub token (Contents: read) for a private repository. |
| per_affordance | number | How many nominations one affordance may produce, 1 to 200. Raise it to see alternative leads for the same host capability. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo` or a URL."
},
"pages": {
"type": "number",
"default": 4,
"description": "How many source pages to read for affordance evidence, 1 to 12 (about 90,000 characters each). More pages means more of the tree is read; the grants are cut from whatever was read."
},
"grants": {
"type": "number",
"default": 8,
"description": "How many codeless capability nominations to return, 1 to 200. Ranked by measured fit and capability standing."
},
"include": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Optional path filter — only paths containing this text are read for affordances."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository."
},
"per_affordance": {
"type": "number",
"default": 2,
"description": "How many nominations one affordance may produce, 1 to 200. Raise it to see alternative leads for the same host capability."
}
},
"additionalProperties": false
}| sections |
| array |
| Which sections to print, when you only need some of them. Omit it and the whole audit comes back, which is the right default on a first call. On a follow-up — re-reading the capability list after a repair, or checking the benchmark alone — name just what you need (for example `["capabilities"]`) rather than re-sending the whole audit into the conversation. Nothing is computed differently and nothing costs less; only the printed result is narrower, and the machine-readable payload is unchanged. |
| own_library | array | Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library. |
| github_token | string | Optional GitHub token (Contents: read) for a private repository. Not needed if the owner connected the SHPBL GitHub App to this key at https://shpbl.com/mcp-access. |
| protocol_ack | boolean | Set true to say you already hold the SHPBL protocol. The discipline, the ten meta capabilities, the hands-off list and the return shape are then not reprinted even when `brief: false` — they are unchanged and they still bind the run. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL key (shpbl_mcp_…), if you have one. Optional — without it the audit runs at the free depth. Also read from the `Authorization: Bearer …` header."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo`, a github.com URL, or `owner/repo#branch`."
},
"brief": {
"type": "boolean",
"default": true,
"description": "Default true: keep the audit compact and do not include the full method protocol. Set false to include the protocol block."
},
"as_free": {
"type": "boolean",
"default": false,
"description": "Run at the free depth even when the key carries a paid tier, so you can see exactly what a caller without a subscription is handed. Costs no allowance and changes nothing else about the audit."
},
"sections": {
"type": "array",
"items": {
"enum": [
"report",
"capabilities",
"benchmark",
"meta",
"library",
"own_library"
],
"type": "string"
},
"minItems": 1,
"description": "Which sections to print, when you only need some of them. Omit it and the whole audit comes back, which is the right default on a first call. On a follow-up — re-reading the capability list after a repair, or checking the benchmark alone — name just what you need (for example `[\"capabilities\"]`) rather than re-sending the whole audit into the conversation. Nothing is computed differently and nothing costs less; only the printed result is narrower, and the machine-readable payload is unchanged."
},
"own_library": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"api": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Exported symbols, if you kept them."
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The capability's name, as you kept it."
},
"path": {
"type": "string",
"maxLength": 400,
"description": "Where it lives in your tree, e.g. `.shpbl/retry-backoff/`."
},
"repo": {
"type": "string",
"maxLength": 300,
"description": "Which of your repositories it came from."
},
"contract": {
"type": "string",
"maxLength": 600,
"description": "The one-line contract you recorded for it."
}
},
"additionalProperties": false
},
"maxItems": 300,
"description": "Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository. Not needed if the owner connected the SHPBL GitHub App to this key at https://shpbl.com/mcp-access."
},
"protocol_ack": {
"type": "boolean",
"default": false,
"description": "Set true to say you already hold the SHPBL protocol. The discipline, the ten meta capabilities, the hands-off list and the return shape are then not reprinted even when `brief: false` — they are unchanged and they still bind the run."
}
},
"additionalProperties": false
}| Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library. |
| github_token | string | Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key. |
| protocol_ack | boolean | Set true to say you already hold the SHPBL protocol — the discipline, the ten meta capabilities, the hands-off list and the return shape are then not reprinted on page 1. Same effect as `brief` for the preamble, and the honest default for a session that has already called `method_protocol` or run an earlier stage. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL key (shpbl_mcp_…), if you have one. Optional — without it the repair returns one file at the free depth. Also read from the `Authorization: Bearer …` header."
},
"part": {
"type": "integer",
"default": 1,
"maximum": 400,
"minimum": 1,
"description": "Which page of source to return. Page 1 reports the total and carries the protocol."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo` or a URL."
},
"brief": {
"type": "boolean",
"default": false,
"description": "Skip the remediation protocol preamble and return source with a one-line reminder instead. Use it once you already hold the method — `method_protocol` (free) returns it whenever you need it again."
},
"paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 80,
"description": "Paths to read, from the evaluation. Omit to read the repository's spine."
},
"own_library": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"api": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Exported symbols, if you kept them."
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The capability's name, as you kept it."
},
"path": {
"type": "string",
"maxLength": 400,
"description": "Where it lives in your tree, e.g. `.shpbl/retry-backoff/`."
},
"repo": {
"type": "string",
"maxLength": 300,
"description": "Which of your repositories it came from."
},
"contract": {
"type": "string",
"maxLength": 600,
"description": "The one-line contract you recorded for it."
}
},
"additionalProperties": false
},
"maxItems": 300,
"description": "Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key."
},
"protocol_ack": {
"type": "boolean",
"default": false,
"description": "Set true to say you already hold the SHPBL protocol — the discipline, the ten meta capabilities, the hands-off list and the return shape are then not reprinted on page 1. Same effect as `brief` for the preamble, and the honest default for a session that has already called `method_protocol` or run an earlier stage."
}
},
"additionalProperties": false
}| repo* |
| string |
| A GitHub repository: `owner/repo` or a URL. |
| brief | boolean | 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. |
| pages | number | 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. |
| budget | number | 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. |
| grants | number | 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. |
| approve | array | 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 | array | 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. |
| include | string | Optional path filter — only paths containing this text are harvested. |
| estimate | boolean | Return the size of the walk only — batch count, total characters, largest batch, split files — with no source. |
| approved_by | string | 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. |
| cml_license | string | Your perpetual copy's licence key, if you hold one. It changes retention, never depth. |
| github_token | string | Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key. |
| governor_key | string | Operator passphrase for SHPBL's own copy. Resolved by the server; it changes only where the harvest is staged, never what is proposed. |
| host_license | string | 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. |
| ledger_digest | string | The ledger folded so far, handed back by a previous session so this batch continues the same run instead of starting over. |
| quality_floor | number | 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. |
| per_affordance | number | Harvest mode: how many proposals one host affordance may produce, 1 to 200. |
| reuse_permitted | boolean | 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 | string | The upstream project the reuse is declared against. Defaults to the repository being harvested. |
| novelty_threshold | number | 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. |
| reuse_obligations | array | 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 | array | Licence or notice files from the host that must be copied into the artifact. Detected candidates are reported to you if you omit this. |
| suppress_duplicates | boolean | Harvest mode: drop proposals whose proposed composition is identical to a higher-ranked one. Default true. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"mode": {
"enum": [
"harvest",
"walk"
],
"type": "string",
"description": "`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`."
},
"part": {
"type": "number",
"description": "Walk mode only: which batch to return, 1 to 2000. Batch 1 carries the protocol and the manifest; walk them all in order."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo` or a URL."
},
"brief": {
"type": "boolean",
"description": "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."
},
"pages": {
"type": "number",
"default": 4,
"description": "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."
},
"budget": {
"type": "number",
"description": "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."
},
"grants": {
"type": "number",
"default": 8,
"description": "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."
},
"approve": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 200,
"description": "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": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 200,
"description": "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."
},
"include": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Optional path filter — only paths containing this text are harvested."
},
"estimate": {
"type": "boolean",
"default": false,
"description": "Return the size of the walk only — batch count, total characters, largest batch, split files — with no source."
},
"approved_by": {
"type": "string",
"maxLength": 120,
"minLength": 2,
"description": "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."
},
"cml_license": {
"type": "string",
"maxLength": 200,
"minLength": 4,
"description": "Your perpetual copy's licence key, if you hold one. It changes retention, never depth."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key."
},
"governor_key": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Operator passphrase for SHPBL's own copy. Resolved by the server; it changes only where the harvest is staged, never what is proposed."
},
"host_license": {
"type": "string",
"maxLength": 400,
"minLength": 2,
"description": "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."
},
"ledger_digest": {
"type": "string",
"maxLength": 60000,
"minLength": 1,
"description": "The ledger folded so far, handed back by a previous session so this batch continues the same run instead of starting over."
},
"quality_floor": {
"type": "number",
"description": "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."
},
"per_affordance": {
"type": "number",
"default": 2,
"description": "Harvest mode: how many proposals one host affordance may produce, 1 to 200."
},
"reuse_permitted": {
"type": "boolean",
"description": "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": {
"type": "string",
"maxLength": 200,
"minLength": 2,
"description": "The upstream project the reuse is declared against. Defaults to the repository being harvested."
},
"novelty_threshold": {
"type": "number",
"description": "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."
},
"reuse_obligations": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 2
},
"maxItems": 20,
"description": "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": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 40,
"description": "Licence or notice files from the host that must be copied into the artifact. Detected candidates are reported to you if you omit this."
},
"suppress_duplicates": {
"type": "boolean",
"description": "Harvest mode: drop proposals whose proposed composition is identical to a higher-ranked one. Default true."
}
},
"additionalProperties": false
}| string |
| `catalog` — engineered components (Practitioner). `crown-jewels` — the S-Tier Vault of standalone lab-curated artifacts. `composites` — capabilities past runs invented for one host. (`vault` is no longer available; asking for it returns a pointer to these scopes.) |
| page_size | number | Rows per page, 1 to 50. Defaults to 20. |
| certified_only | boolean | Crown jewels only: return only rows whose body the certification harness executed and read clean (CERTIFIED or PROVISIONAL). This withholds the INCONCLUSIVE rows — bodies the harness could not exercise, which still exist and still ship. Leave this off (the default) to see them too; the withheld figure is reported as `certification.withheldInconclusive`. |
| component_class | string | Catalog only: restrict to one component class, e.g. `CrownJewel/S-Tier`, `Block/Engine`. Substring match. |
| include_siblings | boolean | With `ids`: also list up to 12 other component IDs in the same class, for comparison. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 2
},
"maxItems": 20,
"minItems": 1,
"description": "Up to 20 component IDs (e.g. `STIER-S-84`, `BLD-ENG-303`) returned in full instead of a search."
},
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"pack": {
"type": "string",
"minLength": 2,
"description": "Vault only: restrict to one vertical pack, e.g. `fintech-v1`. Substring match."
},
"page": {
"type": "number",
"default": 1,
"description": "1-based page of results. A page past the end is refused, never returned empty."
},
"limit": {
"type": "number",
"description": "Alias for `page_size`, 1 to 50. Given both, `page_size` wins."
},
"query": {
"type": "string",
"minLength": 2,
"description": "Plain-words capability, name, ID or API symbol. Omit to page the whole pool."
},
"scope": {
"enum": [
"catalog",
"vault",
"crown-jewels",
"composites"
],
"type": "string",
"default": "catalog",
"description": "`catalog` — engineered components (Practitioner). `crown-jewels` — the S-Tier Vault of standalone lab-curated artifacts. `composites` — capabilities past runs invented for one host. (`vault` is no longer available; asking for it returns a pointer to these scopes.)"
},
"page_size": {
"type": "number",
"description": "Rows per page, 1 to 50. Defaults to 20."
},
"certified_only": {
"type": "boolean",
"default": false,
"description": "Crown jewels only: return only rows whose body the certification harness executed and read clean (CERTIFIED or PROVISIONAL). This withholds the INCONCLUSIVE rows — bodies the harness could not exercise, which still exist and still ship. Leave this off (the default) to see them too; the withheld figure is reported as `certification.withheldInconclusive`."
},
"component_class": {
"type": "string",
"minLength": 2,
"description": "Catalog only: restrict to one component class, e.g. `CrownJewel/S-Tier`, `Block/Engine`. Substring match."
},
"include_siblings": {
"type": "boolean",
"default": false,
"description": "With `ids`: also list up to 12 other component IDs in the same class, for comparison."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL key (shpbl_mcp_…), only needed to list App-connected repositories. Optional if sent as the Authorization header."
},
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Which page of the connected-repository list to return, 1-based. Use this rather than a higher `limit` past 100; the response names the next page when there is one."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "Ask about one target, `owner/repo`: whether this key may open a pull request on it. Call this before offering to write."
},
"limit": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1,
"description": "How many repositories to return (default 30, max 100)."
},
"owner": {
"type": "string",
"minLength": 1,
"description": "A GitHub user or organisation to list the public repositories of, when no token is available."
},
"github_token": {
"type": "string",
"minLength": 1,
"description": "A GitHub token (PAT or fine-grained) to list with. Never stored, never logged — used for this call only."
}
},
"additionalProperties": false
}| include | string | Optional path filter — only paths containing this text are in scope for the whole run. |
| fold_token | string | The `fold_token` returned by the previous step, passed back verbatim. Required from `step: 2` onward: it is signed by this server and carries the previous step's number and the hash of the ledger you held then, so a step cannot be skipped and a ledger cannot be truncated or replaced. Never edit it, never write one yourself. |
| own_library | array | Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library. |
| personality | string | How the person wants to be spoken to for this run: technical, professional, friendly, light, coach, deadpan. Ask them once before step 0 and pass what they choose; it rides the run and changes wording only, never a finding, a state or a gate. Defaults to professional when they have no preference. Pass `none` to switch the voice off entirely — bare wording, no openers, no asides — which is the right setting for an automated reviewer reading the run as evidence. |
| continue_ack | string | The person's approval to continue past a checkpoint. Every 3 harvest steps this run pauses: report to the person, ask whether to continue, and only when they say yes call the next step with `continue_ack: "continue"`. Never send it without asking. |
| github_token | string | Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key. |
| protocol_ack | boolean | Set true to say this session already holds the SHPBL protocol. The discipline, the ten meta capabilities, the hands-off list and the return shapes are then not printed on step 0 or step 1 — they are unchanged and they still bind the run. Use it when you have already called `method_protocol` or run a staged tool in this session; it saves tens of thousands of characters of repetition. |
| ledger_digest | string | The ledger folded so far, one line per capability, **each line carrying the file path it came from** (for example `src/lib/queue.ts — retry with backoff`). Required from `step: 2` onward — it is the proof that you actually folded the previous step — and required on the closing step so the closing library comparison runs against what you harvested. The server checks shape as well as length: a ledger that names no paths, or is padded out around one, is refused (and not charged). |
| checkpoint_interval | number | How many harvest steps between check-ins with the person. Defaults to 3; raise it (up to 10) only when the person has asked for fewer pauses. Never set it silently — the check-ins are how the person stays in the loop. Once set it rides inside the run's `fold_token`, so passing it again on later steps is not required; if you ever start a fresh chain, set it again or the run returns to 3. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "A GitHub repository: `owner/repo`, a URL, or `owner/repo#branch`."
},
"step": {
"type": "number",
"default": 0,
"description": "0 to 2000. 0 (default) returns the run card and the plan with no source. 1…N walk the harvest batches, one per turn and in order. N+1 closes the run with the report template and the write-back path. Do not skip ahead."
},
"budget": {
"type": "number",
"description": "Characters per harvest step — a whole number from 10,000 to 120,000. Defaults to a moderate 45,000 so each step stays readable and cheap; raise it toward 90,000 only if the person asks for fewer, heavier steps."
},
"include": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Optional path filter — only paths containing this text are in scope for the whole run."
},
"fold_token": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "The `fold_token` returned by the previous step, passed back verbatim. Required from `step: 2` onward: it is signed by this server and carries the previous step's number and the hash of the ledger you held then, so a step cannot be skipped and a ledger cannot be truncated or replaced. Never edit it, never write one yourself."
},
"own_library": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"api": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Exported symbols, if you kept them."
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The capability's name, as you kept it."
},
"path": {
"type": "string",
"maxLength": 400,
"description": "Where it lives in your tree, e.g. `.shpbl/retry-backoff/`."
},
"repo": {
"type": "string",
"maxLength": 300,
"description": "Which of your repositories it came from."
},
"contract": {
"type": "string",
"maxLength": 600,
"description": "The one-line contract you recorded for it."
}
},
"additionalProperties": false
},
"maxItems": 300,
"description": "Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library."
},
"personality": {
"type": "string",
"maxLength": 40,
"description": "How the person wants to be spoken to for this run: technical, professional, friendly, light, coach, deadpan. Ask them once before step 0 and pass what they choose; it rides the run and changes wording only, never a finding, a state or a gate. Defaults to professional when they have no preference. Pass `none` to switch the voice off entirely — bare wording, no openers, no asides — which is the right setting for an automated reviewer reading the run as evidence."
},
"continue_ack": {
"type": "string",
"maxLength": 40,
"minLength": 1,
"description": "The person's approval to continue past a checkpoint. Every 3 harvest steps this run pauses: report to the person, ask whether to continue, and only when they say yes call the next step with `continue_ack: \"continue\"`. Never send it without asking."
},
"github_token": {
"type": "string",
"maxLength": 300,
"minLength": 8,
"description": "Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key."
},
"protocol_ack": {
"type": "boolean",
"default": false,
"description": "Set true to say this session already holds the SHPBL protocol. The discipline, the ten meta capabilities, the hands-off list and the return shapes are then not printed on step 0 or step 1 — they are unchanged and they still bind the run. Use it when you have already called `method_protocol` or run a staged tool in this session; it saves tens of thousands of characters of repetition."
},
"ledger_digest": {
"type": "string",
"maxLength": 60000,
"minLength": 1,
"description": "The ledger folded so far, one line per capability, **each line carrying the file path it came from** (for example `src/lib/queue.ts — retry with backoff`). Required from `step: 2` onward — it is the proof that you actually folded the previous step — and required on the closing step so the closing library comparison runs against what you harvested. The server checks shape as well as length: a ledger that names no paths, or is padded out around one, is refused (and not charged)."
},
"checkpoint_interval": {
"type": "number",
"description": "How many harvest steps between check-ins with the person. Defaults to 3; raise it (up to 10) only when the person has asked for fewer pauses. Never set it silently — the check-ins are how the person stays in the loop. Once set it rides inside the run's `fold_token`, so passing it again on later steps is not required; if you ever start a fresh chain, set it again or the run returns to 3."
}
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| key | string | Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. |
| kind | string | What this pull request lands. `harvest` means kept capabilities and a ledger: write them under `.shpbl/` and this scaffolds `.shpbl/README.md` as the index of their own capability library when it is missing. `foundry` means built software and its tests, landing under `.shpbl/` beside the index the same way a harvest does — only ever an artifact whose Build Intent `build_intent` authorised. `repair` means fixed files at their own paths, and nothing is scaffolded. |
| repo* | string | The GitHub repository to write to: `owner/repo` or a URL. |
| files* | array | Complete file contents to commit. For a repair, the whole fixed file — not a diff. |
| title* | string | Pull request title — say what the change does. |
| branch | string | Branch to write on. Defaults to one derived from `run_id`, or `shpbl/<date>-<n>`; reusing a name appends to that PR. |
| run_id | string | A stable id for this piece of work (a harvest run seal, a repair order id). Retrying with the same run_id lands on the same branch and updates the same pull request instead of opening a second one. Prefer this over `branch`. |
| summary* | string | Pull request body: the repair order, or the run seal and coverage of a harvest. Markdown. |
| base_ref | string | Branch to open against. Defaults to the repository's default branch. |
| github_token | string | One-off GitHub token with Contents and Pull requests write. Used for this call only and never stored. Omit it if the SHPBL GitHub App is installed. |
| build_authorization | array | The signed build authorizations `build_intent` returned, one per artifact this pull request lands. Required when `kind` is `foundry`: the server verifies each against its own Build Intent ledger and refuses to land an artifact it never gated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"repo",
"title",
"summary",
"files"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header."
},
"kind": {
"enum": [
"harvest",
"repair",
"foundry"
],
"type": "string",
"description": "What this pull request lands. `harvest` means kept capabilities and a ledger: write them under `.shpbl/` and this scaffolds `.shpbl/README.md` as the index of their own capability library when it is missing. `foundry` means built software and its tests, landing under `.shpbl/` beside the index the same way a harvest does — only ever an artifact whose Build Intent `build_intent` authorised. `repair` means fixed files at their own paths, and nothing is scaffolded."
},
"repo": {
"type": "string",
"maxLength": 300,
"minLength": 3,
"description": "The GitHub repository to write to: `owner/repo` or a URL."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"text"
],
"properties": {
"path": {
"type": "string",
"maxLength": 400,
"minLength": 1,
"description": "Repository-relative path."
},
"text": {
"type": "string",
"maxLength": 400000,
"description": "The complete new contents of the file."
}
},
"additionalProperties": false
},
"maxItems": 200,
"minItems": 1,
"description": "Complete file contents to commit. For a repair, the whole fixed file — not a diff."
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 3,
"description": "Pull request title — say what the change does."
},
"branch": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Branch to write on. Defaults to one derived from `run_id`, or `shpbl/<date>-<n>`; reusing a name appends to that PR."
},
"run_id": {
"type": "string",
"maxLength": 60,
"minLength": 3,
"description": "A stable id for this piece of work (a harvest run seal, a repair order id). Retrying with the same run_id lands on the same branch and updates the same pull request instead of opening a second one. Prefer this over `branch`."
},
"summary": {
"type": "string",
"maxLength": 60000,
"minLength": 3,
"description": "Pull request body: the repair order, or the run seal and coverage of a harvest. Markdown."
},
"base_ref": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Branch to open against. Defaults to the repository's default branch."
},
"github_token": {
"type": "string",
"maxLength": 500,
"minLength": 20,
"description": "One-off GitHub token with Contents and Pull requests write. Used for this call only and never stored. Omit it if the SHPBL GitHub App is installed."
},
"build_authorization": {
"type": "array",
"items": {
"type": "string",
"maxLength": 4000,
"minLength": 20
},
"maxItems": 50,
"description": "The signed build authorizations `build_intent` returned, one per artifact this pull request lands. Required when `kind` is `foundry`: the server verifies each against its own Build Intent ledger and refuses to land an artifact it never gated."
}
},
"additionalProperties": false
}