oth-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,58 +1,40 @@
 # oth-mcp
 
-MCP server for the [OTH (OpenTeleHealth) API](https://doccla-dev.oth.io/api/docs). Gives Claude direct access to query and manage OTH resources across environments.
+MCP server for https://doccla-dev.oth.io/api/docs Gives agents direct access to query and manage OTH resources
+
+
+
+https://github.com/user-attachments/assets/c31f864a-2896-46b2-8ac1-ae62dd9293b5
+
+
+## Design
+
+The server is designed for minimal token usage. Instead of embedding the full API reference in tool descriptions, the endpoint guide is exposed as an [MCP resource](https://github.com/doccla-experiments/oth-mcp/blob/main/src/api-guide.ts) (`oth://api-guide`) that the agent loads on demand — only when it needs to look up paths or request bodies. This keeps each tool call lightweight while still giving agents access to the complete reference.
 
 ## Setup
 
 ### 1. Configure credentials
 
-**Environment variables** (works everywhere):
+**macOS Keychain (preferred)** — no plaintext on disk:
 
 ```bash
-export OTH_USERNAME="your-username"
-export OTH_PASSWORD="your-password"
-export OTH_ENV="dev"  # optional, defaults to dev
+# For each environment (oth-dev, oth-stag, oth-demo):
+security add-generic-password -a "oth-dev" -s "oth-mcp-username" -w
+security add-generic-password -a "oth-dev" -s "oth-mcp-password" -w
 ```
 
-**macOS Keychain** (no plaintext on disk):
+**Environment variables** (works everywhere):
 
 ```bash
-# For each environment (dev, stag, demo):
-security add-generic-password -a "oth-dev" -s "oth-mcp-username" -w
-security add-generic-password -a "oth-dev" -s "oth-mcp-password" -w
+export OTH_USERNAME="your-username"
+export OTH_PASSWORD="your-password"
+export OTH_ENV="dev"  # optional, defaults to dev
 ```
 
 ### 2. Add to Claude Code
 
-Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
-
-```json
-{
-  "mcpServers": {
-    "oth": {
-      "command": "npx",
-      "args": ["-y", "oth-mcp"]
-    }
-  }
-}
-```
-
-Or with inline credentials:
-
-```json
-{
-  "mcpServers": {
-    "oth": {
-      "command": "npx",
-      "args": ["-y", "oth-mcp"],
-      "env": {
-        "OTH_USERNAME": "your-username",
-        "OTH_PASSWORD": "your-password",
-        "OTH_ENV": "dev"
-      }
-    }
-  }
-}
+```bash
+claude mcp add oth -- npx -y oth-mcp
 ```
 
 ## Tools
@@ -85,4 +67,4 @@ oth_env({})  // show current env + auth state
 ## Limitations
 
 - **MFA not supported** — accounts with MFA enabled will fail to authenticate. Use an account without MFA.
-- **macOS Keychain only on macOS** — Linux/Windows users must use environment variables.
+- **macOS Keychain only on macOS** — Linux/Windows users must use environment variables.

package/dist/api-guide.d.ts

@@ -1 +1 @@
-export declare const API_GUIDE = "# OTH API Endpoint Reference\n\n## Patients\nGET /clinician/api/patients                     ?username= &firstName= &lastName= &uniqueId= &status= &max= &offset=\nGET /clinician/api/patients/{id}\nGET /clinician/api/patients/me\nGET /clinician/api/patients/{id}/measurements           ?from= &to= &max=\nGET /clinician/api/patients/{id}/measurements/aggregate\nGET /clinician/api/patients/{id}/measurement-types\nGET /clinician/api/patients/{id}/questionnaires\nGET /clinician/api/patients/{id}/questionnaire-results  ?from= &to= &max=\nGET /clinician/api/patients/{id}/questionnaire_schedules\nPOST /clinician/api/patients/{id}/questionnaire_schedules\nGET /clinician/api/patients/{id}/contact-info\nPUT /clinician/api/patients/{id}/contact-info\nGET /clinician/api/patients/{id}/acknowledgements\n\n## Clinicians\nGET /clinician/api/clinicians                    ?max= &offset=\nPOST /clinician/api/clinicians\nGET /clinician/api/clinicians/{id}\nPUT /clinician/api/clinicians/{id}\nGET /clinician/api/clinicians/me\nGET /clinician/api/clinicians/me/colleagues\n\n## Questionnaire Definitions\nGET /clinician/api/questionnaire_definitions     ?max= &offset=\nGET /clinician/api/questionnaire_definitions/{id}\nPOST /clinician/api/questionnaire_definitions    {name, requiresManualInspection}\nPUT /clinician/api/questionnaire_definitions/{id}\n\n## Questionnaires (node graph)\nGET /clinician/api/questionnaires/{id}\nPOST /clinician/api/questionnaires/{id}/results\n\n## Questionnaire Results\nGET /clinician/api/questionnaire-results         ?from= &to= &max= &offset=\nGET /clinician/api/questionnaire-results/{id}\n\n## Questionnaire Schedules\nGET /clinician/api/questionnaire_schedules       ?max= &offset=\n\n## Questionnaire Groups\nGET /questionnaires/questionnaire-groups         ?max=\nPOST /questionnaires/questionnaire-groups        {name, questionnaireDefinitions}\n\n## Patient Notes\nGET /clinician/api/patient-notes                 ?max= &offset=\nPOST /clinician/api/patient-notes\nGET /clinician/api/patient-notes/{id}\nPUT /clinician/api/patient-notes/{id}\nDELETE /clinician/api/patient-notes/{id}\nPOST /clinician/api/patient-notes/{id}/read\n\n## Measurements\nGET /measurements/measurement-types\nGET /measurements/measurement-captures           ?patient= &from= &to= &max=\nPOST /measurements/measurement-captures\nGET /measurements/measurement-captures/{uuid}\nPOST /measurements/measurement-captures/{uuid}/measurements\nGET /measurements/measurement-streams            ?patient= &from= &to= &max=\nPOST /measurements/measurement-streams\nGET /measurements/measurement-streams/{uuid}\nGET /measurements/measurement-streams/{uuid}/measurements\nGET /measurements/measurement-streams/{uuid}/incidents\nGET /measurements/measurement-streams/incidents\nPOST /measurements/measurement-streams/acknowledgements\nGET /measurements/processors\nGET /measurements/processors/{name}\n\n## Thresholds\nGET /thresholds/patient-thresholds               ?patient= &max=\nPOST /thresholds/patient-thresholds\nGET /thresholds/patient-thresholds/{uuid}\nPUT /thresholds/patient-thresholds/{uuid}\nDELETE /thresholds/patient-thresholds/{uuid}\nGET /thresholds/patient-group-thresholds         ?max=\nPOST /thresholds/patient-group-thresholds\nGET /thresholds/patient-group-thresholds/{uuid}\nPUT /thresholds/patient-group-thresholds/{uuid}\nDELETE /thresholds/patient-group-thresholds/{uuid}\nPOST /thresholds/evaluation\n\n## Organizations\nGET /organizations/organizations\nGET /organizations/organizations/{uuid}\nPUT /organizations/organizations/{uuid}\nGET /organizations/organizations/{uuid}/metadata-fields\nGET /organizations/patients/{id}/metadata\nPUT /organizations/patients/{id}/metadata\n\n## Users & IDP\nGET /idp2/users/{id}\nPUT /idp2/users/{id}/locked\nDELETE /idp2/users/{id}/password\nGET /idp2/roles\nGET /idp2/permissions\n\n## Patient Groups\nGET /clinician/api/patientgroups                 ?max= &offset=\nGET /clinician/api/patientgroups/{id}\nPOST /clinician/api/patientgroups\nPUT /clinician/api/patientgroups/{id}\nDELETE /clinician/api/patientgroups/{id}\n\n## Audit\nGET /audit/resources/{resourceUrl}               ?max= &offset=\n\n## Calendar\nGET /calendar/events                             ?patient= &from= &to=\nPOST /calendar/events\nGET /calendar/events/{uuid}\nPUT /calendar/events/{uuid}\nDELETE /calendar/events/{uuid}\n\n## Chat\nGET /chat/threads                                ?patient=\nGET /chat/threads/{uuid}\nGET /chat/threads/{uuid}/messages\nPOST /chat/threads/{uuid}/read\nPOST /chat/messages\nGET /chat/messages/{uuid}\nPOST /chat/messages/{uuid}/read\nGET /chat/snippets\nPOST /chat/snippets\nPUT /chat/snippets/{uuid}\nDELETE /chat/snippets/{uuid}\n\n## Notifications\nGET /notifications/devices                       ?user=\nPOST /notifications/devices\nGET /notifications/subscriptions\nPOST /notifications/subscriptions\nDELETE /notifications/subscriptions/{uuid}\n\n## Mutation Request Bodies\n\nPOST /clinician/api/patients\n  required: uniqueId, username, firstName, lastName, sex(male|female|unknown),\n            address, postalCode, city, links.patientGroups[uri...]\n  optional: dateOfBirth(YYYY-MM-DD), phone, mobilePhone, email, comment,\n            dueDate, profilePicture, place, relatives[{firstName,lastName,relation,phone}]\n\nPUT /clinician/api/patients/{id}\n  same fields as create, all optional except links.patientGroups\n\nPOST /clinician/api/clinicians\n  required: username, firstName, lastName, links.patientGroups[uri...], links.roles[uri...]\n  optional: email, phone, mobilePhone, uniqueId\n\nPOST /clinician/api/patient-notes\n  required: note, type(normal|important), links.patient(uri)\n  optional: reminderDate(date-time)\n\nPOST /clinician/api/patientgroups\n  required: name, messagingEnabled, blueAlarmsEnabled, links.organization(uri)\n  optional: dueDateVisible, calculateBloodPressureWeeklyAverage, copdPrediction\n\nPOST /clinician/api/patients/{id}/questionnaire_schedules\n  required: links.questionnaireDefinition(uri)\n  optional: scheduledTime (varies by type \u2014 WEEKDAYS, MONTHLY, EVERY_NTH_DAY, SPECIFIC_DATE, etc.)\n\nPOST /measurements/measurement-captures\n  required: source, sourceId, captureTime(date-time), measurements[], links.patient(uri)\n  optional: historic\n  note: source+sourceId must be unique per capture\n\nPOST /chat/messages\n  required: body, links.organization(uri)\n  variant 1: links.patient(uri), optional links.attachments[uri...]\n  variant 2: links.patientGroup(uri)\n\nPOST /calendar/events\n  required: type, description, schedule.startTime(date-time),\n            party.clinicians[{links.clinician(uri)}],\n            party.patients[{links.patient(uri)}],\n            links.origin(uri)\n  optional: schedule.endTime(date-time), party.name\n\n## Notes\n- Dates use ISO 8601: 2024-01-01T00:00:00.000Z\n- Default max is 100, default offset is 0\n- All list endpoints support pagination via max/offset\n- Clinician-service resources use numeric {id}; other services use {uuid}\n- Links are always absolute URIs: https://doccla-dev.oth.io/clinician/api/patients/123\n- Schemas discoverable via each service's root links.schemas; filenames vary by endpoint\n";
+export declare const API_GUIDE = "# OTH API Endpoint Reference\n\n## Key Concepts\n\nLinks are the API's primary navigation mechanism. Every response includes a\nlinks object with absolute URIs. Use these as-is for subsequent requests \u2014\nnever construct URLs from IDs manually. Foreign key references (e.g. patient\nin a measurement, patientGroups in a patient) are always link URIs, not bare IDs.\n\nAuth: the MCP server handles auth transparently. For reference, most read\nendpoints and questionnaire submission accept Basic auth. Acknowledgements,\nignored, and manual measurement-captures require a clinician-scoped Bearer JWT\nobtained via POST /idp2/tokens.\n\n## Common Workflows\n\nReview results:\n  GET /clinician/api/patients?uniqueId={nhsNo}\n  GET /results/results?patient={patient-link}&acknowledged=false\n  GET {result-link}\n  PUT {result-link}/acknowledgement  (Bearer JWT required)\n\nSubmit questionnaire response:\n  GET /clinician/api/questionnaire_definitions/{id}\n  GET {links.activeQuestionnaire}  (extract node names from response)\n  POST {questionnaire-link}/results\n    {version:\"1.0\", date:ISO-8601, links:{patient:uri},\n     output:[{name:\"{nodeName}.FIELD\", type:\"Integer\"|\"Float\"|\"Object\"|\"Boolean\", value:<typed>}]}\n\nSubmit measurement (clinician-entered):\n  POST /measurements/measurement-captures\n    {source, sourceId, captureTime, links:{patient:uri},\n     measurements:[{type, timestamp, measurement:{<type-specific>},\n       origin:{manualMeasurement:{enteredBy} | deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier}}}]}\n  Common types: blood_pressure({systolic,diastolic,unit}), pulse({value,unit}),\n    saturation({value,unit}), temperature({value,unit}), weight(Float)\n\nPatient lifecycle:\n  POST /clinician/api/patients  (with links.patientGroups)\n  GET+PUT /organizations/patients/{id}/metadata  (PUT replaces entire set \u2014 GET first, merge, then PUT)\n  PUT /clinician/api/patients/{id}  (status:\"discharged\")\n\n## Patients\nGET /clinician/api/patients                     ?uniqueId= &username= &firstName= &lastName= &search= &phone= &patientGroup= &id= &status= &select= &max= &offset=\nGET /clinician/api/patients/{id}\nGET /clinician/api/patients/me\nGET /clinician/api/patients/{id}/measurements           ?from= &to= &max=\nGET /clinician/api/patients/{id}/measurements/aggregate\nGET /clinician/api/patients/{id}/measurement-types\nGET /clinician/api/patients/{id}/questionnaires\nGET /clinician/api/patients/{id}/questionnaire_schedules\nPOST /clinician/api/patients/{id}/questionnaire_schedules\nGET /clinician/api/patients/{id}/contact-info\nPUT /clinician/api/patients/{id}/contact-info\nGET /clinician/api/patients/{id}/acknowledgements\n  status enum: all|active|inactive|discharged|discharged_self_managed|deceased (default: active)\n  patientGroup and id are repeatable (up to 100\u00D7) for batch queries\n  search matches across firstName, lastName, uniqueId, username\n\n## Clinicians\nGET /clinician/api/clinicians                    ?max= &offset=\nPOST /clinician/api/clinicians\nGET /clinician/api/clinicians/{id}\nPUT /clinician/api/clinicians/{id}\nGET /clinician/api/clinicians/me\nGET /clinician/api/clinicians/me/colleagues\n\n## Questionnaire Definitions\nGET /clinician/api/questionnaire_definitions     ?max= &offset=\nGET /clinician/api/questionnaire_definitions/{id}\nPOST /clinician/api/questionnaire_definitions    {name, requiresManualInspection}\nPUT /clinician/api/questionnaire_definitions/{id}\n\n## Questionnaires (node graph)\nGET /clinician/api/questionnaires/{id}\nPOST /clinician/api/questionnaires/{id}/results\n\n## Results\nGET /results/results                             ?patient= &acknowledged= &resultType= &questionnaire= &order= &from= &to= &max=\nGET /results/results/{uuid}\nPUT /results/results/{uuid}/acknowledgement      (Bearer JWT required)\nPUT /results/results/{uuid}/ignored              (Bearer JWT required)\n\n## Questionnaire Schedules\nGET /clinician/api/questionnaire_schedules       ?max= &offset=\n\n## Questionnaire Groups\nGET /questionnaires/questionnaire-groups         ?max=\nPOST /questionnaires/questionnaire-groups        {name, questionnaireDefinitions}\n\n## Patient Notes\nGET /clinician/api/patient-notes                 ?max= &offset=\nPOST /clinician/api/patient-notes\nGET /clinician/api/patient-notes/{id}\nPUT /clinician/api/patient-notes/{id}\nDELETE /clinician/api/patient-notes/{id}\nPOST /clinician/api/patient-notes/{id}/read\n\n## Measurements\nGET /measurements/measurement-types\nGET /measurements/measurement-captures           ?patient= &source= &since= &from= &to= &max=\nPOST /measurements/measurement-captures\nGET /measurements/measurement-captures/{uuid}\nPOST /measurements/measurement-captures/{uuid}/measurements\nGET /measurements/measurement-streams            ?patient= &patientGroup= &from= &to= &max=\nPOST /measurements/measurement-streams\nGET /measurements/measurement-streams/{uuid}\nGET /measurements/measurement-streams/{uuid}/measurements\nGET /measurements/measurement-streams/{uuid}/incidents\nGET /measurements/measurement-streams/incidents\nPOST /measurements/measurement-streams/acknowledgements\nGET /measurements/processors\nGET /measurements/processors/{name}\n\n## Thresholds\nGET /thresholds/patient-thresholds               ?patient= &max=\nPOST /thresholds/patient-thresholds\nGET /thresholds/patient-thresholds/{uuid}\nPUT /thresholds/patient-thresholds/{uuid}\nDELETE /thresholds/patient-thresholds/{uuid}\nGET /thresholds/patient-group-thresholds         ?max=\nPOST /thresholds/patient-group-thresholds\nGET /thresholds/patient-group-thresholds/{uuid}\nPUT /thresholds/patient-group-thresholds/{uuid}\nDELETE /thresholds/patient-group-thresholds/{uuid}\nPOST /thresholds/evaluation\n\n## Organizations\nGET /organizations/organizations\nGET /organizations/organizations/{uuid}\nPUT /organizations/organizations/{uuid}\nGET /organizations/organizations/{uuid}/metadata-fields\nGET /organizations/patients/{id}/metadata\nPUT /organizations/patients/{id}/metadata         (replaces entire set \u2014 GET first, merge, then PUT)\n\n## Object Storage\nPOST /object-storage/objects                      (raw body, set Content-Type header)\nGET /object-storage/objects/{uuid}\n\n## Users & IDP\nPOST /idp2/tokens                                (Basic auth, body: {links:{clinician:uri}}) \u2192 201 {token}\nGET /idp2/users/{id}\nPUT /idp2/users/{id}/locked\nDELETE /idp2/users/{id}/password\nGET /idp2/roles\nGET /idp2/permissions\n\n## Patient Groups\nGET /clinician/api/patientgroups                 ?max= &offset=\nGET /clinician/api/patientgroups/{id}\nPOST /clinician/api/patientgroups\nPUT /clinician/api/patientgroups/{id}\nDELETE /clinician/api/patientgroups/{id}\n\n## Audit\nGET /audit/resources/{resourceUrl}               ?max= &offset=\n\n## Calendar\nGET /calendar/events                             ?patient= &from= &to=\nPOST /calendar/events\nGET /calendar/events/{uuid}\nPUT /calendar/events/{uuid}\nDELETE /calendar/events/{uuid}\n\n## Chat\nGET /chat/threads                                ?patient=\nGET /chat/threads/{uuid}\nGET /chat/threads/{uuid}/messages\nPOST /chat/threads/{uuid}/read\nPOST /chat/messages\nGET /chat/messages/{uuid}\nPOST /chat/messages/{uuid}/read\nGET /chat/snippets\nPOST /chat/snippets\nPUT /chat/snippets/{uuid}\nDELETE /chat/snippets/{uuid}\n\n## Notifications\nGET /notifications/devices                       ?user=\nPOST /notifications/devices\nGET /notifications/subscriptions\nPOST /notifications/subscriptions\nDELETE /notifications/subscriptions/{uuid}\n\n## Mutation Request Bodies\n\nPOST /clinician/api/patients\n  required: uniqueId, username, firstName, lastName, sex(male|female|unknown),\n            address, postalCode, city, links.patientGroups[uri...]\n  optional: dateOfBirth(YYYY-MM-DD), phone, mobilePhone, email, comment,\n            dueDate, profilePicture, place, relatives[{firstName,lastName,relation,phone}]\n\nPUT /clinician/api/patients/{id}\n  same fields as create, all optional except links.patientGroups\n\nPOST /clinician/api/clinicians\n  required: username, firstName, lastName, links.patientGroups[uri...], links.roles[uri...]\n  optional: email, phone, mobilePhone, uniqueId\n\nPOST /clinician/api/patient-notes\n  required: note, type(normal|important), links.patient(uri)\n  optional: reminderDate(date-time)\n\nPOST /clinician/api/patientgroups\n  required: name, messagingEnabled, blueAlarmsEnabled, links.organization(uri)\n  optional: dueDateVisible, calculateBloodPressureWeeklyAverage, copdPrediction\n\nPOST /clinician/api/patients/{id}/questionnaire_schedules\n  required: links.questionnaireDefinition(uri)\n  optional: scheduledTime (varies by type \u2014 WEEKDAYS, MONTHLY, EVERY_NTH_DAY, SPECIFIC_DATE, etc.)\n\nPOST /measurements/measurement-captures\n  required: source, sourceId, captureTime(date-time), links.patient(uri),\n            measurements[{type, timestamp, measurement:{<type-specific fields>},\n              origin:{manualMeasurement:{enteredBy} | deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier}}}]\n  optional: historic\n  note: source+sourceId must be unique per capture\n\nPOST /measurements/measurement-streams\n  required: inputType(e.g. \"discrete\"), links.patient(uri),\n            measurements[{type, timestamp, measurement:{value,unit},\n              origin:{deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier:{macAddress}}}}]\n\nPUT /results/results/{uuid}/acknowledgement\n  required: note, date(date-time), visibleForPatient(bool)\n  optional: closureNotes[string...]\n\nPUT /results/results/{uuid}/ignored\n  required: replyIds[string...]  (empty array to unignore)\n  optional: reason\n\nPOST /chat/messages\n  required: body, links.organization(uri)\n  variant 1: links.patient(uri), optional links.attachments[uri...]\n  variant 2: links.patientGroup(uri)\n\nPOST /calendar/events\n  required: type, description, schedule.startTime(date-time),\n            party.clinicians[{links.clinician(uri)}],\n            party.patients[{links.patient(uri)}],\n            links.origin(uri)\n  optional: schedule.endTime(date-time), party.name\n\n## Notes\n- Dates use ISO 8601: 2024-01-01T00:00:00.000Z\n- Default max is 100, default offset is 0\n- All list endpoints support pagination via max/offset\n- Clinician-service resources use numeric {id}; other services use {uuid}\n- Links are always absolute URIs: https://doccla-dev.oth.io/clinician/api/patients/123\n- Schemas discoverable via each service's root links.schemas; filenames vary by endpoint\n";

package/dist/api-guide.js

@@ -1,19 +1,61 @@
 export const API_GUIDE = `# OTH API Endpoint Reference
 
+## Key Concepts
+
+Links are the API's primary navigation mechanism. Every response includes a
+links object with absolute URIs. Use these as-is for subsequent requests —
+never construct URLs from IDs manually. Foreign key references (e.g. patient
+in a measurement, patientGroups in a patient) are always link URIs, not bare IDs.
+
+Auth: the MCP server handles auth transparently. For reference, most read
+endpoints and questionnaire submission accept Basic auth. Acknowledgements,
+ignored, and manual measurement-captures require a clinician-scoped Bearer JWT
+obtained via POST /idp2/tokens.
+
+## Common Workflows
+
+Review results:
+  GET /clinician/api/patients?uniqueId={nhsNo}
+  GET /results/results?patient={patient-link}&acknowledged=false
+  GET {result-link}
+  PUT {result-link}/acknowledgement  (Bearer JWT required)
+
+Submit questionnaire response:
+  GET /clinician/api/questionnaire_definitions/{id}
+  GET {links.activeQuestionnaire}  (extract node names from response)
+  POST {questionnaire-link}/results
+    {version:"1.0", date:ISO-8601, links:{patient:uri},
+     output:[{name:"{nodeName}.FIELD", type:"Integer"|"Float"|"Object"|"Boolean", value:<typed>}]}
+
+Submit measurement (clinician-entered):
+  POST /measurements/measurement-captures
+    {source, sourceId, captureTime, links:{patient:uri},
+     measurements:[{type, timestamp, measurement:{<type-specific>},
+       origin:{manualMeasurement:{enteredBy} | deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier}}}]}
+  Common types: blood_pressure({systolic,diastolic,unit}), pulse({value,unit}),
+    saturation({value,unit}), temperature({value,unit}), weight(Float)
+
+Patient lifecycle:
+  POST /clinician/api/patients  (with links.patientGroups)
+  GET+PUT /organizations/patients/{id}/metadata  (PUT replaces entire set — GET first, merge, then PUT)
+  PUT /clinician/api/patients/{id}  (status:"discharged")
+
 ## Patients
-GET /clinician/api/patients                     ?username= &firstName= &lastName= &uniqueId= &status= &max= &offset=
+GET /clinician/api/patients                     ?uniqueId= &username= &firstName= &lastName= &search= &phone= &patientGroup= &id= &status= &select= &max= &offset=
 GET /clinician/api/patients/{id}
 GET /clinician/api/patients/me
 GET /clinician/api/patients/{id}/measurements           ?from= &to= &max=
 GET /clinician/api/patients/{id}/measurements/aggregate
 GET /clinician/api/patients/{id}/measurement-types
 GET /clinician/api/patients/{id}/questionnaires
-GET /clinician/api/patients/{id}/questionnaire-results  ?from= &to= &max=
 GET /clinician/api/patients/{id}/questionnaire_schedules
 POST /clinician/api/patients/{id}/questionnaire_schedules
 GET /clinician/api/patients/{id}/contact-info
 PUT /clinician/api/patients/{id}/contact-info
 GET /clinician/api/patients/{id}/acknowledgements
+  status enum: all|active|inactive|discharged|discharged_self_managed|deceased (default: active)
+  patientGroup and id are repeatable (up to 100×) for batch queries
+  search matches across firstName, lastName, uniqueId, username
 
 ## Clinicians
 GET /clinician/api/clinicians                    ?max= &offset=
@@ -33,9 +75,11 @@ PUT /clinician/api/questionnaire_definitions/{id}
 GET /clinician/api/questionnaires/{id}
 POST /clinician/api/questionnaires/{id}/results
 
-## Questionnaire Results
-GET /clinician/api/questionnaire-results         ?from= &to= &max= &offset=
-GET /clinician/api/questionnaire-results/{id}
+## Results
+GET /results/results                             ?patient= &acknowledged= &resultType= &questionnaire= &order= &from= &to= &max=
+GET /results/results/{uuid}
+PUT /results/results/{uuid}/acknowledgement      (Bearer JWT required)
+PUT /results/results/{uuid}/ignored              (Bearer JWT required)
 
 ## Questionnaire Schedules
 GET /clinician/api/questionnaire_schedules       ?max= &offset=
@@ -54,11 +98,11 @@ POST /clinician/api/patient-notes/{id}/read
 
 ## Measurements
 GET /measurements/measurement-types
-GET /measurements/measurement-captures           ?patient= &from= &to= &max=
+GET /measurements/measurement-captures           ?patient= &source= &since= &from= &to= &max=
 POST /measurements/measurement-captures
 GET /measurements/measurement-captures/{uuid}
 POST /measurements/measurement-captures/{uuid}/measurements
-GET /measurements/measurement-streams            ?patient= &from= &to= &max=
+GET /measurements/measurement-streams            ?patient= &patientGroup= &from= &to= &max=
 POST /measurements/measurement-streams
 GET /measurements/measurement-streams/{uuid}
 GET /measurements/measurement-streams/{uuid}/measurements
@@ -87,9 +131,14 @@ GET /organizations/organizations/{uuid}
 PUT /organizations/organizations/{uuid}
 GET /organizations/organizations/{uuid}/metadata-fields
 GET /organizations/patients/{id}/metadata
-PUT /organizations/patients/{id}/metadata
+PUT /organizations/patients/{id}/metadata         (replaces entire set — GET first, merge, then PUT)
+
+## Object Storage
+POST /object-storage/objects                      (raw body, set Content-Type header)
+GET /object-storage/objects/{uuid}
 
 ## Users & IDP
+POST /idp2/tokens                                (Basic auth, body: {links:{clinician:uri}}) → 201 {token}
 GET /idp2/users/{id}
 PUT /idp2/users/{id}/locked
 DELETE /idp2/users/{id}/password
@@ -161,10 +210,25 @@ POST /clinician/api/patients/{id}/questionnaire_schedules
   optional: scheduledTime (varies by type — WEEKDAYS, MONTHLY, EVERY_NTH_DAY, SPECIFIC_DATE, etc.)
 
 POST /measurements/measurement-captures
-  required: source, sourceId, captureTime(date-time), measurements[], links.patient(uri)
+  required: source, sourceId, captureTime(date-time), links.patient(uri),
+            measurements[{type, timestamp, measurement:{<type-specific fields>},
+              origin:{manualMeasurement:{enteredBy} | deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier}}}]
   optional: historic
   note: source+sourceId must be unique per capture
 
+POST /measurements/measurement-streams
+  required: inputType(e.g. "discrete"), links.patient(uri),
+            measurements[{type, timestamp, measurement:{value,unit},
+              origin:{deviceMeasurement:{connectionType,manufacturer,model,primaryDeviceIdentifier:{macAddress}}}}]
+
+PUT /results/results/{uuid}/acknowledgement
+  required: note, date(date-time), visibleForPatient(bool)
+  optional: closureNotes[string...]
+
+PUT /results/results/{uuid}/ignored
+  required: replyIds[string...]  (empty array to unignore)
+  optional: reason
+
 POST /chat/messages
   required: body, links.organization(uri)
   variant 1: links.patient(uri), optional links.attachments[uri...]

package/dist/tools.js

@@ -10,12 +10,13 @@ export function registerTools(server, auth, client) {
         title: "OTH GET Request",
         description: `GET any OTH API endpoint. Auth handled automatically.
 Common paths:
-  /clinician/api/patients?username=&firstName=&max=
+  /clinician/api/patients?uniqueId=&search=&patientGroup=&status=&max=
   /clinician/api/patients/{id}
   /clinician/api/questionnaire_definitions?max=
   /clinician/api/questionnaires/{id}
-  /clinician/api/questionnaire-results?from=&to=&max=
-  /measurements/measurement-types
+  /results/results?patient=&acknowledged=&resultType=&max=
+  /results/results/{uuid}
+  /measurements/measurement-captures?patient=&source=&max=
   /organizations/organizations
 Read the oth://api-guide resource for full endpoint reference.`,
         annotations: {
@@ -67,7 +68,14 @@ Read the oth://api-guide resource for full endpoint reference.`,
     });
     server.registerTool("oth_mutate", {
         title: "OTH Mutate Request",
-        description: "POST, PUT, PATCH, or DELETE to any OTH API endpoint. Auth handled automatically.",
+        description: `POST, PUT, PATCH, or DELETE to any OTH API endpoint. Auth handled automatically.
+Common mutations:
+  PUT /results/results/{uuid}/acknowledgement  {note, date, visibleForPatient}
+  PUT /results/results/{uuid}/ignored          {replyIds[], reason}
+  POST /measurements/measurement-captures      {source, sourceId, captureTime, measurements[], links:{patient}}
+  POST /clinician/api/patients                 {uniqueId, username, firstName, lastName, sex, ...}
+  PUT /organizations/patients/{id}/metadata    (replaces entire set — GET first)
+Read the oth://api-guide resource for full endpoint reference.`,
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oth-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for the OTH (OpenTeleHealth) API",
   "type": "module",
   "bin": {