@shiftleftpt/sbd-toe-mcp
MCP server for the SbD-ToE (Security by Design — Theory of Everything) security manual — structured tools for Claude, GitHub Copilot, Cursor, Windsurf, Zed and any MCP-compatible client.
Quick Start
Zero configuration required. Works out-of-the-box with npx:
Claude Code:
claude mcp add sbd-toe -- npx -y @shiftleftpt/sbd-toe-mcp
Claude Desktop / Cursor / Windsurf — add to your MCP config:
{
"mcpServers": {
"sbd-toe": {
"command": "npx",
"args": ["-y", "@shiftleftpt/sbd-toe-mcp"]
}
}
}
VS Code + GitHub Copilot — add to .vscode/mcp.json:
{
"servers": {
"sbdToe": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@shiftleftpt/sbd-toe-mcp"]
}
}
}
For full installation instructions for all clients see docs/installation.md.
Requirements: Node.js ≥ 20.9.0
What it does
This MCP server gives any AI client structured access to the SbD-ToE security manual — a 15-chapter (00–14) framework for Security by Design — Theory of Everything.
All data is bundled locally. No Algolia, no internet connection required at runtime, no API keys.
Tools
Resources
Prompts
Grounded codegen (v0.9.0)
prepare_sbd_toe_codegen_context is the v0.9.0 entry point for code-generation, code-review and test-plan work that has to stay grounded in the SbD-ToE manual / AppSec Core v1 surface / regulatory overlay.
What it does — and what it does NOT do
- Does assemble deterministic context: activation trace, activated scope (requirements / controls / slices / regulatory obligations), AppSec Core v1 entities and relations, evidence patterns ranked by relevance, manual rastreabilidade entries, regulatory overlay entries, citation map, completeness report, LLM codegen instructions, and a
security_rationale_templatefor the agent to fill. - Does apply an auditable scope gate before returning ready context (see below).
- Does NOT generate code, edit files, or call an LLM. The tool returns context only.
- Does NOT invent identifiers, slices, requirements, controls, obligations or evidence. Anything not in
citations(the inverted legal-id list, 0.21 §3) did not surface in the deterministic resolvers. - Does NOT declare regulatory compliance. Regulatory overlay is published as an external cross-check, never as a SbD-ToE conformance signal.
Scope gate — five output states
Semantic activation
Each activation_trace entry carries source, produced, trigger, score (deterministic, in [0,1]), confidence and reason. Sources include:
explicit_concern(1.0)task_term(0.8)compound_term(0.7) — e.g. "endpoint seguro", "segredo hardcoded", "release pipeline"alias_expansion(0.6) — PT↔EN expansion (via the semantic gateway + codegen alias table)intent_keyword(0.5) — whole-word matcher; the semantic gateway's substring matcher is intentionally NOT reused for codegen activationchanged_file(0.5) — path-based heuristics overchanged_filesrisk_level(1.0) — informational, drives v0 requirement filtering
Evidence patterns are scored against the activated scope (direct control match = 1.0, active requirement = 0.7, derived control = 0.5) and capped at 25 to keep the LLM context manageable. Capped patterns surface in debug.rejected_candidates when debug=true.
How to consume the response
See prompts/sbd-toe-grounded-codegen.md (also exposed as the MCP resource sbd://toe/grounded-codegen-guide). The guide is the authoritative contract for agents — keep it open while wiring downstream LLM flows.
Limitations
- This is the MVP G2 release. The full Paper 5 experimental programme is not in scope.
- The activation lexicon is deliberately small and auditable. Probabilistic/learned scoring is not part of v0.9.0.
- The shipped overlay represents the published regulatory cross-check, not a compliance attestation surface.
Architecture
AI client (Claude / Copilot / Cursor / ...)
↓ MCP stdio
sbd-toe-mcp server
↓ local read
data/publish/ ← semantic snapshots bundled in the package
- The user asks a question in their AI client.
- The client calls a tool (e.g.
search_sbd_toe_manual). - The server reads the local snapshots in
data/publish/. - Retrieval combines documentary and structured records.
- The server returns grounded context with citations and links.
- The user's model answers based on that context.
Distribution
Primary channel: npm
npx -y @shiftleftpt/sbd-toe-mcp
Secondary channel: GitHub Releases — self-contained bundle for environments without internet access or npx. Each release publishes:
sbd-toe-mcp-vX.Y.Z-bundle.tar.gzsbd-toe-mcp-vX.Y.Z-bundle.zipsbd-toe-mcp-vX.Y.Z-bundle.sha256
Installing from a GitHub Release bundle
For environments without npm/npx:
- Download
sbd-toe-mcp-vX.Y.Z-bundle.zipfrom GitHub Releases. - Extract the archive.
- Point your MCP client to the extracted
dist/index.js:{ "command": "node", "args": ["/path/to/extracted/dist/index.js"] } - No
npm ciornpm run buildneeded — the bundle is self-contained.
Optional configuration
No environment variables are required. The following can be overridden:
Copy .env.example to .env and adjust as needed.
Relation to the SbD-ToE ecosystem
This project consumes the published bundle of the compiled SbD-ToE manual. It does not re-index the manual, does not reconcile AppSec Core directly, does not rebuild semantics and does not replace the builder.
Maintainers who want to update the bundled snapshots from a local checkout of sbd-toe-knowledge-graph:
npm run checkout:backend
To pin a formal KG release (the bundle and its .sha256 are fetched from the GitHub Release and the digest is verified before anything is written):
node scripts/sync-bundle.mjs --from-release vX.Y.Z --dry-run # see what changes
node scripts/sync-bundle.mjs --from-release vX.Y.Z
A major change of the consumer contract (for example v1.x → v2.0) is a gate: the sync stops unless the change is accepted explicitly, after the serving logic has been re-validated. The acceptance is recorded in consumed-bundle.json (contract_major_acceptance), and npm run check rejects a contract major that this code does not support.
node scripts/sync-bundle.mjs --from-release vX.Y.Z --accept-major v2 --accept-reason "<decision, who, when>"
Development
npm ci
npm run check
npm run build
npm run test
See CONTRIBUTING.md for the contribution workflow.
Security
See SECURITY.md. Vulnerabilities must be reported privately by email, never via public issue.
Licence
Split licensing:
- code and runtime:
LICENSE(Apache-2.0) - documentation and bundled snapshots:
LICENSE-DATA(CC BY-SA 4.0) - mapping and attribution note:
LICENSE-NOTE.md
