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.
