saferagenticai-mcp 0.2.0__tar.gz

saferagenticai_mcp-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+# Synced runtime data — regenerated from canonical repo locations by
+# scripts/sync-data.sh before every release. Not committed; the source of
+# truth is research/mcp/suites/, research/mcp/exemplars/, and
+# assessor/src/data/criteria-v1.json.
+saferagenticai_mcp/_data/
+
+# Build artefacts
+dist/
+build/
+*.egg-info/
+__pycache__/

saferagenticai_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: saferagenticai-mcp
+Version: 0.2.0
+Summary: MCP server exposing the SaferAgenticAI safety framework (canonical criteria + Implementation Patterns layer) to coding assistants.
+Project-URL: Homepage, https://www.saferagenticai.org
+Project-URL: Repository, https://github.com/NellInc/SaferAgenticAI
+Project-URL: Documentation, https://github.com/NellInc/SaferAgenticAI/tree/main/research/mcp
+Project-URL: Issues, https://github.com/NellInc/SaferAgenticAI/issues
+Author: Nell Watson, Agentic AI Safety Community of Practice
+License: CC-BY-4.0
+Keywords: agentic-ai,ai-safety,framework,governance,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# SaferAgenticAI MCP Server
+
+Serves the SaferAgenticAI framework (canonical criteria + Implementation Patterns layer) to coding assistants via the Model Context Protocol.
+
+## Install
+
+Pick the path that matches your setup.
+
+### Option 1 — `uvx` (fastest, no manual venv)
+
+If you have [uv](https://github.com/astral-sh/uv) installed, point your MCP
+client at:
+
+```
+uvx --from git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server saferagenticai-mcp
+```
+
+uv handles isolation and caches the install. Works for single-command config
+lines in `~/.claude/mcp.json`.
+
+### Option 2 — `pipx` (isolated global install)
+
+```bash
+pipx install "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server"
+```
+
+Exposes `saferagenticai-mcp` globally; updated with `pipx upgrade saferagenticai-mcp`.
+
+### Option 3 — manual venv (works offline from a checkout)
+
+Homebrew / system Python blocks direct `pip install` under PEP 668, so if
+you've cloned the repo and want an editable install:
+
+```bash
+python3 -m venv research/mcp/.venv
+research/mcp/.venv/bin/pip install -e research/mcp/server
+```
+
+Produces `research/mcp/.venv/bin/saferagenticai-mcp`. Pattern YAML edits in
+the repo are picked up live (editable mode).
+
+### Option 4 — from PyPI (once published)
+
+```bash
+pipx install saferagenticai-mcp
+# or
+pip install --user saferagenticai-mcp
+```
+
+The package bundles `criteria-v1.json` + 214 pattern YAMLs + 4 exemplars
+inside `saferagenticai_mcp/_data/`, so a wheel install works without any
+repo checkout (verified: 891 KB wheel, 219 data entries).
+
+## Configure (Claude Code)
+
+Add to `~/.claude/mcp.json` (or your IDE's MCP config). Pick the variant that
+matches your install option.
+
+### With `uvx`
+
+```json
+{
+  "mcpServers": {
+    "saferagenticai": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server",
+        "saferagenticai-mcp"
+      ]
+    }
+  }
+}
+```
+
+### With `pipx` or manual venv
+
+```json
+{
+  "mcpServers": {
+    "saferagenticai": {
+      "command": "/absolute/path/to/saferagenticai-mcp"
+    }
+  }
+}
+```
+
+For a manual venv checkout, the absolute path is
+`<repo>/research/mcp/.venv/bin/saferagenticai-mcp`.
+
+Restart Claude Code / your IDE after editing. The server will load on the
+first tool call from your assistant.
+
+## Tools (10 total)
+
+| Tool | Input | Returns |
+|---|---|---|
+| `list_suites` | — | 16 suites with titles and subgoal counts |
+| `get_requirement` | `id`, `include_pattern` | one subgoal + its Pattern layer; falls back to fuzzy candidates if no exact match |
+| `list_requirements` | suite/type/content_type/confidence filters | filtered subgoal list with reliability signals |
+| `search_patterns` | `query`, `limit` | field-weighted ranked matches with `matched_in` and snippets |
+| `get_cross_references` | `id`, `include_inferred` | outgoing adjacencies |
+| `get_reverse_references` | `id` | incoming adjacencies (who cites this pattern) |
+| `resolve_id` | `query` | canonicalise a partial id, slug fragment, or display_id; always returns candidates |
+| `find_patterns_for_task` | `task` (natural language) | top patterns grouped by suite for a task description |
+| `list_unreviewed` | `limit` | patterns without `reviewed_by`, sorted low-confidence first |
+| `review_stats` | — | coverage %, per-suite, per-confidence; plus validation issue count |
+
+## Data sources
+
+- **Canonical framework**: `assessor/src/data/criteria-v1.json` (extracted from `framework.html`)
+- **Pattern layer**: `research/mcp/suites/<SUITE>/<pattern_id>.yaml`
+- **Exemplars**: `research/mcp/exemplars/*.yaml` (fallback for four anchor subgoals)
+
+At startup the server loads both and builds an in-memory index keyed by `pattern_id`. `display_id` lookups are also supported but may resolve to multiple subgoals (underlined variants).
+
+## Smoke test (without MCP installed)
+
+```bash
+python3 -c "
+from saferagenticai_mcp.framework_loader import load_framework
+idx = load_framework()
+print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
+"
+```
+
+## Versioning
+
+- Canonical framework: follows `criteria-v1.json`'s `version` field.
+- Pattern layer: `v1-draft` while this directory is being populated; `v1` once reviewed.
+
+## What's already built in
+
+- **Hot reload** — server stat-walks the source tree on each tool call; edits show up without restart.
+- **Load-time validation** — required fields, content_type enum, confidence enum. Invalid patterns log WARNINGs but don't fail the server.
+- **`find_patterns_for_task`** — natural-language task → top patterns grouped by suite. Replaces the need for a separate embedding index at current scale.
+- **Reverse xref index** — built at load, queried by `get_reverse_references`.
+
+## Not implemented
+
+- Auth / remote transport (stdio only).
+- Embedding-based semantic search — the field-weighted keyword scoring is sufficient at 214 patterns; embeddings would be worth it at 10× this scale.
+- `mark_reviewed` write tool — deliberately not added. Phase 3 review edits go through the YAML directly (editor + git diff = auditable); the MCP stays read-only.

saferagenticai_mcp-0.2.0/README.md

@@ -0,0 +1,143 @@
+# SaferAgenticAI MCP Server
+
+Serves the SaferAgenticAI framework (canonical criteria + Implementation Patterns layer) to coding assistants via the Model Context Protocol.
+
+## Install
+
+Pick the path that matches your setup.
+
+### Option 1 — `uvx` (fastest, no manual venv)
+
+If you have [uv](https://github.com/astral-sh/uv) installed, point your MCP
+client at:
+
+```
+uvx --from git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server saferagenticai-mcp
+```
+
+uv handles isolation and caches the install. Works for single-command config
+lines in `~/.claude/mcp.json`.
+
+### Option 2 — `pipx` (isolated global install)
+
+```bash
+pipx install "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server"
+```
+
+Exposes `saferagenticai-mcp` globally; updated with `pipx upgrade saferagenticai-mcp`.
+
+### Option 3 — manual venv (works offline from a checkout)
+
+Homebrew / system Python blocks direct `pip install` under PEP 668, so if
+you've cloned the repo and want an editable install:
+
+```bash
+python3 -m venv research/mcp/.venv
+research/mcp/.venv/bin/pip install -e research/mcp/server
+```
+
+Produces `research/mcp/.venv/bin/saferagenticai-mcp`. Pattern YAML edits in
+the repo are picked up live (editable mode).
+
+### Option 4 — from PyPI (once published)
+
+```bash
+pipx install saferagenticai-mcp
+# or
+pip install --user saferagenticai-mcp
+```
+
+The package bundles `criteria-v1.json` + 214 pattern YAMLs + 4 exemplars
+inside `saferagenticai_mcp/_data/`, so a wheel install works without any
+repo checkout (verified: 891 KB wheel, 219 data entries).
+
+## Configure (Claude Code)
+
+Add to `~/.claude/mcp.json` (or your IDE's MCP config). Pick the variant that
+matches your install option.
+
+### With `uvx`
+
+```json
+{
+  "mcpServers": {
+    "saferagenticai": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server",
+        "saferagenticai-mcp"
+      ]
+    }
+  }
+}
+```
+
+### With `pipx` or manual venv
+
+```json
+{
+  "mcpServers": {
+    "saferagenticai": {
+      "command": "/absolute/path/to/saferagenticai-mcp"
+    }
+  }
+}
+```
+
+For a manual venv checkout, the absolute path is
+`<repo>/research/mcp/.venv/bin/saferagenticai-mcp`.
+
+Restart Claude Code / your IDE after editing. The server will load on the
+first tool call from your assistant.
+
+## Tools (10 total)
+
+| Tool | Input | Returns |
+|---|---|---|
+| `list_suites` | — | 16 suites with titles and subgoal counts |
+| `get_requirement` | `id`, `include_pattern` | one subgoal + its Pattern layer; falls back to fuzzy candidates if no exact match |
+| `list_requirements` | suite/type/content_type/confidence filters | filtered subgoal list with reliability signals |
+| `search_patterns` | `query`, `limit` | field-weighted ranked matches with `matched_in` and snippets |
+| `get_cross_references` | `id`, `include_inferred` | outgoing adjacencies |
+| `get_reverse_references` | `id` | incoming adjacencies (who cites this pattern) |
+| `resolve_id` | `query` | canonicalise a partial id, slug fragment, or display_id; always returns candidates |
+| `find_patterns_for_task` | `task` (natural language) | top patterns grouped by suite for a task description |
+| `list_unreviewed` | `limit` | patterns without `reviewed_by`, sorted low-confidence first |
+| `review_stats` | — | coverage %, per-suite, per-confidence; plus validation issue count |
+
+## Data sources
+
+- **Canonical framework**: `assessor/src/data/criteria-v1.json` (extracted from `framework.html`)
+- **Pattern layer**: `research/mcp/suites/<SUITE>/<pattern_id>.yaml`
+- **Exemplars**: `research/mcp/exemplars/*.yaml` (fallback for four anchor subgoals)
+
+At startup the server loads both and builds an in-memory index keyed by `pattern_id`. `display_id` lookups are also supported but may resolve to multiple subgoals (underlined variants).
+
+## Smoke test (without MCP installed)
+
+```bash
+python3 -c "
+from saferagenticai_mcp.framework_loader import load_framework
+idx = load_framework()
+print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
+"
+```
+
+## Versioning
+
+- Canonical framework: follows `criteria-v1.json`'s `version` field.
+- Pattern layer: `v1-draft` while this directory is being populated; `v1` once reviewed.
+
+## What's already built in
+
+- **Hot reload** — server stat-walks the source tree on each tool call; edits show up without restart.
+- **Load-time validation** — required fields, content_type enum, confidence enum. Invalid patterns log WARNINGs but don't fail the server.
+- **`find_patterns_for_task`** — natural-language task → top patterns grouped by suite. Replaces the need for a separate embedding index at current scale.
+- **Reverse xref index** — built at load, queried by `get_reverse_references`.
+
+## Not implemented
+
+- Auth / remote transport (stdio only).
+- Embedding-based semantic search — the field-weighted keyword scoring is sufficient at 214 patterns; embeddings would be worth it at 10× this scale.
+- `mark_reviewed` write tool — deliberately not added. Phase 3 review edits go through the YAML directly (editor + git diff = auditable); the MCP stays read-only.

saferagenticai_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "saferagenticai-mcp"
+version = "0.2.0"
+description = "MCP server exposing the SaferAgenticAI safety framework (canonical criteria + Implementation Patterns layer) to coding assistants."
+readme = "README.md"
+license = { text = "CC-BY-4.0" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Nell Watson" },
+    { name = "Agentic AI Safety Community of Practice" },
+]
+keywords = [
+    "ai-safety",
+    "agentic-ai",
+    "mcp",
+    "model-context-protocol",
+    "framework",
+    "governance",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://www.saferagenticai.org"
+Repository = "https://github.com/NellInc/SaferAgenticAI"
+Documentation = "https://github.com/NellInc/SaferAgenticAI/tree/main/research/mcp"
+Issues = "https://github.com/NellInc/SaferAgenticAI/issues"
+
+[project.scripts]
+saferagenticai-mcp = "saferagenticai_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Editable install uses repo-relative paths (framework_loader auto-detects).
+# Wheel install bundles the runtime data under saferagenticai_mcp/_data/.
+# Populate that directory by running `scripts/sync-data.sh` before every
+# release; it copies criteria-v1.json + suites/ + exemplars/ from the
+# canonical repo locations into the package. The sync is gitignored so the
+# package-internal copy never drifts from the canonical source silently.
+
+# Hatchling respects .gitignore by default, which would drop the
+# gitignored saferagenticai_mcp/_data/ tree from the build. Listing it as
+# an "artifact" forces inclusion while keeping it out of version control.
+
+[tool.hatch.build.targets.wheel]
+packages = ["saferagenticai_mcp"]
+artifacts = ["saferagenticai_mcp/_data/**"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "saferagenticai_mcp/**",
+    "scripts/sync-data.sh",
+    "README.md",
+    "pyproject.toml",
+]
+artifacts = ["saferagenticai_mcp/_data/**"]

saferagenticai_mcp-0.2.0/saferagenticai_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""SaferAgenticAI MCP server.
+
+Exposes the two-layer framework (canonical criteria + Implementation Patterns)
+to coding assistants via the Model Context Protocol.
+"""
+
+__version__ = "0.1.0"