bms-session-plugin 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "bms-session-plugin",
+  "version": "1.0.0",
+  "description": "BMS Session API integration for HOSxP hospital databases. Provides skills for querying hospital data and building healthcare applications.",
+  "homepage": "https://www.npmjs.com/package/bms-session-plugin"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "bms-session": {
+      "command": "npx",
+      "args": ["-y", "bms-session-mcp-server"],
+      "env": {
+        "BMS_SESSION_ID": "${BMS_SESSION_ID}"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "bms-session-plugin",
+  "version": "1.0.0",
+  "description": "Claude Code plugin for BMS Session API and HOSxP hospital databases",
+  "files": [
+    ".claude-plugin/",
+    "skills/",
+    ".mcp.json"
+  ],
+  "keywords": [
+    "claude-code-plugin",
+    "bms",
+    "hosxp",
+    "hospital",
+    "mcp",
+    "healthcare",
+    "thailand"
+  ],
+  "license": "MIT"
+}

package/skills/bms-session/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: bms-session
+description: This skill should be used when the user asks to "query HOSxP database", "connect to BMS", "use bms-session-id", "query hospital data", "build HOSxP dashboard", "access patient records", mentions "BMS Session", "HOSxP", "hospital database Thailand", or works with Thai hospital systems using HN/VN/AN identifiers.
+---
+
+# BMS Session API — HOSxP Hospital Database Integration
+
+## Purpose
+
+Provide guidance for querying and building applications against HOSxP hospital databases using the BMS Session API. HOSxP is the most widely used hospital information system in Thailand.
+
+## When MCP Server Is Available
+
+If the `bms-session` MCP server is connected, use its tools directly:
+
+1. Read `bms://session-info` resource first to understand the database type and constraints
+2. Use `list_tables` with a pattern filter to discover relevant tables (e.g., `list_tables({ pattern: "patient*" })`)
+3. Use `describe_table` to understand column structure before writing queries
+4. Use `query` to execute SQL and return results
+
+Always use `LIMIT` to avoid returning excessive rows.
+
+## When MCP Server Is Not Available
+
+Build queries using the REST API directly. The flow:
+
+### Step 1: Validate Session
+
+```
+GET https://hosxp.net/phapi/PasteJSON?Action=GET&code={bms-session-id}
+```
+
+Extract from response:
+- `result.user_info.bms_url` — API base URL
+- `result.user_info.bms_session_code` — Bearer token (fallback: `result.key_value`)
+- `result.user_info.bms_database_type` — "MariaDB" or "PostgreSQL"
+- `result.user_info.bms_database_name` — Database name
+
+### Step 2: Execute Queries
+
+```
+POST {bms_url}/api/sql
+Headers: Authorization: Bearer {bms_session_code}, Content-Type: application/json
+Body: { "sql": "SELECT ...", "app": "MyApp" }
+```
+
+Response contains: `data` (rows), `field_name` (columns), `record_count`, `MessageCode`.
+
+## Quick Code Patterns
+
+### Python
+
+```python
+import requests
+
+SESSION_ID = "your-session-id"
+# Step 1: Get session
+session = requests.get(f"https://hosxp.net/phapi/PasteJSON?Action=GET&code={SESSION_ID}").json()
+url = session["result"]["user_info"]["bms_url"]
+token = session["result"]["user_info"].get("bms_session_code") or session["result"].get("key_value")
+
+# Step 2: Query
+result = requests.post(f"{url}/api/sql",
+    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+    json={"sql": "SELECT hn, pname, fname, lname FROM patient LIMIT 10", "app": "MyApp"}
+).json()
+print(result["data"])
+```
+
+### TypeScript
+
+```typescript
+const SESSION_ID = "your-session-id";
+// Step 1: Get session
+const session = await fetch(`https://hosxp.net/phapi/PasteJSON?Action=GET&code=${SESSION_ID}`).then(r => r.json());
+const url = session.result.user_info.bms_url;
+const token = session.result.user_info.bms_session_code ?? session.result.key_value;
+
+// Step 2: Query
+const result = await fetch(`${url}/api/sql`, {
+  method: "POST",
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ sql: "SELECT hn, pname, fname, lname FROM patient LIMIT 10", app: "MyApp" }),
+}).then(r => r.json());
+console.log(result.data);
+```
+
+## HOSxP Database Quick Reference
+
+### Key Identifiers
+- **HN** (Hospital Number) — unique patient ID within a hospital
+- **VN** (Visit Number) — unique outpatient visit ID
+- **AN** (Admission Number) — unique inpatient admission ID
+
+### Core Tables
+
+| Table | Purpose | Key Columns |
+|---|---|---|
+| `patient` | Patient demographics | `hn`, `pname`, `fname`, `lname`, `birthday`, `sex`, `cid` |
+| `opd` | Outpatient visits | `hn`, `vn`, `vstdate`, `doctor` |
+| `ovst` | Visit details | `vn`, `hn`, `vstdate`, `vsttime`, `main_dep` |
+| `ipt` | Inpatient admissions | `an`, `hn`, `regdate`, `dchdate`, `ward` |
+| `doctor` | Physicians | `code`, `name`, `licenseno` |
+| `drugitems` | Medication catalog | `icode`, `name`, `genericname`, `dosageform` |
+| `icd101` | ICD-10 diagnosis codes | `code`, `name`, `tname` |
+
+### Common Relationships
+
+```
+patient.hn ─→ opd.hn (patient's visits)
+opd.vn ─→ ovst.vn (visit details)
+opd.vn ─→ opitemrece.vn (prescriptions/charges)
+patient.hn ─→ ipt.hn (admissions)
+ipt.an ─→ iptdrugorder.an (inpatient orders)
+```
+
+### Table Naming Patterns
+
+| Prefix | Domain |
+|---|---|
+| `patient_*` | Patient-related (demographics, allergies, history) |
+| `opd_*` / `ovst_*` | Outpatient visits |
+| `ipt_*` | Inpatient admissions |
+| `drug*` | Medications and pharmacy |
+| `lab_*` | Laboratory results |
+| `xray_*` / `rad_*` | Radiology |
+| `er_*` | Emergency room |
+| `an_*` / `anc_*` | Antenatal care |
+| `pcu_*` | Primary care unit |
+
+## Constraints and Best Practices
+
+- **Read-only** — Do not attempt write operations unless explicitly requested
+- **Use LIMIT** — HOSxP databases can have millions of records
+- **Single quotes** — Use `'` for string literals (required for PostgreSQL)
+- **Restricted tables** — `opduser`, `opdconfig`, `sys_var`, `user_var`, `user_jwt` are blocked
+- **Max 20 tables** per query
+- **Supported SQL** — SELECT, DESCRIBE, EXPLAIN, SHOW, WITH (CTE)
+- **Sessions expire** — Default 10 hours, check `expired_second` in session response
+
+## Error Handling
+
+| MessageCode | Meaning | Action |
+|---|---|---|
+| 200 | Success | Process data |
+| 400 | Invalid SQL or bad request | Check SQL syntax |
+| 409 | SQL execution error | Check column/table names |
+| 500 | Server error or session expired | Re-validate session |
+| HTTP 501 | Authentication failure | Session expired, get new session ID |
+
+## Additional Resources
+
+### Reference Files
+
+For detailed documentation, consult:
+- **`references/api-reference.md`** — Complete API specification with all endpoints, parameters, field types, and parameter binding
+- **`references/hosxp-database-guide.md`** — Comprehensive HOSxP table catalog, relationships, and Thai healthcare data patterns

package/skills/bms-session/references/api-reference.md

@@ -0,0 +1,199 @@
+# BMS Session API Reference
+
+## Session Validation
+
+### Endpoint
+
+```
+GET https://hosxp.net/phapi/PasteJSON?Action=GET&code={bms-session-id}
+```
+
+### Response Structure
+
+```json
+{
+  "MessageCode": 200,
+  "Message": "OK",
+  "result": {
+    "system_info": {
+      "version": "1.0.0.0",
+      "environment": "production"
+    },
+    "user_info": {
+      "name": "User Name",
+      "position": "Position",
+      "position_id": 1,
+      "hospital_code": "00000",
+      "doctor_code": "00000",
+      "department": "department_name",
+      "location": "location_name",
+      "is_hr_admin": false,
+      "is_director": false,
+      "bms_url": "https://hospital.tunnel.hosxp.net",
+      "bms_session_port": 53845,
+      "bms_session_code": "jwt_token",
+      "bms_database_name": "hosxp_db",
+      "bms_database_type": "PostgreSQL"
+    },
+    "key_value": "jwt_token",
+    "expired_second": 36000
+  },
+  "RequestTime": "2025-10-20T12:00:00.000Z"
+}
+```
+
+### Key Fields
+
+| Path | Purpose |
+|---|---|
+| `result.user_info.bms_url` | Base URL for API calls |
+| `result.user_info.bms_session_code` | Bearer token for authentication |
+| `result.key_value` | Fallback bearer token (same value) |
+| `result.user_info.bms_database_type` | "MariaDB" or "PostgreSQL" — determines SQL dialect |
+| `result.user_info.bms_database_name` | Database name |
+| `result.expired_second` | Session TTL in seconds |
+
+## /api/sql — Read Operations
+
+### GET Method
+
+```
+GET {bms_url}/api/sql?sql=SELECT+VERSION()&app=MyApp
+Authorization: Bearer {bms_session_code}
+```
+
+### POST Method (Recommended)
+
+```
+POST {bms_url}/api/sql
+Authorization: Bearer {bms_session_code}
+Content-Type: application/json
+
+{
+  "sql": "SELECT hn, pname, fname, lname FROM patient LIMIT 10",
+  "app": "MyApp"
+}
+```
+
+### POST with Parameter Binding
+
+Prevents SQL injection by binding parameters separately:
+
+```json
+{
+  "sql": "SELECT * FROM patient WHERE birthday = :birthday AND bloodgrp = :bloodgrp",
+  "app": "MyApp",
+  "params": {
+    "birthday": { "value": "2024-01-01", "value_type": "date" },
+    "bloodgrp": { "value": "O", "value_type": "string" }
+  }
+}
+```
+
+### Parameter Types
+
+| Type | Description | Example |
+|---|---|---|
+| `string` | Text values | `"John"` |
+| `integer` | Whole numbers | `42` |
+| `float` | Decimal numbers | `3.14` |
+| `date` | YYYY-MM-DD | `"2024-01-01"` |
+| `time` | HH:mm:ss | `"08:00:00"` |
+| `datetime` | ISO 8601 | `"2024-01-01T08:00:00"` |
+
+### Supported SQL Statements
+
+| Statement | Purpose | Example |
+|---|---|---|
+| `SELECT` | Retrieve data | `SELECT * FROM patient LIMIT 10` |
+| `DESCRIBE` | Table structure (MariaDB) | `DESCRIBE patient` |
+| `EXPLAIN` | Query execution plan | `EXPLAIN SELECT * FROM patient` |
+| `SHOW` | Database metadata | `SHOW TABLES`, `SHOW DATABASES` |
+| `WITH` | Common Table Expressions | `WITH cte AS (SELECT ...) SELECT * FROM cte` |
+
+### Response Format
+
+```json
+{
+  "MessageCode": 200,
+  "Message": "OK",
+  "RequestTime": "2025-10-20T12:00:00.000Z",
+  "data": [
+    { "hn": "12345", "pname": "Mr.", "fname": "John", "lname": "Doe" }
+  ],
+  "field": [6, 6, 6, 6],
+  "field_name": ["hn", "pname", "fname", "lname"],
+  "record_count": 1
+}
+```
+
+### Field Type Codes
+
+The `field` array contains type codes for each column:
+
+| Code | Type | Description |
+|---|---|---|
+| 1 | Boolean | true/false |
+| 2 | Integer | Whole numbers |
+| 3 | Float | Decimal numbers |
+| 4 | DateTime | ISO 8601 format |
+| 5 | Time | HH:mm:ss |
+| 6 | String | Text (most common) |
+| 7 | Blob | Binary data (Base64) |
+| 9 | String (Alt) | Alternative text type |
+
+### Error Codes
+
+| MessageCode | Meaning |
+|---|---|
+| 200 | Success |
+| 400 | Invalid SQL, bad request, or invalid key |
+| 409 | SQL execution error (bad column/table name) |
+| 500 | Server error or session expired |
+
+| HTTP Status | Meaning |
+|---|---|
+| 200 | Request processed (check MessageCode) |
+| 501 | Unauthorized — missing or invalid Bearer token |
+
+### Security Restrictions
+
+- **Table blacklist**: `opduser`, `opdconfig`, `sys_var`, `user_var`, `user_jwt`
+- **Max 20 tables** per query
+- **No cross-database queries** (dots not allowed in table names)
+- **SQL whitelist**: Only SELECT, DESCRIBE, EXPLAIN, SHOW, WITH allowed
+- Trailing semicolons are removed automatically
+- Backslashes are converted for safety
+
+## /api/sql_update — Write Operations
+
+Write operations require an additional authentication key and are not covered by default in read-only integrations. Include only when the user explicitly requests write capability.
+
+### Authentication Key
+
+```
+key = MD5(bms_session_code + "PO7yRv3OdFwK81eg").toUpperCase()
+```
+
+### Upsert (POST)
+
+```json
+{
+  "sql": "SELECT hn, fname FROM patient WHERE hn = '12345'",
+  "app": "MyApp",
+  "key": "MD5_HASH",
+  "table_name": "patient",
+  "field": [6, 6],
+  "data": [{ "hn": "12345", "fname": "Updated Name" }]
+}
+```
+
+### Delete (DELETE method)
+
+Same format as upsert. The `sql` identifies records to delete. `data` is ignored.
+
+### Write Constraints
+
+- `sql` must be a simple SELECT (no JOINs, subqueries, GROUP BY)
+- Table must have exactly one primary key
+- `field` array must match columns in the SELECT query

package/skills/bms-session/references/hosxp-database-guide.md

@@ -0,0 +1,191 @@
+# HOSxP Database Guide
+
+HOSxP is the most widely used hospital information system (HIS) in Thailand, deployed in over 800 hospitals. This guide covers database conventions, common tables, and query patterns.
+
+## Database Platforms
+
+HOSxP deployments use either:
+- **MariaDB** (older/most common) — Use `SHOW TABLES`, `DESCRIBE table_name`
+- **PostgreSQL** (newer deployments) — Use `information_schema` queries, single quotes required
+
+Always check `bms_database_type` from the session response to determine which dialect to use.
+
+## Key Identifiers
+
+| Abbreviation | Thai Name | Purpose | Format |
+|---|---|---|---|
+| **HN** | เลขประจำตัวผู้ป่วย | Hospital Number — unique patient ID | String, e.g., `"000001"` |
+| **VN** | เลขครั้งที่มา | Visit Number — outpatient visit ID | String, e.g., `"6801000001"` |
+| **AN** | เลขรับรองการรักษา | Admission Number — inpatient stay ID | String, e.g., `"68/00001"` |
+| **CID** | เลขบัตรประชาชน | Citizen ID (13-digit Thai national ID) | String, 13 chars |
+
+## Core Tables
+
+### Patient Registration
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `patient` | Master patient index | `hn` (PK), `pname`, `fname`, `lname`, `birthday`, `sex`, `cid`, `bloodgrp` |
+| `patient_pttype` | Patient insurance types | `hn`, `pttype`, `hospmain`, `startdate`, `expiredate` |
+| `patient_drug` | Patient medication records | `hn`, `drugitems_icode`, `vstdate` |
+| `patient_allergy` | Known allergies | `hn`, `agent`, `symptom` |
+
+### Outpatient (OPD)
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `opd` | Outpatient visit header | `hn`, `vn`, `vstdate`, `doctor`, `main_dep` |
+| `ovst` | Visit details | `vn` (PK), `hn`, `vstdate`, `vsttime`, `main_dep`, `main_dep_queue` |
+| `ovstdiag` | Visit diagnoses | `vn`, `icd10`, `diagtype` (1=principal, 2=co-morbid) |
+| `opitemrece` | Prescriptions & charges | `vn`, `icode`, `qty`, `unitprice` |
+| `ovstost` | Vital signs | `vn`, `bp_systolic`, `bp_diastolic`, `pulse`, `temperature` |
+
+### Inpatient (IPT)
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `ipt` | Admission header | `an` (PK), `hn`, `regdate`, `dchdate`, `ward`, `pression` |
+| `iptdiag` | Admission diagnoses | `an`, `icd10`, `diagtype` |
+| `iptdrugorder` | Inpatient drug orders | `an`, `icode`, `qty`, `orderdate` |
+| `ipt_nurse_note` | Nursing notes | `an`, `note_date`, `note_time`, `note_text` |
+
+### Medications & Pharmacy
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `drugitems` | Drug catalog (master) | `icode` (PK), `name`, `genericname`, `dosageform`, `strength` |
+| `drugusage` | Drug usage instructions | `drugusage` (PK), `name`, `name1`, `name2`, `name3` |
+| `drugstock` | Drug inventory | `icode`, `qty`, `warehouse` |
+| `nondrugitems` | Non-drug items (supplies) | `icode` (PK), `name`, `unitprice` |
+
+### Laboratory
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `lab_head` | Lab order header | `lab_order_number`, `hn`, `vn`, `order_date` |
+| `lab_order` | Lab order items | `lab_order_number`, `lab_items_code`, `lab_order_result` |
+| `lab_items` | Lab test catalog | `lab_items_code` (PK), `lab_items_name`, `lab_items_unit` |
+
+### Reference / Lookup Tables
+
+| Table | Description | Key Columns |
+|---|---|---|
+| `icd101` | ICD-10 diagnosis codes | `code` (PK), `name` (English), `tname` (Thai) |
+| `icd9cm1` | ICD-9-CM procedure codes | `code`, `name`, `tname` |
+| `pttype` | Insurance/payer types | `pttype` (PK), `name`, `nhso_code` |
+| `kskdepartment` | Hospital departments | `depcode` (PK), `department` |
+| `ward` | Ward/bed management | `ward` (PK), `name` |
+| `spclty` | Medical specialties | `spclty` (PK), `name` |
+
+## Common Query Patterns
+
+### Patient Lookup
+
+```sql
+-- By HN
+SELECT hn, pname, fname, lname, birthday, sex FROM patient WHERE hn = '000001'
+
+-- By name (Thai)
+SELECT hn, pname, fname, lname FROM patient WHERE fname LIKE '%สมชาย%' LIMIT 20
+
+-- By CID
+SELECT hn, pname, fname, lname FROM patient WHERE cid = '1234567890123'
+```
+
+### Visit History
+
+```sql
+-- Recent OPD visits for a patient
+SELECT o.vn, o.vstdate, d.name as doctor_name, k.department
+FROM ovst o
+LEFT JOIN doctor d ON d.code = o.doctor
+LEFT JOIN kskdepartment k ON k.depcode = o.main_dep
+WHERE o.hn = '000001'
+ORDER BY o.vstdate DESC
+LIMIT 20
+```
+
+### Diagnosis Statistics
+
+```sql
+-- Top 10 diagnoses this month
+SELECT od.icd10, i.name as diagnosis, COUNT(*) as visit_count
+FROM ovstdiag od
+JOIN icd101 i ON i.code = od.icd10
+JOIN ovst o ON o.vn = od.vn
+WHERE o.vstdate >= '2026-01-01' AND o.vstdate <= '2026-01-31'
+  AND od.diagtype = '1'
+GROUP BY od.icd10, i.name
+ORDER BY visit_count DESC
+LIMIT 10
+```
+
+### Drug Prescriptions
+
+```sql
+-- Most prescribed drugs this month
+SELECT d.name as drug_name, d.genericname, COUNT(*) as rx_count
+FROM opitemrece oi
+JOIN drugitems d ON d.icode = oi.icode
+JOIN ovst o ON o.vn = oi.vn
+WHERE o.vstdate >= '2026-01-01'
+  AND d.name IS NOT NULL
+GROUP BY d.name, d.genericname
+ORDER BY rx_count DESC
+LIMIT 20
+```
+
+### Patient Counts by Department
+
+```sql
+SELECT k.department, COUNT(DISTINCT o.hn) as patient_count, COUNT(*) as visit_count
+FROM ovst o
+JOIN kskdepartment k ON k.depcode = o.main_dep
+WHERE o.vstdate >= '2026-01-01'
+GROUP BY k.department
+ORDER BY visit_count DESC
+```
+
+## Table Discovery Patterns
+
+HOSxP has thousands of tables. Use these patterns to find relevant ones:
+
+| Looking for | Search pattern | Example tables |
+|---|---|---|
+| Patient data | `patient*` | patient, patient_pttype, patient_allergy |
+| Outpatient | `o*`, `opd*`, `ovst*` | opd, ovst, ovstdiag, opitemrece |
+| Inpatient | `ipt*` | ipt, iptdiag, iptdrugorder |
+| Drugs | `drug*` | drugitems, drugusage, drugstock |
+| Lab | `lab_*` | lab_head, lab_order, lab_items |
+| Radiology | `xray_*`, `rad_*` | xray_head, rad_request |
+| Emergency | `er_*` | er_regist, er_nursing_detail |
+| Dental | `*dent*` | patient_dent_diagram |
+| Antenatal | `anc_*` | anc_head, anc_detail |
+| Surgery | `*oper*` | operation_list, operation_detail |
+| Appointment | `*appoint*` | oapp (OPD appointment) |
+| Referral | `*refer*` | referout, referin |
+| Insurance | `pttype*` | pttype, patient_pttype |
+
+## Thai Healthcare Context
+
+### Insurance Types (pttype)
+
+Common Thai healthcare insurance schemes:
+- **UC** (บัตรทอง) — Universal Coverage (NHSO)
+- **SSS** (ประกันสังคม) — Social Security Scheme
+- **CSMBS** (ข้าราชการ) — Civil Servant Medical Benefit Scheme
+- **Self-pay** (จ่ายเอง) — Out-of-pocket
+
+### Department Codes
+
+Departments vary by hospital but common patterns:
+- Emergency, OPD General, OPD Specialty clinics
+- IPD wards (medical, surgical, pediatric, obstetric)
+- Operating room, ICU, Dental
+
+### Data Sensitivity Notes
+
+- `cid` (Citizen ID) is personally identifiable — use aggregated data when possible
+- Patient names (`fname`, `lname`) are PII — anonymize in reports
+- Design dashboards to show statistics and trends, not individual patient records
+- The BMS Session system is designed for non-sensitive operational data access