phi-guard-mcp 0.1.2__tar.gz

phi_guard_mcp-0.1.2/.github/ISSUE_TEMPLATE/benchmark_case.md

@@ -0,0 +1,34 @@
+---
+name: Benchmark case
+about: Propose a synthetic benchmark fixture or detector edge case
+title: "Benchmark: "
+labels: benchmark
+assignees: ""
+---
+
+## Synthetic Input
+
+Use synthetic data only.
+
+```text
+Paste a minimal synthetic clinical-style note here.
+```
+
+## Expected Findings
+
+List exact category and text pairs.
+
+```json
+[
+  {"category": "PHONE", "text": "555-010-2040"}
+]
+```
+
+## Why This Matters
+
+Explain the detector behavior this case should exercise.
+
+## Privacy Check
+
+- [ ] This benchmark proposal contains synthetic data only.
+- [ ] This benchmark proposal does not include real PHI or private identifiers.

phi_guard_mcp-0.1.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Report a reproducible problem using synthetic data only
+title: "Bug: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the problem.
+
+## Reproduction
+
+Use synthetic data only.
+
+```text
+Paste a minimal synthetic input here.
+```
+
+Command or API call:
+
+```bash
+phi-guard scan example.txt
+```
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Environment
+
+- OS:
+- Python version:
+- `phi-guard-mcp` version:
+
+## Privacy Check
+
+- [ ] This report contains synthetic data only.
+- [ ] This report does not include real PHI, credentials, private emails, private IPs, or account tokens.

phi_guard_mcp-0.1.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest a scoped privacy, redaction, benchmark, CLI, or MCP improvement
+title: "Feature: "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+What should be added or improved?
+
+## Use Case
+
+Describe the developer or maintainer workflow this supports.
+
+## Proposed Behavior
+
+What should the project do?
+
+## Safety Boundary
+
+- [ ] This does not add diagnosis, treatment, triage, prognosis, medication, or clinical risk scoring.
+- [ ] This does not claim HIPAA compliance, legal sufficiency, or Expert Determination.
+- [ ] This can be developed and tested with synthetic data only.

phi_guard_mcp-0.1.2/.github/ISSUE_TEMPLATE/security_or_privacy.md

@@ -0,0 +1,34 @@
+---
+name: Security or privacy concern
+about: Report a security or privacy issue without exposing sensitive data
+title: "Security/privacy: "
+labels: security, privacy
+assignees: ""
+---
+
+## Before Posting
+
+Do not include real patient data, secrets, credentials, private infrastructure details, or exploit
+details that would create risk if public.
+
+If synthetic data is enough to explain the issue, continue below. If sensitive details are required,
+contact the maintainer through GitHub and request a private reporting path first.
+
+## Summary
+
+Describe the concern using synthetic examples only.
+
+## Impact
+
+What could go wrong?
+
+## Synthetic Reproduction
+
+```text
+Use synthetic data only.
+```
+
+## Privacy Check
+
+- [ ] This report uses synthetic data only.
+- [ ] This report does not include real PHI, credentials, private emails, private IPs, or account tokens.

phi_guard_mcp-0.1.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+Describe the change and why it is needed.
+
+## Impact
+
+- [ ] PHI detection rules
+- [ ] Redaction output
+- [ ] Audit or validation output
+- [ ] CLI behavior
+- [ ] MCP behavior
+- [ ] Documentation only
+
+## Tests
+
+List the commands or checks run.
+
+```bash
+python -m pytest -q
+ruff check .
+phi-guard gate --config .phi-guard.toml
+```
+
+## Privacy and Safety
+
+- [ ] This PR uses synthetic data only.
+- [ ] This PR does not include real PHI, credentials, private emails, private IPs, or account tokens.
+- [ ] This PR does not add diagnosis, treatment, triage, medication, clinical risk scoring, or HIPAA compliance claims.

phi_guard_mcp-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Compile
+        run: python -m compileall -q src tests
+
+      - name: Tests
+        run: python -m pytest -q
+
+      - name: Privacy gate
+        run: phi-guard gate --config .phi-guard.toml
+
+      - name: Build
+        run: python -m build
+
+      - name: Twine check
+        run: twine check dist/*

phi_guard_mcp-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish distribution
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/phi-guard-mcp/
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: twine check dist/*
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

phi_guard_mcp-0.1.2/.gitignore

@@ -0,0 +1,20 @@
+.DS_Store
+.env
+.venv/
+venv/
+
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+build/
+dist/
+*.egg-info/
+
+.idea/
+.vscode/

phi_guard_mcp-0.1.2/.phi-guard.toml

@@ -0,0 +1,38 @@
+[gate]
+include = [
+  "README.md",
+  "docs/**/*.md",
+  "src/**/*.py",
+  "pyproject.toml",
+]
+exclude = [
+  ".git/**",
+  ".venv/**",
+  "dist/**",
+  "build/**",
+  "examples/**",
+  "tests/**",
+  "benchmarks/**",
+  "__pycache__/**",
+]
+allow_text = [
+  "https://developers.openai.com/community/codex-for-oss",
+  "https://developers.openai.com/codex/codex-for-oss-terms",
+  "https://github.com/charlesree826/phi-guard-mcp",
+  "https://github.com/charlesree826/phi-guard-mcp/issues",
+  "https://github.com/charlesree826/phi-guard-mcp/actions/workflows/ci.yml",
+  "https://github.com/charlesree826/phi-guard-mcp/actions/workflows/ci.yml/badge.svg",
+  "https://github.com/charlesree826/phi-guard-mcp/releases",
+  "https://github.com/charlesree826/phi-guard-mcp/releases/tag/v0.1.2",
+  "https://github.com/charlesree826/phi-guard-mcp/releases/download/v0.1.2/phi_guard_mcp-0.1.2-py3-none-any.whl",
+  "https://img.shields.io/github/license/charlesree826/phi-guard-mcp.svg",
+  "https://img.shields.io/github/v/release/charlesree826/phi-guard-mcp.svg",
+  "https://img.shields.io/badge/python-3.12%2B-blue.svg",
+  "https://pypi.org/project/phi-guard-mcp/",
+  "https://www.hhs.gov/hipaa/for-professionals/special-topics/de-identification/index.html",
+  "https://www.fda.gov/regulatory-information/search-fda-guidance-documents/clinical-decision-support-software",
+  "https://www.fda.gov/medical-devices/digital-health-center-excellence/device-software-functions-including-mobile-medical-applications",
+  "Jordan Rivera",
+  "MRN-48291",
+  "48291",
+]

phi_guard_mcp-0.1.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want this project to be useful for developers working on healthcare AI privacy and safety. We
+expect participation to be professional, respectful, and focused on improving the software.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Keep discussions technical, specific, and evidence-based.
+- Respect privacy boundaries; never post real patient data or private identifiers.
+- Accept maintainer decisions about scope, especially around clinical decision support and
+  compliance claims.
+
+## Unacceptable Behavior
+
+- Harassment, insults, or personal attacks.
+- Publishing private information without permission.
+- Posting real PHI, credentials, or sensitive infrastructure details.
+- Pressuring maintainers to add diagnosis, treatment, triage, or compliance claims outside the
+  project scope.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments, issues, pull requests, or contributions that violate
+this code of conduct. Serious or repeated violations may lead to blocking from the project.

phi_guard_mcp-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to phi-guard-mcp
+
+Thanks for helping improve `phi-guard-mcp`. This project is healthcare AI privacy infrastructure,
+not a clinical decision support tool. Contributions should keep that boundary clear.
+
+## Ground Rules
+
+- Do not submit real patient records, real medical identifiers, or private account data.
+- Use synthetic examples only.
+- Do not add diagnosis, treatment, triage, prognosis, medication, or clinical risk-scoring features.
+- Keep outputs deterministic and reviewable.
+- Preserve the stable JSON shape used by the Python API, CLI, and MCP tools unless a change is
+  explicitly discussed first.
+
+## Development
+
+Use Python 3.12.
+
+```bash
+python -m pip install -e ".[dev]"
+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/*
+```
+
+## Pull Requests
+
+Please include:
+
+- What changed and why.
+- Whether the change affects PHI detection, redaction, audit output, CLI, or MCP behavior.
+- The synthetic fixtures or tests used.
+- Confirmation that no real PHI or private identifiers were added.
+
+## Benchmark Cases
+
+Benchmark cases must be synthetic. Expected findings should use exact `category` and `text` pairs so
+regressions are easy to review.
+
+## Security and Privacy Reports
+
+Do not open a public issue with real PHI, secrets, exploit details, or private infrastructure data.
+Use the process in `SECURITY.md`.

phi_guard_mcp-0.1.2/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.

phi_guard_mcp-0.1.2/PKG-INFO

@@ -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/*
+```