fhir-r6-guardrails

分类: 工具与效率 | 上传者: aks129 | 下载: 0 | 版本: v1.0（最新）

HealthClaw Guardrails (healthclaw.io) — FHIR 代理护栏，用于通过 MCP 安全访问临床数据。支持 FHIR R4 US Core v9（稳定）和 R6 ballot3（实验）。在以下情况下使用：(1) 通过自动 PHI 编辑功能通过 MCP 读取患者数据，(2) 使用两阶段提议/提交和逐步身份验证编写临床资源，(3) 将请求代理到真实的 FHIR 服务器（HAPI、SMART Health IT、Epic），(4) 审核 AI 代理对医疗保健数据的访问，(5) 评估 R6 权限资源以进行访问控制决策。 12 个 MCP 工具，带护栏强制执行功能。

更新日志: Source: GitHub https://github.com/aks129/HealthClawGuardrails

目录结构

当前层级: tree/main/openclaw/

📄 SKILL.md 5.5 KB

SKILL.md

---
name: fhir-r6-guardrails
version: 1.0.0
description: >
  HealthClaw Guardrails (healthclaw.io) — FHIR agent guardrails for secure clinical
  data access via MCP. Supports FHIR R4 US Core v9 (stable) and R6 ballot3
  (experimental). Use when: (1) Reading patient data through MCP with automatic PHI
  redaction, (2) Writing clinical resources with two-phase propose/commit and step-up
  auth, (3) Proxying requests to real FHIR servers (HAPI, SMART Health IT, Epic),
  (4) Auditing AI agent access to healthcare data, (5) Evaluating R6 Permission
  resources for access control decisions. 12 MCP tools with guardrail enforcement.
metadata:
  openclaw:
    requires:
      env:
        - STEP_UP_SECRET
      bins:
        - node
        - python3
    install:
      - kind: node
        packages:
          - "@modelcontextprotocol/sdk"
          - express
          - node-fetch
      - kind: uv
        packages:
          - flask
          - flask-sqlalchemy
          - httpx
    primaryEnv: STEP_UP_SECRET
---

# FHIR R6 MCP Guardrail Patterns

A runtime security layer for AI agent access to FHIR clinical data via Model Context
Protocol (MCP). This is NOT a knowledge skill — it runs an MCP server that enforces
PHI redaction, step-up authorization, immutable audit trails, and tenant isolation
on every request.

## Setup

### Docker Compose (recommended)

```bash
# Clone the repository
git clone https://github.com/aks129/fhir-mcp-guardrails.git
cd fhir-mcp-guardrails

# Set required secret
export STEP_UP_SECRET=$(openssl rand -hex 32)

# Start all services
docker-compose up -d --build
```

### Manual Setup

```bash
# Python backend (Flask)
uv sync
export STEP_UP_SECRET=$(openssl rand -hex 32)
python main.py &

# MCP server (Node.js)
cd services/agent-orchestrator
npm ci
npm start
```

### Connect to a Real FHIR Server

```bash
export FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4
# All guardrails apply to upstream responses automatically
```

## MCP Server Endpoints

- **Streamable HTTP**: `POST http://localhost:3001/mcp` (preferred)
- **SSE**: `GET http://localhost:3001/sse` (legacy MCP transport)
- **HTTP bridge**: `POST http://localhost:3001/mcp/rpc` (non-MCP clients)

## Available MCP Tools

### Read Tools (no step-up required)

**`context.get`** — Retrieve a pre-built context envelope with patient-centric FHIR
resources. Returns bounded, policy-stamped, time-limited context.

**`fhir.read`** — Read a single FHIR resource by type and ID. Response is automatically
redacted (names to initials, identifiers masked, dates truncated).

**`fhir.search`** — Search FHIR resources with filters: patient, code, status,
_lastUpdated, _count (max 50), _sort. Returns a redacted Bundle.

**`fhir.validate`** — Validate a proposed FHIR resource against structural rules.
Returns OperationOutcome with errors and warnings.

**`fhir.stats`** — Compute count/min/max/mean over Observation valueQuantity values.
Standard FHIR $stats operation (since R4). Filter by patient and/or LOINC code.

**`fhir.lastn`** — Get the last N observations per code. Standard FHIR $lastn.
Sorted by storage order, not effectiveDateTime.

**`fhir.permission_evaluate`** — Evaluate R6 Permission resources for access control.
Returns permit/deny with reasoning. Separates access control from consent records.

**`fhir.subscription_topics`** — List available SubscriptionTopics for event-driven
subscriptions.

### Write Tools (require step-up token)

**`fhir.propose_write`** — Validate and preview a write without committing. Identifies
clinical resource types that require human-in-the-loop confirmation.

**`fhir.commit_write`** — Commit a proposed write. Requires `X-Step-Up-Token` header
(HMAC-SHA256, 5-min TTL). Clinical resources also require `X-Human-Confirmed: true`.

## Write Workflow

Always use the two-phase pattern:

1. Call `fhir.propose_write` with the resource and operation type
2. Check `proposal_status` — must be `"ready"` to proceed
3. Note `requires_human_confirmation` for clinical types (Observation, Condition, etc.)
4. Call `fhir.commit_write` with step-up token and human confirmation headers

## Security Guardrails

All guardrails are enforced automatically on every request:

- **PHI Redaction**: Names → initials, identifiers → last 4 chars, addresses stripped,
  birth dates → year only, photos removed, notes → [Redacted]
- **Audit Trail**: Append-only AuditEvent for every resource access
- **Step-Up Auth**: HMAC-SHA256 tokens with nonce, TTL, tenant binding for writes
- **Tenant Isolation**: X-Tenant-Id enforced at database layer on every query
- **URL Rewriting**: Upstream server URLs never leak to clients
- **Medical Disclaimers**: Injected on clinical resource reads

## Supported Resource Types

Patient, Encounter, Observation, AuditEvent, Consent, Permission, SubscriptionTopic,
Subscription, NutritionIntake, NutritionProduct, DeviceAlert, DeviceAssociation,
Requirements, ActorDefinition.

## R6-Specific Resources

- **Permission** — Access control resource with $evaluate operation (separate from Consent)
- **DeviceAlert** — ISO/IEEE 11073 device alarms
- **NutritionIntake** — Dietary consumption tracking
- **SubscriptionTopic** — Restructured pub/sub (introduced R5, maturing R6)

## Limitations

- Local mode: SQLite JSON blob storage, table scans for filtering
- Structural validation only (no StructureDefinition or terminology binding)
- Human-in-the-loop is header-based, not cryptographic
- Upstream proxy: no response caching, no cross-version translation
- SubscriptionTopic stored but notifications not dispatched

登录后下载/点赞/收藏 ❤ 12 | ★ 0

fhir-r6-guardrails

目录结构

SKILL.md

举报内容

提示