hipaa-mcp 0.1.0__tar.gz

hipaa_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync *)",
+      "Bash(python3 -m pip install -e \".[dev]\")",
+      "Bash(curl -Ls https://astral.sh/uv/install.sh)",
+      "Bash(sh)",
+      "Bash(pip install *)",
+      "Bash(uv venv *)",
+      "Bash(uv run *)",
+      "Bash(uv add *)",
+      "Bash(curl -s \"https://www.ecfr.gov/api/versioner/v1/full/2026-04-16/title-45.xml\" --range 0-3000)",
+      "Bash(.venv/bin/python *)",
+      "Bash(.venv/bin/pytest *)",
+      "Bash(timeout 10 .venv/bin/hipaa-mcp serve)",
+      "Bash(grep -v '^$')",
+      "Bash(python3 -c \"import sys,json; [print\\(json.dumps\\(json.loads\\(l\\), indent=2\\)\\) for l in sys.stdin if l.strip\\(\\) and '\\\\\"id\\\\\":2' in l]\")",
+      "Bash(claude mcp *)",
+      "Read(//home/zachw/.claude/**)",
+      "Skill(update-config)",
+      "mcp__hipaa-mcp__search_regulations",
+      "mcp__hipaa-mcp__list_glossary_terms",
+      "mcp__hipaa-mcp__get_section",
+      "Bash(python -m spacy download en_core_web_sm)",
+      "mcp__hipaa-mcp__add_glossary_term",
+      "mcp__hipaa-mcp__explain_search",
+      "Bash(grep -E '\\\\.\\(toml|md|cfg|txt\\)$')"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "hipaa-mcp"
+  ]
+}

hipaa_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# deps / build
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+
+# tool caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# user data (chromadb, bm25 index, user glossary)
+data/chroma/
+data/bm25_index.pkl
+data/user_glossary.yaml
+*.db
+
+# env
+.env
+
+# claude instructions (local only)
+claude.md
+CLAUDE.md
+
+# OS
+.DS_Store
+Thumbs.db

hipaa_mcp-0.1.0/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "hipaa-mcp": {
+      "type": "stdio",
+      "command": "uv",
+      "args": ["run", "--directory", "/mnt/c/users/zachw/repos/hipaa-2-vec", "hipaa-mcp", "serve"]
+    }
+  }
+}

hipaa_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodePapayas
+
+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.

hipaa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: hipaa-mcp
+Version: 0.1.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: click>=8.1
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: spacy>=3.7

hipaa_mcp-0.1.0/README.md

@@ -0,0 +1,244 @@
+# 🏥 hipaa-mcp
+
+> **Ask HIPAA questions in plain English. Get exact citations back. Nothing else.**
+
+A local-first MCP server that searches **45 CFR Part 164 (HIPAA)** and **42 CFR Part 2** and returns precise regulatory citations like `§ 164.308(a)(1)(ii)(A)` — not summaries, not interpretations, not vibes.
+
+Built for healthtech developers who need to answer "do I need a BAA for this vendor?" without reading 200 pages of CFR or trusting a Reddit thread.
+
+---
+
+> ⚠️ **This is a reference tool, not a compliance tool.** It retrieves and cites regulation text. It does not tell you what the regulation means for your situation. When in doubt, talk to a lawyer.
+
+---
+
+## ✨ What it does
+
+| Tool | What it returns |
+|---|---|
+| `search_regulations("do I need a BAA for my analytics vendor?")` | Ranked `§ X.Y` citations with full regulation text |
+| `get_section("§ 164.308(a)(1)")` | Full text of that specific section |
+| `explain_search("why did my microservice query return these results?")` | Same results + full provenance: which glossary terms fired, confidence scores, per-hit vector/BM25 scores |
+| `add_glossary_term / list_glossary_terms / remove_glossary_term` | Tune how your developer vocabulary maps to regulatory terms |
+
+**How search works:** hybrid vector + BM25 retrieval merged with reciprocal rank fusion → your query gets expanded (e.g. "vendor" → "business associate") before hitting the index → results ranked by combined score. No cloud, no OpenAI, no Anthropic. Everything runs on your machine.
+
+---
+
+## 🚀 Quick start
+
+### Prerequisites
+
+| Dependency | Install |
+|---|---|
+| Python 3.12+ | [python.org](https://www.python.org/downloads/) or `pyenv install 3.12` |
+| `uv` (package manager) | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Ollama *(optional, improves search)* | [ollama.com](https://ollama.com) |
+
+### 1. Install
+
+```bash
+git clone https://github.com/CodePapayas/hipaa-2-vec
+cd hipaa-2-vec
+uv sync
+```
+
+### 2. Download the spaCy language model
+
+```bash
+uv run python -m spacy download en_core_web_sm
+```
+
+> This is used for POS tagging so "building a SaaS" doesn't match regulation text about building facilities.
+
+### 3. Index the regulations
+
+```bash
+uv run hipaa-mcp reindex
+```
+
+This downloads the eCFR XML from the federal government, parses it into chunks, and builds a local ChromaDB vector index + BM25 index. Takes a minute or two. Only needs to run once (or when you want fresh regulation text).
+
+### 4. *(Optional)* Pull the LLM for smarter query rewriting
+
+```bash
+ollama pull gemma4:e4b
+```
+
+Without this, glossary-based expansion still runs — you just won't get LLM-assisted query rewriting. Works fine either way.
+
+---
+
+## 🔌 Connect to Claude Desktop (or any MCP client)
+
+Add this to your MCP config file:
+
+**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "hipaa-mcp": {
+      "command": "uv",
+      "args": ["run", "hipaa-mcp", "serve"],
+      "cwd": "/path/to/hipaa-2-vec"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the 🔨 tools icon — `search_regulations`, `get_section`, `explain_search`, and the glossary tools will be available.
+
+---
+
+## 💬 Example queries
+
+```
+"Do I need a BAA with my logging vendor?"
+"What are the minimum necessary standards?"
+"Can I share patient data with a data analytics subprocessor?"
+"What does HIPAA say about breach notification timelines?"
+"What's required for de-identified data?"
+```
+
+Each returns the matching regulation sections verbatim with their `§` citations. The tool never interprets — just retrieves.
+
+---
+
+## 🗂️ CLI reference
+
+```bash
+# Start MCP server over stdio (used by Claude Desktop / MCP clients)
+hipaa-mcp serve
+
+# Rebuild the index (re-downloads eCFR XML, rebuilds ChromaDB + BM25)
+hipaa-mcp reindex
+hipaa-mcp reindex --date 2026-01-01   # pin to a specific regulation date
+
+# Glossary management
+hipaa-mcp glossary list               # show all term mappings
+hipaa-mcp glossary path               # show where the YAML file lives
+```
+
+---
+
+## 📖 The glossary: why it exists and how to use it
+
+HIPAA uses different words than developers do. The glossary bridges that gap at query time — no re-indexing required when you change it.
+
+### Built-in mappings (sample)
+
+| What you say | What HIPAA says |
+|---|---|
+| SaaS, vendor, contractor | business associate |
+| share, send, transmit | disclosure |
+| delete, purge, wipe | destruction |
+| consent, opt-in | authorization |
+| logging, audit log | audit controls |
+| least privilege | minimum necessary |
+| breach, data leak | breach notification |
+| de-identified | *(anti)* not PHI |
+
+### Relationship types
+
+| Type | Behavior |
+|---|---|
+| `synonym` | Expand in both directions |
+| `hyponym` | One-way only (your term → regulatory term) |
+| `contextual` | Only expand if a scope keyword appears in the query |
+| `anti` | When your term is present, *exclude* the target from expansion |
+
+### Inspecting expansion with `explain_search`
+
+When you want to understand *why* a query returned specific results, use `explain_search` instead of `search_regulations`. It returns the same hits plus:
+
+- **`glossary_matches`** — every glossary entry that fired, with `confidence` (0–1), the relationship type, and which `scope_triggered` words caused a contextual match
+- **`vector_score`** — cosine similarity (0–1) between the query and the chunk
+- **`bm25_score`** — lexical match score normalized to the top BM25 result (0–1)
+- **`rrf_score`** — the final merged rank fusion score
+
+```
+explain_search("does my microservice need a BAA if it processes PHI?")
+→ glossary_matches:
+    "microservice" → "business associate"  [contextual, scope: PHI]  confidence: 0.95
+    "processes"    → "use"                 [synonym, VERB subst.]    confidence: 1.0
+→ hits:
+    § 164.308  vector=0.71  bm25=1.00  rrf=0.032  [hybrid]
+    § 164.314  vector=0.65  bm25=0.84  rrf=0.031  [hybrid]
+```
+
+### Adding your own mappings
+
+```bash
+# Via MCP tool (works inside Claude)
+add_glossary_term(phrase="my term", maps_to="regulatory term", relationship="synonym")
+
+# Or edit the YAML directly
+hipaa-mcp glossary path   # shows the file location
+```
+
+The glossary lives in your platform's user data directory — it won't be overwritten by upgrades.
+
+---
+
+## ⚙️ Configuration
+
+All env vars are prefixed `HIPAA_MCP_`. You can set them in a `.env` file in the project root.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `HIPAA_MCP_OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |
+| `HIPAA_MCP_LLM_MODEL` | `gemma4:e4b` | Model used for query rewriting |
+| `HIPAA_MCP_USE_LLM_FOR_QUERY_UNDERSTANDING` | `true` | Set `false` to skip LLM rewriting (glossary expansion still runs) |
+| `HIPAA_MCP_DATA_DIR` | platform user data dir | Where ChromaDB, BM25 index, and glossary are stored |
+| `HIPAA_MCP_TOP_K_DEFAULT` | `5` | Default number of results returned |
+
+**Example `.env`:**
+```env
+HIPAA_MCP_USE_LLM_FOR_QUERY_UNDERSTANDING=false
+HIPAA_MCP_TOP_K_DEFAULT=10
+```
+
+---
+
+## 🧪 Running tests
+
+```bash
+uv run pytest
+```
+
+Tests use in-memory ChromaDB and a stub LLM — no real Ollama calls, no network required.
+
+---
+
+## 🗺️ What's in scope / not in scope
+
+| ✅ In scope | ❌ Not in scope |
+|---|---|
+| HIPAA 45 CFR Part 164 | Legal interpretation of any kind |
+| 42 CFR Part 2 (substance use records) | Cloud inference of any kind |
+| Plain-English → citation search | A web UI |
+| Local-only, air-gappable | Authentication |
+| Glossary-tunable query expansion | Regs beyond HIPAA + Part 2 |
+
+---
+
+## 📦 Stack
+
+`Python 3.12` · `FastMCP` · `ChromaDB` · `rank_bm25` · `Pydantic v2` · `spaCy` · `lxml` · `Ollama (Gemma 4 E4B)` · `uv`
+
+---
+
+## 🗒️ TODO
+
+- **Glossary expansion preview during reindex** — while `hipaa-mcp reindex` runs, sample ~1 in 5 glossary mappings and print them as they're applied, e.g.:
+
+  ```
+  expanding  "vendor"       →  "business associate"
+  expanding  "share"        →  "disclosure"
+  expanding  "delete"       →  "destruction"
+  ...
+  ```
+
+  Goal: visual confirmation the glossary is wired up correctly + teaches developers the regulatory vocabulary while they wait. Not all terms — just a representative sample, whatever looks good in the terminal.