@shiftleftpt/sbd-toe-mcp 0.7.0 → 0.7.2

package/assets/agent-guide.md

@@ -49,13 +49,46 @@ Use when the user asks *what the manual says*, what applies, how to classify a p
 what controls or artefacts are required, or whether something is aligned with the manual.
 
 ```
-search_sbd_toe_manual       ← conceptual questions, narrative context
-map_sbd_toe_applicability   ← which chapters/controls apply to this project
-get_sbd_toe_chapter_brief   ← what a specific chapter covers (phases, artefacts, topics)
-list_sbd_toe_chapters       ← chapter discovery and navigation
-query_sbd_toe_entities      ← specific controls (CTRL-*), artefacts (ART-*), practices
+search_sbd_toe_manual            ← conceptual questions, narrative context
+map_sbd_toe_applicability        ← which chapters/controls apply to this project
+get_sbd_toe_chapter_brief        ← what a specific chapter covers (phases, artefacts, topics)
+list_sbd_toe_chapters            ← chapter discovery and navigation
+query_sbd_toe_entities           ← specific controls (CTRL-*), artefacts (ART-*), practices
+
+consult_security_requirements    ← deterministic: requirements + controls for a risk level
+                                    params: risk_level (L1|L2|L3), concerns? (string[])
+                                    returns: requirements[], controls[], active_domains[],
+                                             active_categories[], rule_trace[]
+
+resolve_entities                 ← low-level ontology filter engine
+                                    params: record_type, filters? (dot-notation), limit?
+                                    use for: enumerating roles, finding controls by domain,
+                                    listing requirements by category, exploring the ontology
 ```
 
+**Prefer `consult_security_requirements` over `search_sbd_toe_manual`** when the question
+is structured ("what requirements apply at L2?", "which controls are active for auth?").
+Use `search_sbd_toe_manual` for narrative/conceptual questions.
+
+#### Valid `concerns` values (ontology-controlled vocabulary)
+
+| concern | Categories resolved | Meaning |
+|---|---|---|
+| `auth` | AUT, ACC, SES | Authentication, access control, sessions |
+| `logging` | LOG | Audit logging, monitoring |
+| `validation` | VAL, ERR | Input validation, error handling |
+| `api` | API | API security |
+| `config` | CFG | Configuration & environment hardening |
+| `integrity` | INT | Integrity & integration |
+| `distribution` | DST | Supply chain, packaging |
+| `ide` | IDE | Development environment |
+| `requirements` | REQ | Security requirements in SDLC |
+| `architecture` | ARC | Secure architecture |
+| `iac` | IAC | Infrastructure-as-Code |
+| `encryption` | ENC | Cryptography & sensitive data |
+
+Pass concerns as exact lowercase strings from the table above.
+
 ### GUIDE mode
 Use when the user asks *how to implement, design, structure, document, or review* something
 according to the manual.
@@ -66,8 +99,45 @@ according to the manual.
 
 plan_sbd_toe_repo_governance ← list artefacts the manual identifies, grouped by chapter
 map_sbd_toe_review_scope     ← which SbD-ToE bundles to review given changed files
+
+get_guide_by_role            ← deterministic: practice assignments + user stories
+                                params: risk_level (L1|L2|L3), role? (string), phase? (string)
+                                returns: assignments[], by_role{}, by_phase{}, user stories joined
+                                use for: "what should a developer do at L2?",
+                                         "what practices apply in the design phase?"
+
+get_threat_landscape         ← deterministic: threats relevant to a risk level / concern set
+                                params: risk_level (L1|L2|L3), concerns? (string[])
+                                returns: threats[] with mitigation_confidence + mitigated_by[]
+                                NOTE: runs consult internally — do NOT call consult first
+                                use for: threat modelling context, "what threats apply to auth?"
 ```
 
+#### Valid `role` values for `get_guide_by_role`
+
+Canonical role IDs (pass exact or common alias — resolved automatically):
+
+`developer` · `appsec` · `devops` · `grc` · `qa` · `security_champion` · `software_architect`
+· `product_owner` · `scrum_master` · `team_lead` · `ciso` · `executive_management`
+· `ops` · `pentester` · `compliance` · `auditor` · `ir` · `sre`
+
+#### Interpreting tool output
+
+| Field | What to communicate |
+|---|---|
+| `rule_trace` contains `CONCERNS_FILTER_REQUIREMENTS` | Tell user scope was narrowed to the specified concerns |
+| `mitigation_confidence: "heuristic"` | Flag as inferred linkage — not structural evidence |
+| `mitigation_confidence: "derived"` | Structural chapter-match — reliable |
+| `assignments: []` / `threats: []` | Say "manual-grounded: not applicable in this scope" — do not invent |
+| `active_domains` | List the security domains active at this risk level |
+
+#### Pattern for complex answers (threat model / security plan / checklist)
+
+1. `consult_security_requirements(risk_level, concerns?)` — anchor active requirements & controls
+2. `get_threat_landscape(risk_level, concerns?)` — relevant threats + mitigating controls
+3. `get_guide_by_role(risk_level, role?, phase?)` — practices per role/phase
+4. Generate document grounded on steps 1–3 — label each claim as manual-grounded
+
 > **The MCP surfaces what the manual says — the LLM generates content.**
 > Use CONSULT tools to retrieve artefact descriptions, required sections, and controls.
 > Then generate the actual document, template, or checklist based on that grounded context.
@@ -153,7 +223,15 @@ Always distinguish between:
 | "What does chapter N cover?" | `get_sbd_toe_chapter_brief` |
 | "List all chapters" | `list_sbd_toe_chapters` |
 | "Find control / artefact / practice" | `query_sbd_toe_entities` |
-| "Generate a threat model / checklist / plan" | `search_sbd_toe_manual` or `get_sbd_toe_chapter_brief` to retrieve what the manual says it should contain → then generate it |
+| "What requirements apply at L1/L2/L3?" | `consult_security_requirements(risk_level)` |
+| "Which controls are active for auth / logging / …?" | `consult_security_requirements(risk_level, concerns=[…])` |
+| "What threats apply to this project?" | `get_threat_landscape(risk_level)` |
+| "What threats are relevant for auth / logging / …?" | `get_threat_landscape(risk_level, concerns=[…])` |
+| "What should a developer / architect / … do?" | `get_guide_by_role(risk_level, role=…)` |
+| "What practices apply in design / implement / …?" | `get_guide_by_role(risk_level, phase=…)` |
+| "What roles exist in the manual?" | `resolve_entities(record_type="role")` |
+| "List all controls in domain X" | `resolve_entities(record_type="control", filters={domain: X})` |
+| "Generate a threat model / checklist / plan" | `get_threat_landscape` + `get_guide_by_role` → then generate content |
 | "What artefacts does the manual require?" | `plan_sbd_toe_repo_governance` |
 | "Governance plan for this repo" | `plan_sbd_toe_repo_governance` → generate plan from returned artefact list |
 | "What to review given these changed files?" | `map_sbd_toe_review_scope` |
@@ -168,6 +246,7 @@ Always distinguish between:
 | `sbd://toe/agent-guide` | This document — full operational guide |
 | `sbd://toe/index-compact` | Full chapter map as JSON — fast structured lookup |
 | `sbd://toe/chapter-applicability/{riskLevel}` | Active/excluded chapters for a risk level |
+| `sbd://toe/ontology` | Full ontology YAML — domain_mapping, concerns, inference rules |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiftleftpt/sbd-toe-mcp",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "license": "Apache-2.0",
   "description": "MCP server for the SbD-ToE (Security by Design — Theory of Everything) security manual — structured tools for Claude, GitHub Copilot and other MCP clients",
   "keywords": [