phi-guard-mcp 0.1.2__py3-none-any.whl

phi_guard_mcp/__init__.py

@@ -0,0 +1,32 @@
+"""Rule-based PHI detection, redaction, audit, and validation helpers."""
+
+from .benchmark import evaluate_benchmark
+from .engine import audit_text, redact_text, scan_text, validate_no_phi
+from .gate import run_gate
+from .models import (
+    AuditReport,
+    BenchmarkReport,
+    Finding,
+    GateReport,
+    RedactionResult,
+    ScanResult,
+    ValidationResult,
+)
+
+__all__ = [
+    "AuditReport",
+    "BenchmarkReport",
+    "Finding",
+    "GateReport",
+    "RedactionResult",
+    "ScanResult",
+    "ValidationResult",
+    "audit_text",
+    "evaluate_benchmark",
+    "redact_text",
+    "run_gate",
+    "scan_text",
+    "validate_no_phi",
+]
+
+__version__ = "0.1.2"

phi_guard_mcp/benchmark.py

@@ -0,0 +1,139 @@
+"""Synthetic benchmark evaluation for PHI-like identifier detection."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+
+from .engine import scan_text
+from .models import (
+    BenchmarkCase,
+    BenchmarkCaseResult,
+    BenchmarkCategoryMetrics,
+    BenchmarkReport,
+    ExpectedFinding,
+)
+
+FindingKey = tuple[str, str]
+
+
+def evaluate_benchmark(cases_dir: str | Path) -> BenchmarkReport:
+    """Evaluate detector output against synthetic benchmark cases."""
+
+    root = Path(cases_dir)
+    case_paths = sorted(root.glob("*.json"))
+    if not case_paths:
+        raise ValueError(f"No benchmark case JSON files found in {root}")
+
+    total_tp = 0
+    total_fp = 0
+    total_fn = 0
+    case_results: list[BenchmarkCaseResult] = []
+    category_counts: dict[str, Counter[str]] = defaultdict(Counter)
+
+    for case_path in case_paths:
+        case = BenchmarkCase.model_validate(json.loads(case_path.read_text(encoding="utf-8")))
+        scan = scan_text(case.text)
+
+        expected = Counter((item.category, item.text) for item in case.expected_findings)
+        detected = Counter((item.category, item.text) for item in scan.findings)
+        matched = expected & detected
+        false_positive = detected - matched
+        false_negative = expected - matched
+
+        tp = sum(matched.values())
+        fp = sum(false_positive.values())
+        fn = sum(false_negative.values())
+        total_tp += tp
+        total_fp += fp
+        total_fn += fn
+
+        _count_categories(category_counts, "expected", expected)
+        _count_categories(category_counts, "detected", detected)
+        _count_categories(category_counts, "true_positive", matched)
+        _count_categories(category_counts, "false_positive", false_positive)
+        _count_categories(category_counts, "false_negative", false_negative)
+
+        case_results.append(
+            BenchmarkCaseResult(
+                id=case.id,
+                true_positive=tp,
+                false_positive=fp,
+                false_negative=fn,
+                precision=_precision(tp, fp),
+                recall=_recall(tp, fn),
+                f1=_f1(tp, fp, fn),
+                missing=_keys_to_findings(false_negative),
+                unexpected=_keys_to_findings(false_positive),
+            )
+        )
+
+    return BenchmarkReport(
+        cases_dir=str(root),
+        total_cases=len(case_results),
+        true_positive=total_tp,
+        false_positive=total_fp,
+        false_negative=total_fn,
+        precision=_precision(total_tp, total_fp),
+        recall=_recall(total_tp, total_fn),
+        f1=_f1(total_tp, total_fp, total_fn),
+        per_category=_category_metrics(category_counts),
+        cases=case_results,
+    )
+
+
+def _count_categories(
+    category_counts: dict[str, Counter[str]],
+    metric: str,
+    values: Counter[FindingKey],
+) -> None:
+    for (category, _text), count in values.items():
+        category_counts[category][metric] += count
+
+
+def _category_metrics(category_counts: dict[str, Counter[str]]) -> dict[str, BenchmarkCategoryMetrics]:
+    metrics: dict[str, BenchmarkCategoryMetrics] = {}
+    for category in sorted(category_counts):
+        counts = category_counts[category]
+        tp = counts["true_positive"]
+        fp = counts["false_positive"]
+        fn = counts["false_negative"]
+        metrics[category] = BenchmarkCategoryMetrics(
+            expected=counts["expected"],
+            detected=counts["detected"],
+            true_positive=tp,
+            false_positive=fp,
+            false_negative=fn,
+            precision=_precision(tp, fp),
+            recall=_recall(tp, fn),
+            f1=_f1(tp, fp, fn),
+        )
+    return metrics
+
+
+def _keys_to_findings(values: Counter[FindingKey]) -> list[ExpectedFinding]:
+    findings: list[ExpectedFinding] = []
+    for category, text in sorted(values):
+        findings.extend(
+            ExpectedFinding(category=category, text=text)
+            for _ in range(values[(category, text)])
+        )
+    return findings
+
+
+def _precision(true_positive: int, false_positive: int) -> float:
+    denominator = true_positive + false_positive
+    return round(true_positive / denominator, 6) if denominator else 1.0
+
+
+def _recall(true_positive: int, false_negative: int) -> float:
+    denominator = true_positive + false_negative
+    return round(true_positive / denominator, 6) if denominator else 1.0
+
+
+def _f1(true_positive: int, false_positive: int, false_negative: int) -> float:
+    precision = _precision(true_positive, false_positive)
+    recall = _recall(true_positive, false_negative)
+    denominator = precision + recall
+    return round(2 * precision * recall / denominator, 6) if denominator else 0.0

phi_guard_mcp/cli.py

@@ -0,0 +1,124 @@
+"""Command line interface for phi-guard."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .benchmark import evaluate_benchmark
+from .engine import audit_text, redact_text, scan_text, validate_no_phi
+from .gate import run_gate
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = tuple(sys.argv[1:] if argv is None else argv)
+    parser = _build_parser()
+
+    if argv in (("--help",), ("-h",)):
+        parser.print_help()
+        return 0
+    if argv == ("--version",):
+        print(f"phi-guard {__version__}")
+        return 0
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "benchmark":
+        result = evaluate_benchmark(args.cases_dir)
+        payload = result.model_dump()
+        if args.out:
+            _write_json(args.out, payload)
+        _print_json(payload)
+        return 0
+
+    if args.command == "gate":
+        result = run_gate(args.path, config_path=args.config)
+        _print_json(result.model_dump())
+        return 0 if result.ok else 1
+
+    text = _read_text(args.file)
+
+    if args.command == "scan":
+        _print_json(scan_text(text).model_dump())
+        return 0
+
+    if args.command == "redact":
+        result = redact_text(text, mode=args.mode)
+        out_path = Path(args.out)
+        out_path.write_text(result.redacted_text, encoding="utf-8")
+        _print_json(result.model_dump())
+        return 0
+
+    if args.command == "audit":
+        _print_json(audit_text(text).model_dump())
+        return 0
+
+    if args.command == "validate":
+        result = validate_no_phi(text)
+        _print_json(result.model_dump())
+        return 0 if result.ok else 1
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="phi-guard",
+        description="Detect, redact, and audit PHI-like identifiers before text reaches AI agents.",
+    )
+    parser.add_argument("--version", action="version", version=f"phi-guard {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    scan_parser = subparsers.add_parser("scan", help="Scan a text file and output JSON findings.")
+    scan_parser.add_argument("file", help="Path to .txt, .md, .json, or '-' for stdin.")
+
+    redact_parser = subparsers.add_parser("redact", help="Redact a text file and write the result.")
+    redact_parser.add_argument("file", help="Path to .txt, .md, .json, or '-' for stdin.")
+    redact_parser.add_argument("--out", required=True, help="Path for the redacted output file.")
+    redact_parser.add_argument("--mode", choices=["placeholder"], default="placeholder")
+
+    audit_parser = subparsers.add_parser("audit", help="Output an audit JSON report.")
+    audit_parser.add_argument("file", help="Path to .txt, .md, .json, or '-' for stdin.")
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate that no PHI-like identifiers are detected.",
+    )
+    validate_parser.add_argument("file", help="Path to .txt, .md, .json, or '-' for stdin.")
+
+    benchmark_parser = subparsers.add_parser("benchmark", help="Run a synthetic benchmark.")
+    benchmark_parser.add_argument("cases_dir", help="Directory containing synthetic benchmark JSON cases.")
+    benchmark_parser.add_argument("--out", help="Optional path for the benchmark JSON report.")
+
+    gate_parser = subparsers.add_parser("gate", help="Run the repository privacy gate.")
+    gate_parser.add_argument("path", nargs="?", default=".", help="Directory or file to scan.")
+    gate_parser.add_argument("--config", help="Path to .phi-guard.toml.")
+
+    return parser
+
+
+def _read_text(file_arg: str) -> str:
+    if file_arg == "-":
+        return sys.stdin.read()
+    return Path(file_arg).read_text(encoding="utf-8")
+
+
+def _print_json(payload: object) -> None:
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def _write_json(path: str, payload: object) -> None:
+    Path(path).write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

phi_guard_mcp/engine.py

@@ -0,0 +1,275 @@
+"""Transparent rule-based PHI-like identifier detection."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+from re import Pattern
+
+from .models import (
+    SAFE_HARBOR_IDENTIFIERS,
+    AuditReport,
+    Finding,
+    PHICategory,
+    RedactionMode,
+    RedactionResult,
+    ScanResult,
+    ValidationResult,
+)
+
+
+@dataclass(frozen=True)
+class Rule:
+    rule_id: str
+    category: PHICategory
+    pattern: Pattern[str]
+    confidence: float
+    group: str | None = None
+
+
+MONTH_PATTERN = (
+    r"Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|"
+    r"Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?"
+)
+
+
+RULES: tuple[Rule, ...] = (
+    Rule(
+        rule_id="email.basic",
+        category="EMAIL",
+        pattern=re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE),
+        confidence=0.99,
+    ),
+    Rule(
+        rule_id="ssn.us",
+        category="SSN",
+        pattern=re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+        confidence=0.98,
+    ),
+    Rule(
+        rule_id="phone.us",
+        category="PHONE",
+        pattern=re.compile(r"(?<!\d)(?:\+?1[-.\s]?)?(?:\(\d{3}\)|\d{3})[-.\s]?\d{3}[-.\s]?\d{4}(?!\d)"),
+        confidence=0.92,
+    ),
+    Rule(
+        rule_id="url.http",
+        category="URL",
+        pattern=re.compile(r"\bhttps?://[^\s)>\"\]`']+", re.IGNORECASE),
+        confidence=0.97,
+    ),
+    Rule(
+        rule_id="ip.v4",
+        category="IP_ADDRESS",
+        pattern=re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"),
+        confidence=0.90,
+    ),
+    Rule(
+        rule_id="mrn.labeled",
+        category="MRN",
+        pattern=re.compile(
+            r"\b(?:MRN|Medical[ \t]+Record(?:[ \t]+Number)?|Record[ \t]+No\.?)"
+            r"[:# \t-]*(?P<phi>(?=[A-Z0-9-]*\d)[A-Z0-9][A-Z0-9-]{3,})\b",
+            re.IGNORECASE,
+        ),
+        confidence=0.96,
+        group="phi",
+    ),
+    Rule(
+        rule_id="account.labeled",
+        category="ACCOUNT_ID",
+        pattern=re.compile(
+            r"\b(?:Account|Acct|Patient[ \t]+ID|Member[ \t]+ID|Policy)"
+            r"[:# \t-]*(?P<phi>(?=[A-Z0-9-]*\d)[A-Z0-9][A-Z0-9-]{3,})\b",
+            re.IGNORECASE,
+        ),
+        confidence=0.90,
+        group="phi",
+    ),
+    Rule(
+        rule_id="date.iso_or_us",
+        category="DATE",
+        pattern=re.compile(r"\b(?:\d{4}[/-]\d{1,2}[/-]\d{1,2}|\d{1,2}[/-]\d{1,2}[/-]\d{2,4})\b"),
+        confidence=0.90,
+    ),
+    Rule(
+        rule_id="date.month_name",
+        category="DATE",
+        pattern=re.compile(rf"\b(?:{MONTH_PATTERN})\s+\d{{1,2}},\s+\d{{4}}\b", re.IGNORECASE),
+        confidence=0.90,
+    ),
+    Rule(
+        rule_id="address.street",
+        category="ADDRESS",
+        pattern=re.compile(
+            r"\b\d{1,6}\s+[A-Z][A-Za-z0-9.'-]*"
+            r"(?:\s+[A-Z][A-Za-z0-9.'-]*){0,4}\s+"
+            r"(?:St|Street|Ave|Avenue|Rd|Road|Blvd|Boulevard|Dr|Drive|Lane|Ln|Way|Court|Ct)\b",
+            re.IGNORECASE,
+        ),
+        confidence=0.82,
+    ),
+    Rule(
+        rule_id="facility.named",
+        category="MEDICAL_FACILITY",
+        pattern=re.compile(
+            r"\b[A-Z][A-Za-z&.'-]*(?:[ \t]+[A-Z][A-Za-z&.'-]*){0,4}[ \t]+"
+            r"(?:Hospital|Clinic|Medical[ \t]+Center|Health[ \t]+System|Urgent[ \t]+Care)\b"
+        ),
+        confidence=0.82,
+    ),
+    Rule(
+        rule_id="name.clinical_label",
+        category="NAME",
+        pattern=re.compile(
+            r"\b(?:Patient[ \t]+Name|Name|Patient|Provider|Physician)[:# \t-]+"
+            r"(?P<phi>[A-Z][a-z]+(?:[ \t]+[A-Z][a-z]+){1,2})\b"
+        ),
+        confidence=0.84,
+        group="phi",
+    ),
+)
+
+PLACEHOLDERS: dict[PHICategory, str] = {
+    "NAME": "[NAME]",
+    "DATE": "[DATE]",
+    "PHONE": "[PHONE]",
+    "EMAIL": "[EMAIL]",
+    "ADDRESS": "[ADDRESS]",
+    "MRN": "[MRN]",
+    "SSN": "[SSN]",
+    "URL": "[URL]",
+    "IP_ADDRESS": "[IP_ADDRESS]",
+    "MEDICAL_FACILITY": "[MEDICAL_FACILITY]",
+    "ACCOUNT_ID": "[ACCOUNT_ID]",
+}
+
+
+def scan_text(text: str) -> ScanResult:
+    """Scan plain text for PHI-like identifiers."""
+
+    findings = _deduplicate_findings(_collect_findings(text))
+    return ScanResult(
+        text_length=len(text),
+        findings=findings,
+        summary=_summarize(findings),
+    )
+
+
+def redact_text(text: str, mode: RedactionMode = "placeholder") -> RedactionResult:
+    """Redact detected PHI-like identifiers with stable placeholders."""
+
+    if mode != "placeholder":
+        raise ValueError("Only placeholder redaction is supported in the current release.")
+
+    scan = scan_text(text)
+    redacted = text
+    for finding in sorted(scan.findings, key=lambda item: item.start, reverse=True):
+        redacted = redacted[: finding.start] + PLACEHOLDERS[finding.category] + redacted[finding.end :]
+
+    return RedactionResult(
+        mode=mode,
+        redacted_text=redacted,
+        findings=scan.findings,
+        summary=scan.summary,
+    )
+
+
+def audit_text(text: str) -> AuditReport:
+    """Return an audit-oriented summary of PHI-like identifiers."""
+
+    scan = scan_text(text)
+    return AuditReport(
+        text_length=scan.text_length,
+        total_findings=len(scan.findings),
+        categories=scan.summary,
+        findings=scan.findings,
+        safe_harbor_notes=[
+            "This report can support common identifier review, but it is not a full "
+            "Safe Harbor determination.",
+            "Manual review is required before using output in a regulated environment.",
+        ],
+        limitations=[
+            "Rule-based matching can miss identifiers and can produce false positives.",
+            "This package does not provide diagnosis, treatment, triage, CDS, or HIPAA compliance.",
+            "Use synthetic or properly authorized text only.",
+        ],
+    )
+
+
+def validate_no_phi(text: str) -> ValidationResult:
+    """Validate whether text contains detected PHI-like identifiers."""
+
+    scan = scan_text(text)
+    has_phi = bool(scan.findings)
+    return ValidationResult(
+        ok=not has_phi,
+        has_phi=has_phi,
+        message="No PHI-like identifiers detected." if not has_phi else "PHI-like identifiers detected.",
+        findings=scan.findings,
+        summary=scan.summary,
+    )
+
+
+def _collect_findings(text: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for rule in RULES:
+        for match in rule.pattern.finditer(text):
+            if rule.category == "IP_ADDRESS" and not _is_valid_ipv4(match.group(0)):
+                continue
+
+            start, end = match.span(rule.group) if rule.group else match.span()
+            value = text[start:end]
+            if not value.strip():
+                continue
+
+            findings.append(
+                Finding(
+                    category=rule.category,
+                    text=value,
+                    start=start,
+                    end=end,
+                    confidence=rule.confidence,
+                    rule_id=rule.rule_id,
+                    safe_harbor_identifier=SAFE_HARBOR_IDENTIFIERS[rule.category],
+                )
+            )
+    return findings
+
+
+def _deduplicate_findings(findings: list[Finding]) -> list[Finding]:
+    ordered = sorted(
+        findings,
+        key=lambda item: (
+            item.start,
+            -(item.end - item.start),
+            -item.confidence,
+            item.category,
+            item.rule_id,
+        ),
+    )
+    selected: list[Finding] = []
+    occupied: list[tuple[int, int]] = []
+
+    for finding in ordered:
+        if any(_overlaps((finding.start, finding.end), existing) for existing in occupied):
+            continue
+        selected.append(finding)
+        occupied.append((finding.start, finding.end))
+
+    return sorted(selected, key=lambda item: (item.start, item.end, item.category, item.rule_id))
+
+
+def _overlaps(left: tuple[int, int], right: tuple[int, int]) -> bool:
+    return left[0] < right[1] and right[0] < left[1]
+
+
+def _summarize(findings: list[Finding]) -> dict[str, int]:
+    counts = Counter(finding.category for finding in findings)
+    return dict(sorted(counts.items()))
+
+
+def _is_valid_ipv4(value: str) -> bool:
+    parts = value.split(".")
+    return len(parts) == 4 and all(part.isdigit() and 0 <= int(part) <= 255 for part in parts)

phi_guard_mcp/gate.py

@@ -0,0 +1,110 @@
+"""Repository privacy gate for PHI-like identifiers."""
+
+from __future__ import annotations
+
+import fnmatch
+import tomllib
+from pathlib import Path
+
+from .engine import scan_text
+from .models import Finding, GateFileReport, GateReport
+
+DEFAULT_INCLUDE = [
+    "**/*.txt",
+    "**/*.md",
+    "**/*.py",
+    "**/*.json",
+    "pyproject.toml",
+]
+
+DEFAULT_EXCLUDE = [
+    ".git/**",
+    ".venv/**",
+    "dist/**",
+    "build/**",
+    "examples/**",
+    "tests/**",
+    "benchmarks/**",
+    "__pycache__/**",
+]
+
+
+def run_gate(root: str | Path = ".", config_path: str | Path | None = None) -> GateReport:
+    """Scan configured repository paths and fail when PHI-like identifiers are found."""
+
+    root_path = Path(root).resolve()
+    include, exclude, allow_text = _load_config(root_path, config_path)
+    files = _discover_files(root_path, include, exclude)
+
+    flagged: list[GateFileReport] = []
+    for path in files:
+        text = path.read_text(encoding="utf-8", errors="replace")
+        scan = scan_text(text)
+        findings = [finding for finding in scan.findings if finding.text not in allow_text]
+        if findings:
+            flagged.append(
+                GateFileReport(
+                    path=path.relative_to(root_path).as_posix(),
+                    findings=findings,
+                    summary=_summarize_findings(findings),
+                )
+            )
+
+    return GateReport(
+        ok=not flagged,
+        root=str(root_path),
+        scanned_files=len(files),
+        flagged_files=len(flagged),
+        findings=flagged,
+    )
+
+
+def _load_config(root: Path, config_path: str | Path | None) -> tuple[list[str], list[str], set[str]]:
+    resolved_config = _resolve_config_path(root, config_path)
+    if resolved_config is None:
+        return DEFAULT_INCLUDE, DEFAULT_EXCLUDE, set()
+
+    data = tomllib.loads(resolved_config.read_text(encoding="utf-8"))
+    gate_config = data.get("gate", {})
+    return (
+        list(gate_config.get("include", DEFAULT_INCLUDE)),
+        list(gate_config.get("exclude", DEFAULT_EXCLUDE)),
+        set(gate_config.get("allow_text", [])),
+    )
+
+
+def _resolve_config_path(root: Path, config_path: str | Path | None) -> Path | None:
+    if config_path is not None:
+        candidate = Path(config_path)
+        if not candidate.is_absolute():
+            candidate = root / candidate
+        if not candidate.exists():
+            raise FileNotFoundError(candidate)
+        return candidate
+
+    default_config = root / ".phi-guard.toml"
+    return default_config if default_config.exists() else None
+
+
+def _discover_files(root: Path, include: list[str], exclude: list[str]) -> list[Path]:
+    if root.is_file():
+        return [root]
+
+    paths: set[Path] = set()
+    for pattern in include:
+        for candidate in root.glob(pattern):
+            if candidate.is_file() and not _is_excluded(candidate.relative_to(root), exclude):
+                paths.add(candidate)
+    return sorted(paths)
+
+
+def _is_excluded(relative_path: Path, exclude: list[str]) -> bool:
+    path = relative_path.as_posix()
+    return any(fnmatch.fnmatch(path, pattern) for pattern in exclude)
+
+
+def _summarize_findings(findings: list[Finding]) -> dict[str, int]:
+    summary: dict[str, int] = {}
+    for finding in findings:
+        summary[finding.category] = summary.get(finding.category, 0) + 1
+    return dict(sorted(summary.items()))

phi_guard_mcp/models.py

@@ -0,0 +1,140 @@
+"""Stable result models shared by the Python API, CLI, and MCP server."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+PHICategory = Literal[
+    "NAME",
+    "DATE",
+    "PHONE",
+    "EMAIL",
+    "ADDRESS",
+    "MRN",
+    "SSN",
+    "URL",
+    "IP_ADDRESS",
+    "MEDICAL_FACILITY",
+    "ACCOUNT_ID",
+]
+
+RedactionMode = Literal["placeholder"]
+
+SAFE_HARBOR_IDENTIFIERS: dict[PHICategory, str] = {
+    "NAME": "Names",
+    "DATE": "All elements of dates except year",
+    "PHONE": "Telephone numbers",
+    "EMAIL": "Email addresses",
+    "ADDRESS": "Geographic subdivisions smaller than a state",
+    "MRN": "Medical record numbers",
+    "SSN": "Social Security numbers",
+    "URL": "Web Universal Resource Locators",
+    "IP_ADDRESS": "Internet Protocol addresses",
+    "ACCOUNT_ID": "Account numbers",
+    "MEDICAL_FACILITY": "Other unique identifying characteristic or code",
+}
+
+
+class Finding(BaseModel):
+    category: PHICategory
+    text: str
+    start: int = Field(ge=0)
+    end: int = Field(ge=0)
+    confidence: float = Field(ge=0.0, le=1.0)
+    rule_id: str
+    safe_harbor_identifier: str
+
+
+class ScanResult(BaseModel):
+    ok: bool = True
+    text_length: int
+    findings: list[Finding]
+    summary: dict[str, int]
+
+
+class RedactionResult(BaseModel):
+    ok: bool = True
+    mode: RedactionMode
+    redacted_text: str
+    findings: list[Finding]
+    summary: dict[str, int]
+
+
+class AuditReport(BaseModel):
+    ok: bool = True
+    text_length: int
+    total_findings: int
+    categories: dict[str, int]
+    findings: list[Finding]
+    safe_harbor_notes: list[str]
+    limitations: list[str]
+
+
+class ValidationResult(BaseModel):
+    ok: bool
+    has_phi: bool
+    message: str
+    findings: list[Finding]
+    summary: dict[str, int]
+
+
+class ExpectedFinding(BaseModel):
+    category: PHICategory
+    text: str
+
+
+class BenchmarkCase(BaseModel):
+    id: str
+    text: str
+    expected_findings: list[ExpectedFinding]
+
+
+class BenchmarkCaseResult(BaseModel):
+    id: str
+    true_positive: int = Field(ge=0)
+    false_positive: int = Field(ge=0)
+    false_negative: int = Field(ge=0)
+    precision: float = Field(ge=0.0, le=1.0)
+    recall: float = Field(ge=0.0, le=1.0)
+    f1: float = Field(ge=0.0, le=1.0)
+    missing: list[ExpectedFinding]
+    unexpected: list[ExpectedFinding]
+
+
+class BenchmarkCategoryMetrics(BaseModel):
+    expected: int = Field(ge=0)
+    detected: int = Field(ge=0)
+    true_positive: int = Field(ge=0)
+    false_positive: int = Field(ge=0)
+    false_negative: int = Field(ge=0)
+    precision: float = Field(ge=0.0, le=1.0)
+    recall: float = Field(ge=0.0, le=1.0)
+    f1: float = Field(ge=0.0, le=1.0)
+
+
+class BenchmarkReport(BaseModel):
+    ok: bool = True
+    cases_dir: str
+    total_cases: int = Field(ge=0)
+    true_positive: int = Field(ge=0)
+    false_positive: int = Field(ge=0)
+    false_negative: int = Field(ge=0)
+    precision: float = Field(ge=0.0, le=1.0)
+    recall: float = Field(ge=0.0, le=1.0)
+    f1: float = Field(ge=0.0, le=1.0)
+    per_category: dict[str, BenchmarkCategoryMetrics]
+    cases: list[BenchmarkCaseResult]
+
+
+class GateFileReport(BaseModel):
+    path: str
+    findings: list[Finding]
+    summary: dict[str, int]
+
+
+class GateReport(BaseModel):
+    ok: bool
+    root: str
+    scanned_files: int = Field(ge=0)
+    flagged_files: int = Field(ge=0)
+    findings: list[GateFileReport]

phi_guard_mcp/server.py

@@ -0,0 +1,144 @@
+"""MCP stdio server for PHI guard tools."""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib import metadata
+from typing import Any
+
+import anyio
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+from pydantic import BaseModel, Field
+
+from . import __version__
+from .engine import audit_text, redact_text, scan_text, validate_no_phi
+from .models import RedactionMode
+
+SERVER_NAME = "phi-guard-mcp"
+
+_HELP = """phi-guard-mcp
+
+MCP stdio server for detecting, redacting, and auditing PHI-like identifiers
+before medical text is sent to AI agents.
+
+Usage:
+  phi-guard-mcp            Start the MCP stdio server
+  phi-guard-mcp --help     Show this help
+  phi-guard-mcp --version  Show package version
+
+CLI:
+  phi-guard scan <file>
+  phi-guard redact <file> --out <file>
+  phi-guard audit <file>
+  phi-guard validate <file>
+"""
+
+
+class TextArgs(BaseModel):
+    text: str = Field(min_length=0, description="Plain text to inspect.")
+
+
+class RedactArgs(TextArgs):
+    mode: RedactionMode = Field(default="placeholder", description="Redaction mode.")
+
+
+async def _scan_phi(args: TextArgs) -> dict[str, Any]:
+    return scan_text(args.text).model_dump()
+
+
+async def _redact_phi(args: RedactArgs) -> dict[str, Any]:
+    return redact_text(args.text, mode=args.mode).model_dump()
+
+
+async def _audit_deidentification(args: TextArgs) -> dict[str, Any]:
+    return audit_text(args.text).model_dump()
+
+
+async def _validate_no_phi(args: TextArgs) -> dict[str, Any]:
+    return validate_no_phi(args.text).model_dump()
+
+
+TOOL_REGISTRY: dict[str, tuple[type[BaseModel], Any, str]] = {
+    "scan_phi": (
+        TextArgs,
+        _scan_phi,
+        "Detect PHI-like identifiers and return structured findings.",
+    ),
+    "redact_phi": (
+        RedactArgs,
+        _redact_phi,
+        "Detect and redact PHI-like identifiers with placeholders.",
+    ),
+    "audit_deidentification": (
+        TextArgs,
+        _audit_deidentification,
+        "Return an audit-oriented summary of PHI-like identifiers and limitations.",
+    ),
+    "validate_no_phi": (
+        TextArgs,
+        _validate_no_phi,
+        "Validate whether text has no detected PHI-like identifiers.",
+    ),
+}
+
+server = Server(SERVER_NAME)
+
+
+@server.list_tools()
+async def _list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name=name,
+            description=description,
+            inputSchema=schema_cls.model_json_schema(),
+        )
+        for name, (schema_cls, _handler, description) in TOOL_REGISTRY.items()
+    ]
+
+
+@server.call_tool()
+async def _call_tool(name: str, arguments: dict[str, Any] | None) -> list[TextContent]:
+    if name not in TOOL_REGISTRY:
+        raise ValueError(f"Unknown tool: {name}")
+
+    schema_cls, handler, _description = TOOL_REGISTRY[name]
+    parsed_args = schema_cls.model_validate(arguments or {})
+    result = await handler(parsed_args)
+    return [TextContent(type="text", text=json.dumps(result, indent=2, ensure_ascii=False))]
+
+
+async def _run_stdio_server() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def _package_version() -> str:
+    try:
+        return metadata.version("phi-guard-mcp")
+    except metadata.PackageNotFoundError:
+        return __version__
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = sys.argv[1:] if argv is None else argv
+    if args in (["--help"], ["-h"]):
+        print(_HELP)
+        return
+    if args == ["--version"]:
+        print(f"phi-guard-mcp {_package_version()}")
+        return
+    if args:
+        print(_HELP, file=sys.stderr)
+        raise SystemExit(2)
+    anyio.run(_run_stdio_server)
+
+
+if __name__ == "__main__":
+    main()

phi_guard_mcp-0.1.2.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: phi-guard-mcp
+Version: 0.1.2
+Summary: MCP server and CLI for detecting, redacting, and auditing PHI before medical text is sent to AI agents.
+Project-URL: Homepage, https://github.com/charlesree826/phi-guard-mcp
+Project-URL: Repository, https://github.com/charlesree826/phi-guard-mcp
+Project-URL: Issues, https://github.com/charlesree826/phi-guard-mcp/issues
+Author: Charles Ree
+License-Expression: MIT
+License-File: LICENSE
+Keywords: de-identification,hipaa,mcp,medical-ai,phi,privacy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.3.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: twine>=5.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# phi-guard-mcp
+
+[![CI](https://github.com/charlesree826/phi-guard-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/charlesree826/phi-guard-mcp/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/charlesree826/phi-guard-mcp.svg)](https://github.com/charlesree826/phi-guard-mcp/releases)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+[![License](https://img.shields.io/github/license/charlesree826/phi-guard-mcp.svg)](LICENSE)
+
+MCP server and CLI for detecting, redacting, and auditing PHI before medical text is sent to AI
+agents.
+
+`phi-guard-mcp` is healthcare AI safety infrastructure, not a clinical product. It is a local,
+rule-based guardrail that helps developers identify PHI-like identifiers in plain text, redact them
+with stable placeholders, and produce audit-friendly JSON before content reaches an AI agent or MCP
+workflow.
+
+Proof points for maintainers:
+
+- Synthetic benchmark with exact-match PHI finding evaluation.
+- Safe Harbor mapping audit fields for review workflows.
+- CI privacy gate that blocks PHI-like identifiers in maintained source and docs.
+- CLI, Python API, and MCP stdio tools sharing one stable JSON result model.
+
+Important scope limits:
+
+- Not for diagnosis, treatment, triage, medical advice, or medication recommendations.
+- Not a HIPAA compliance guarantee and not a substitute for legal, privacy, or security review.
+- Not an FDA-regulated clinical decision support or device software function.
+- Do not test with real patient records. The examples in this repo are synthetic.
+
+The project aligns its documentation vocabulary with HHS HIPAA de-identification concepts such as
+Safe Harbor and Expert Determination, while intentionally avoiding clinical decision support scope.
+See [HHS de-identification guidance](https://www.hhs.gov/hipaa/for-professionals/special-topics/de-identification/index.html),
+[FDA CDS guidance](https://www.fda.gov/regulatory-information/search-fda-guidance-documents/clinical-decision-support-software),
+and [FDA device software functions](https://www.fda.gov/medical-devices/digital-health-center-excellence/device-software-functions-including-mobile-medical-applications).
+
+## Install
+
+Install from the current GitHub release wheel:
+
+```bash
+python -m pip install https://github.com/charlesree826/phi-guard-mcp/releases/download/v0.1.2/phi_guard_mcp-0.1.2-py3-none-any.whl
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+PyPI publishing is configured through GitHub Actions trusted publishing and will be enabled after
+the PyPI package owner creates the matching pending publisher entry for this repository.
+
+## Quickstart
+
+Scan a synthetic note:
+
+```bash
+phi-guard scan examples/synthetic_clinical_note.txt
+```
+
+Redact PHI-like identifiers:
+
+```bash
+phi-guard redact examples/synthetic_clinical_note.txt --out /tmp/synthetic_redacted.txt
+```
+
+Audit a note:
+
+```bash
+phi-guard audit examples/synthetic_clinical_note.txt
+```
+
+Validate text before it enters an AI agent:
+
+```bash
+phi-guard validate examples/synthetic_clean_note.txt
+```
+
+Run the synthetic benchmark:
+
+```bash
+phi-guard benchmark benchmarks/synthetic/cases --out benchmarks/synthetic-report.json
+```
+
+Run the repository privacy gate:
+
+```bash
+phi-guard gate --config .phi-guard.toml
+```
+
+All CLI commands output stable JSON for automation.
+
+See [docs/demo.md](docs/demo.md) for a complete CLI and MCP transcript.
+
+## MCP Server
+
+Run the stdio MCP server:
+
+```bash
+phi-guard-mcp
+```
+
+Available tools:
+
+- `scan_phi(text)`
+- `redact_phi(text, mode="placeholder")`
+- `audit_deidentification(text)`
+- `validate_no_phi(text)`
+
+MCP tools return the same finding schema as the CLI, including `safe_harbor_identifier`.
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "phi-guard": {
+      "command": "phi-guard-mcp"
+    }
+  }
+}
+```
+
+## Python API
+
+```python
+from phi_guard_mcp import audit_text, evaluate_benchmark, redact_text, scan_text, validate_no_phi
+
+result = scan_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
+redacted = redact_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
+audit = audit_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
+validation = validate_no_phi("No identifiers are present in this synthetic note.")
+benchmark = evaluate_benchmark("benchmarks/synthetic/cases")
+```
+
+## What It Detects
+
+The first release focuses on plain text and common PHI-like identifiers:
+
+- Names in clinical label contexts
+- Dates
+- Phone numbers
+- Email addresses
+- Address-like fragments
+- Medical record numbers
+- Social Security numbers
+- URLs and IP addresses
+- Medical facility names
+- Account, member, policy, and patient ID tokens
+
+This is a deterministic heuristic engine. It favors transparent behavior and repeatable JSON over
+opaque model judgment.
+
+Safe Harbor mapping is included as a review aid only. It does not make output HIPAA compliant and
+does not replace Expert Determination or legal review.
+
+## Project Docs
+
+- [Demo](docs/demo.md)
+- [Synthetic benchmark](docs/benchmark.md)
+- [Privacy gate](docs/privacy-gate.md)
+- [Safety scope](docs/safety-scope.md)
+- [Roadmap](docs/roadmap.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Development
+
+```bash
+python -m compileall -q src tests
+python -m pytest -q
+ruff check .
+phi-guard gate --config .phi-guard.toml
+python -m build
+twine check dist/*
+```

phi_guard_mcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+phi_guard_mcp/__init__.py,sha256=g-FNIBx8ut_0T1Xbc8Uxrn3LVHev9_gawNAR21XwCF8,663
+phi_guard_mcp/benchmark.py,sha256=VtY-l-1Y-isJP6Q6aRI4AOa_wG5ODIJj8FOqdONJS3M,4742
+phi_guard_mcp/cli.py,sha256=vFNbzTLb603hissVGK9HHBjSisBBv_ctmw65OTFRn_k,4278
+phi_guard_mcp/engine.py,sha256=pO8drfyOLMKeNypznL9x4EsoIPgMRvnHX1QlUWdAM8k,8278
+phi_guard_mcp/gate.py,sha256=0lxrMS-ZAynqjk8x6bYAEHNc4aSZdj0m1JK5ZEUYi0g,3381
+phi_guard_mcp/models.py,sha256=R6bh50iyKd0ShYjdECWmoN9gA8mPYt7edyAiNFLOodU,3366
+phi_guard_mcp/server.py,sha256=DSGf8JxB3MoiFacAWOoXpK8cu-15pp33dNt3ZHV6VUA,3851
+phi_guard_mcp-0.1.2.dist-info/METADATA,sha256=BK9dOmRrMhTPPtFAwAI-cIjtfjXCMgRO7NsgZYcIyYo,6614
+phi_guard_mcp-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+phi_guard_mcp-0.1.2.dist-info/entry_points.txt,sha256=iq-dkI1N3QNpSU8Kzkd1y7VkbPSCEsP86fRpMnYGZGg,95
+phi_guard_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=cQfRJm4R05GtH02Mrl7RktEwwbhFqof8LFWfBBBMHOM,1068
+phi_guard_mcp-0.1.2.dist-info/RECORD,,

phi_guard_mcp-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

phi_guard_mcp-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+phi-guard = phi_guard_mcp.cli:main
+phi-guard-mcp = phi_guard_mcp.server:main

phi_guard_mcp-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Ree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.