@shiftleftpt/sbd Toe

@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_template for 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 activation
• changed_file (0.5) — path-based heuristics over changed_files
• risk_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

1. The user asks a question in their AI client.
2. The client calls a tool (e.g. search_sbd_toe_manual).
3. The server reads the local snapshots in data/publish/.
4. Retrieval combines documentary and structured records.
5. The server returns grounded context with citations and links.
6. 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.gz
• sbd-toe-mcp-vX.Y.Z-bundle.zip
• sbd-toe-mcp-vX.Y.Z-bundle.sha256

Installing from a GitHub Release bundle

For environments without npm/npx:

1. Download sbd-toe-mcp-vX.Y.Z-bundle.zip from GitHub Releases.
2. Extract the archive.
3. Point your MCP client to the extracted dist/index.js:

   {
     "command": "node",
     "args": ["/path/to/extracted/dist/index.js"]
   }
   

4. No npm ci or npm run build needed — 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