User's Manual

Welcome

Thank you for bringing this in. SHPBL was built by one person who got tired of watching good software forget what it already knew — the same authentication guard written for the fifth time, the same retry loop, the same careful thing solved and then lost. Every caller who runs it is the reason it keeps getting sharper, and we hope you get something real out of it.

The free lane is not a demo. It runs the entire method at full depth. What it does not do is keep anything for you — that is the only difference, and we would rather say it plainly than dress it up.

What the server actually does

Four movements, always in this order:

1. Audit. The repository is surveyed as it actually is — files, bytes, languages, spine files, risk signals — before any suggestion is made.
2. Name. Every capability it holds is listed with its signature, its file, its line and its stated contract.
3. Repair. The remediation is ordered, and your agent is handed verbatim source so the diffs land on real lines.
4. Harvest. What is reusable is folded into a sealed capability ledger you can keep in your own repository.

It reads public repositories that carry a proper open-source licence, your own repositories, and private repositories you have access to. No model runs on this server: the reading and the writing are always your agent's. We supply the method, the deterministic work and the library.

Connecting it

The advertised door is https://shpbl.com/mcp. It speaks OAuth: your client sends you through a sign-in page, so no key is ever typed into the client.

{
  "mcpServers": {
    "shpbl": {
      "type": "http",
      "url": "https://shpbl.com/mcp"
    }
  }
}

Clients that can only carry a static key use the key-only door instead:

URL       https://shpbl.com/api/public/mcp
Transport Streamable HTTP
Auth      None
Header    Authorization: Bearer shpbl_mcp_YOUR_KEY

Either way, a key only matters when you want a run to persist. Everything else runs without one. The step-by-step per client lives on the access page.

Your first run

On the first message of a new conversation your agent calls welcome — the onboarding tool. It returns this manual in miniature: the greeting, the tool menu and the sentences you can say. Then say something like “audit owner/repo with SHPBL”, and it begins.

If you would rather see the shape of the job before you spend anything, ask for an estimate first. harvest_repo with estimate: true reads no source at all and tells you the batch count and the character total. It is free, and it is the honest pre-flight.

The thirteen tools

In the order a run uses them. Ten are free with no key; three are what a $39/month subscription opens.

Things you can just say

You never call a tool yourself. You talk to the agent you already use, and it picks.

• “Audit <owner>/<repo> with SHPBL and tell me plainly what it can do.”
• “Run the SHPBL gauntlet on my repo, but check in with me at every step.”
• “Estimate a SHPBL harvest first — I want to know the cost before we start.”
• “Use SHPBL to write the fix for the thing it flagged, and show me the diff.”
• “Ask SHPBL whether this problem is already solved in its library.”
• “Have SHPBL audit itself so I can see whether the method is real.”

How a run behaves

The procedure is law, not advice — and that is enforced by the server, not requested of the model. In practice you should see:

• One step per turn. Call, do, report a single readable line, then the next. Never the whole run in one breath.
• Proof of the last step. The conductor refuses step two and beyond without the digest of the step before it, so no step can be skipped quietly.
• A check-in. Every third harvest step it stops, reports, and asks whether to continue. You can ask for fewer pauses; the agent may not raise the interval on its own.
• No filling in gaps. If the supplied material does not answer something, it writes “not present” rather than guessing.
• A named deviation. There is exactly one legal reason to depart from a step — it would break a stated rule — and when that happens it stops and asks you.

What it will never touch

Some files are read by the tools you build with, so a change that looks obviously right in a diff can break your running app the moment it merges. A run reads them, writes about them, and hands the decision to you and to whatever agent already owns them: environment files, every lockfile, generated code, agent instruction files, backend wiring and migration history, build, CI and deploy config, .git, vendored output and anything holding a credential.

The write-back tool refuses those paths outright, at every tier, with no override.

Reusing your own harvest

A kept run writes a .shpbl/ folder into your repository, with a README.md that lists what was harvested. On the next run, ask your agent to read those lines and pass them back as the run's own library. It then checks each concern against what you already solved before citing anything new — your library compounds, and it stays yours. Those entries are held for that one call and never stored by SHPBL.

Keeping what a run produces

The $499 Complete Master Library is a tangible thing: a hard copy mailed to your home, licensed to you in perpetuity, and a second copy contributed to a nonprofit you choose. Borrowing the intelligence is $39 a month and cancels any time. Either way, whatever a run produces is yours outright — nothing flows back into our library, and there is no contribution loop.

Support, ideas and suggestions

Write to dev@cmpsbl.com. A real person reads it, and good ideas from callers have changed this server before. If a run found something surprising in your repository, we would like to hear about that too.

Kenneth E. Sweet Jr. · SHPBL · Abilene, Texas — made by humans who care.