oth-mcp 0.1.5 → 0.1.6

package/README.md

@@ -99,7 +99,7 @@ Switch environment or check current state.
 
 ```
 oth_env({ environment: "stag" })
-oth_env({})  // show current env + auth state
+oth_env({})  // show current env, auth state, and the username calls run as
 ```
 
 ## Limitations

package/dist/api-guide.d.ts

@@ -1 +1 @@
-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  required: uniqueId, username, firstName, lastName, sex, address, postalCode, city,\n            status(active|inactive|discharged|discharged_self_managed|deceased),\n            links.patientGroups[uri...]\n  optional: dateOfBirth, phone, mobilePhone, email, comment, dueDate, profilePicture,\n            place, relatives[{firstName,lastName,relation,phone}]\n  note: PUT shape differs from GET \u2014 GET returns patientGroups as nested objects and\n        links with all navigation URIs; PUT expects only links.patientGroups as a flat\n        array of URIs. Omit fields rather than sending null \u2014 some null values are\n        stored as the string \"null\". uniqueId must be unique across the system;\n        duplicates return 422 \"Patient not replaced\".\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";
+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. Follow these rather than constructing URLs\nfrom IDs manually. Foreign key references (e.g. patient in a measurement,\npatientGroups in a patient) are always link URIs, not bare IDs.\n  - In request bodies, use link URIs exactly as returned.\n  - As the path for oth_get/oth_mutate, strip the origin and pass only the\n    path: absolute URLs are rejected. e.g. a link of\n    http://host.docker.internal:7100/clinician/api/patients/15\n    is requested as path /clinician/api/patients/15\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\nActing user: every call runs as the MCP's configured user (oth_env shows the\nusername), and is bound by that user's roles and patient groups. GET\n/clinician/api/clinicians/me shows both. Patient reads and writes are limited\nto that user's patient groups: e.g. creating a patient in a group the user is\nnot in returns 422 \"Clinician does not have access to patient group\".\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\nSet up an organization, patient group and role:\n  POST /organizations/organizations                {name, metadataFields:[]}\n  POST /clinician/api/patientgroups                (links.organization from the org's links.self)\n  POST /thresholds/patient-group-thresholds        (optional, per measurement type)\n  POST /idp2/roles                                 {name, permissions:[\"ROLE_...\"]}\n  PUT  /clinician/api/clinicians/{me-id}           add the new group to the acting user,\n                                                   so patients can be created in it\n\nCreate a clinician or patient that can log in:\n  POST /clinician/api/clinicians  or  POST /clinician/api/patients\n    \u2192 response includes temporaryPassword; the account cannot be used until\n      its password is changed\n  POST /idp2/users/auth  as that user (see Users & IDP): NOT possible through\n    the MCP, which always authenticates as its own user. Do it outside the MCP,\n    with a single request: repeated failed logins lock the account.\n\nCreate and publish a questionnaire:\n  POST /clinician/api/questionnaire_definitions    {name, requiresManualInspection}\n    \u2192 links.self ends in the definition's numeric id\n  POST /clinician/api/questionnaire_definitions/{id}/draft\n    {active:true, nodes, connections, links:{creator:clinician-uri}}\n    \u2192 active:true publishes immediately (response has links.activeQuestionnaire);\n      active:false leaves a draft (links.draftQuestionnaire)\n\nCheck or fix a user's login state (no login attempt needed):\n  GET /idp2/users?url={clinician-or-patient-uri}   \u2192 users[].links.user\n  GET {links.user}                                 accountLocked, temporaryPassword,\n                                                   passwordExpired, passwordLastChanged\n  PUT {links.user}/locked                          {accountLocked:false}\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                    ?username= &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, nameShownToPatient?, requiresManualInspection}\nPUT /clinician/api/questionnaire_definitions/{id}\nPOST /clinician/api/questionnaire_definitions/{id}/draft   (new version; see Mutation Request Bodies)\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\nPOST /organizations/organizations                 {name, metadataFields:[]}\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                                  ?url={clinician-or-patient-uri}  (find the idp2 user behind a clinician/patient)\nGET /idp2/users/{id}                             includes accountLocked, temporaryPassword, passwordExpired\nPUT /idp2/users/{id}/locked                      {accountLocked:bool}\nDELETE /idp2/users/{id}/password\nPOST /idp2/users/auth                            change own password: Basic auth as the user with their\n                                                 current (e.g. temporary) password, body {password:new}\n                                                 \u2192 200. Not usable via the MCP (it authenticates as itself).\nGET /idp2/roles\nPOST /idp2/roles                                 {name, permissions:[\"ROLE_PATIENT_READ\", ...]}\nGET /idp2/permissions                            permission names to use in roles\n\n  Lockout: repeated failed Basic auth attempts lock the account (\"Account locked\n  for user ...\"). Check state with GET /idp2/users/{id}, unlock with PUT .../locked.\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  note: the acting user must belong to every group in links.patientGroups (else 422).\n        Response includes temporaryPassword (see Common Workflows).\n\nPUT /clinician/api/patients/{id}\n  required: uniqueId, username, firstName, lastName, sex, address, postalCode, city,\n            status(active|inactive|discharged|discharged_self_managed|deceased),\n            links.patientGroups[uri...]\n  optional: dateOfBirth, phone, mobilePhone, email, comment, dueDate, profilePicture,\n            place, relatives[{firstName,lastName,relation,phone}]\n  note: PUT shape differs from GET \u2014 GET returns patientGroups as nested objects and\n        links with all navigation URIs; PUT expects only links.patientGroups as a flat\n        array of URIs. Omit fields rather than sending null \u2014 some null values are\n        stored as the string \"null\". uniqueId must be unique across the system;\n        duplicates return 422 \"Patient not replaced\".\n\nPOST /clinician/api/clinicians\n  required: username, firstName, lastName, links.patientGroups[uri...], links.roles[uri...]\n  optional: email, phone, mobilePhone, uniqueId\n  note: response includes temporaryPassword (see Common Workflows).\n\nPUT /clinician/api/clinicians/{id}\n  send: firstName, lastName, username, email, uniqueId, phone, mobilePhone,\n        links.patientGroups[uri...], links.roles[uri...]\n  note: REPLACES the clinician. Any field left out is cleared (e.g. omitting\n        uniqueId sets it to null). GET first and send every field back; to add\n        a group, send the existing group URIs plus the new one (same for roles).\n\nPOST /thresholds/patient-group-thresholds\n  required: measurementType(e.g. \"saturation\"), links.patientGroup(uri),\n            limits[{name:\"value\", warningLow, warningHigh, alertLow, alertHigh}]  (null for unused),\n            thresholdType:{scope:\"point\", point:{type:\"absolute\"}}\n\nPOST /clinician/api/questionnaire_definitions/{id}/draft\n  required: active(bool: true publishes), nodes, connections\n  optional: links.creator(clinician uri)\n  nodes: object keyed by node id, e.g.\n    {\"start1\":{id:\"start1\", type:\"start\", position:{top,left}},\n     \"input2\":{id:\"input2\", type:\"input\", question, shortText, dataType:\"BOOLEAN\", position},\n     \"end5\":{id:\"end5\", type:\"end\", position}}\n  connections: [{source, target, type:\"normal\"|\"choice\", choiceValue?, severity:\"\"|\"RED\"|..., frozen?}]\n  note: this is the questionnaire editor's graph format (what its Export produces).\n        GET {links.activeQuestionnaire} returns a different, compiled form\n        (IONode/AssignmentNode/EndNode, nodes renumbered, e.g. \"input2\" becomes\n        \"31\") that cannot be posted back as a draft. Take output names for\n        result submission (e.g. \"31.FIELD\") from the compiled form.\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  (on local they use the gateway's external host, e.g. http://host.docker.internal:7100,\n  which can differ from the MCP's base URL; that is fine, use them as described above)\n- Schemas discoverable via each service's root links.schemas; filenames vary by endpoint\n";

package/dist/api-guide.js

@@ -3,15 +3,26 @@ 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.
+links object with absolute URIs. Follow these rather than constructing URLs
+from IDs manually. Foreign key references (e.g. patient in a measurement,
+patientGroups in a patient) are always link URIs, not bare IDs.
+  - In request bodies, use link URIs exactly as returned.
+  - As the path for oth_get/oth_mutate, strip the origin and pass only the
+    path: absolute URLs are rejected. e.g. a link of
+    http://host.docker.internal:7100/clinician/api/patients/15
+    is requested as path /clinician/api/patients/15
 
 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.
 
+Acting user: every call runs as the MCP's configured user (oth_env shows the
+username), and is bound by that user's roles and patient groups. GET
+/clinician/api/clinicians/me shows both. Patient reads and writes are limited
+to that user's patient groups: e.g. creating a patient in a group the user is
+not in returns 422 "Clinician does not have access to patient group".
+
 ## Common Workflows
 
 Review results:
@@ -40,6 +51,36 @@ Patient lifecycle:
   GET+PUT /organizations/patients/{id}/metadata  (PUT replaces entire set — GET first, merge, then PUT)
   PUT /clinician/api/patients/{id}  (status:"discharged")
 
+Set up an organization, patient group and role:
+  POST /organizations/organizations                {name, metadataFields:[]}
+  POST /clinician/api/patientgroups                (links.organization from the org's links.self)
+  POST /thresholds/patient-group-thresholds        (optional, per measurement type)
+  POST /idp2/roles                                 {name, permissions:["ROLE_..."]}
+  PUT  /clinician/api/clinicians/{me-id}           add the new group to the acting user,
+                                                   so patients can be created in it
+
+Create a clinician or patient that can log in:
+  POST /clinician/api/clinicians  or  POST /clinician/api/patients
+    → response includes temporaryPassword; the account cannot be used until
+      its password is changed
+  POST /idp2/users/auth  as that user (see Users & IDP): NOT possible through
+    the MCP, which always authenticates as its own user. Do it outside the MCP,
+    with a single request: repeated failed logins lock the account.
+
+Create and publish a questionnaire:
+  POST /clinician/api/questionnaire_definitions    {name, requiresManualInspection}
+    → links.self ends in the definition's numeric id
+  POST /clinician/api/questionnaire_definitions/{id}/draft
+    {active:true, nodes, connections, links:{creator:clinician-uri}}
+    → active:true publishes immediately (response has links.activeQuestionnaire);
+      active:false leaves a draft (links.draftQuestionnaire)
+
+Check or fix a user's login state (no login attempt needed):
+  GET /idp2/users?url={clinician-or-patient-uri}   → users[].links.user
+  GET {links.user}                                 accountLocked, temporaryPassword,
+                                                   passwordExpired, passwordLastChanged
+  PUT {links.user}/locked                          {accountLocked:false}
+
 ## Patients
 GET /clinician/api/patients                     ?uniqueId= &username= &firstName= &lastName= &search= &phone= &patientGroup= &id= &status= &select= &max= &offset=
 GET /clinician/api/patients/{id}
@@ -58,7 +99,7 @@ GET /clinician/api/patients/{id}/acknowledgements
   search matches across firstName, lastName, uniqueId, username
 
 ## Clinicians
-GET /clinician/api/clinicians                    ?max= &offset=
+GET /clinician/api/clinicians                    ?username= &max= &offset=
 POST /clinician/api/clinicians
 GET /clinician/api/clinicians/{id}
 PUT /clinician/api/clinicians/{id}
@@ -68,8 +109,9 @@ GET /clinician/api/clinicians/me/colleagues
 ## Questionnaire Definitions
 GET /clinician/api/questionnaire_definitions     ?max= &offset=
 GET /clinician/api/questionnaire_definitions/{id}
-POST /clinician/api/questionnaire_definitions    {name, requiresManualInspection}
+POST /clinician/api/questionnaire_definitions    {name, nameShownToPatient?, requiresManualInspection}
 PUT /clinician/api/questionnaire_definitions/{id}
+POST /clinician/api/questionnaire_definitions/{id}/draft   (new version; see Mutation Request Bodies)
 
 ## Questionnaires (node graph)
 GET /clinician/api/questionnaires/{id}
@@ -127,6 +169,7 @@ POST /thresholds/evaluation
 
 ## Organizations
 GET /organizations/organizations
+POST /organizations/organizations                 {name, metadataFields:[]}
 GET /organizations/organizations/{uuid}
 PUT /organizations/organizations/{uuid}
 GET /organizations/organizations/{uuid}/metadata-fields
@@ -139,11 +182,19 @@ 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
+GET /idp2/users                                  ?url={clinician-or-patient-uri}  (find the idp2 user behind a clinician/patient)
+GET /idp2/users/{id}                             includes accountLocked, temporaryPassword, passwordExpired
+PUT /idp2/users/{id}/locked                      {accountLocked:bool}
 DELETE /idp2/users/{id}/password
+POST /idp2/users/auth                            change own password: Basic auth as the user with their
+                                                 current (e.g. temporary) password, body {password:new}
+                                                 → 200. Not usable via the MCP (it authenticates as itself).
 GET /idp2/roles
-GET /idp2/permissions
+POST /idp2/roles                                 {name, permissions:["ROLE_PATIENT_READ", ...]}
+GET /idp2/permissions                            permission names to use in roles
+
+  Lockout: repeated failed Basic auth attempts lock the account ("Account locked
+  for user ..."). Check state with GET /idp2/users/{id}, unlock with PUT .../locked.
 
 ## Patient Groups
 GET /clinician/api/patientgroups                 ?max= &offset=
@@ -189,6 +240,8 @@ POST /clinician/api/patients
             address, postalCode, city, links.patientGroups[uri...]
   optional: dateOfBirth(YYYY-MM-DD), phone, mobilePhone, email, comment,
             dueDate, profilePicture, place, relatives[{firstName,lastName,relation,phone}]
+  note: the acting user must belong to every group in links.patientGroups (else 422).
+        Response includes temporaryPassword (see Common Workflows).
 
 PUT /clinician/api/patients/{id}
   required: uniqueId, username, firstName, lastName, sex, address, postalCode, city,
@@ -205,6 +258,33 @@ PUT /clinician/api/patients/{id}
 POST /clinician/api/clinicians
   required: username, firstName, lastName, links.patientGroups[uri...], links.roles[uri...]
   optional: email, phone, mobilePhone, uniqueId
+  note: response includes temporaryPassword (see Common Workflows).
+
+PUT /clinician/api/clinicians/{id}
+  send: firstName, lastName, username, email, uniqueId, phone, mobilePhone,
+        links.patientGroups[uri...], links.roles[uri...]
+  note: REPLACES the clinician. Any field left out is cleared (e.g. omitting
+        uniqueId sets it to null). GET first and send every field back; to add
+        a group, send the existing group URIs plus the new one (same for roles).
+
+POST /thresholds/patient-group-thresholds
+  required: measurementType(e.g. "saturation"), links.patientGroup(uri),
+            limits[{name:"value", warningLow, warningHigh, alertLow, alertHigh}]  (null for unused),
+            thresholdType:{scope:"point", point:{type:"absolute"}}
+
+POST /clinician/api/questionnaire_definitions/{id}/draft
+  required: active(bool: true publishes), nodes, connections
+  optional: links.creator(clinician uri)
+  nodes: object keyed by node id, e.g.
+    {"start1":{id:"start1", type:"start", position:{top,left}},
+     "input2":{id:"input2", type:"input", question, shortText, dataType:"BOOLEAN", position},
+     "end5":{id:"end5", type:"end", position}}
+  connections: [{source, target, type:"normal"|"choice", choiceValue?, severity:""|"RED"|..., frozen?}]
+  note: this is the questionnaire editor's graph format (what its Export produces).
+        GET {links.activeQuestionnaire} returns a different, compiled form
+        (IONode/AssignmentNode/EndNode, nodes renumbered, e.g. "input2" becomes
+        "31") that cannot be posted back as a draft. Take output names for
+        result submission (e.g. "31.FIELD") from the compiled form.
 
 POST /clinician/api/patient-notes
   required: note, type(normal|important), links.patient(uri)
@@ -256,5 +336,7 @@ POST /calendar/events
 - All list endpoints support pagination via max/offset
 - Clinician-service resources use numeric {id}; other services use {uuid}
 - Links are always absolute URIs: https://doccla-dev.oth.io/clinician/api/patients/123
+  (on local they use the gateway's external host, e.g. http://host.docker.internal:7100,
+  which can differ from the MCP's base URL; that is fine, use them as described above)
 - Schemas discoverable via each service's root links.schemas; filenames vary by endpoint
 `;

package/dist/auth.d.ts

@@ -11,9 +11,7 @@ export declare class AuthManager {
     get environment(): Environment;
     get baseUrl(): string;
     get isAuthenticated(): boolean;
-    get userInfo(): {
-        username: string | null;
-    } | null;
+    configuredUsername(): Promise<string | null>;
     switchEnvironment(env: Environment): void;
     getToken(): Promise<string>;
     private isExpiringSoon;

package/dist/auth.js

@@ -35,10 +35,16 @@ export class AuthManager {
     get isAuthenticated() {
         return this.state !== null;
     }
-    get userInfo() {
-        if (!this.state)
+    // The user calls will run as, without authenticating. Null if no credentials are configured.
+    async configuredUsername() {
+        if (this.state)
+            return this.state.username;
+        try {
+            return (await this.resolveCredentials()).username;
+        }
+        catch {
             return null;
-        return { username: this.state.username };
+        }
     }
     switchEnvironment(env) {
         if (env === this.env)

package/dist/client.d.ts

@@ -3,7 +3,7 @@ export declare class OthClient {
     private auth;
     constructor(auth: AuthManager);
     get(path: string, query?: Record<string, string>): Promise<unknown>;
-    mutate(method: "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: Record<string, unknown>): Promise<unknown>;
+    mutate(method: "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: Record<string, unknown> | unknown[]): Promise<unknown>;
     private validatePath;
     private buildUrl;
     private processResponse;

package/dist/tools.js

@@ -89,9 +89,9 @@ Read the oth://api-guide resource for full endpoint reference.`,
                 .describe("HTTP method"),
             path: z.string().describe("API path"),
             body: z
-                .record(z.unknown())
+                .union([z.record(z.unknown()), z.array(z.unknown())])
                 .optional()
-                .describe("Request body (JSON)"),
+                .describe("Request body (JSON object or array)"),
         },
     }, async ({ method, path, body }) => {
         try {
@@ -124,7 +124,7 @@ Read the oth://api-guide resource for full endpoint reference.`,
     });
     server.registerTool("oth_env", {
         title: "OTH Environment",
-        description: "Switch OTH environment or show current state. Returns environment, base URL, and authenticated user info.",
+        description: "Switch OTH environment or show current state. Returns environment, base URL, whether a login has happened yet, and the username every call runs as (known before the first login). Calls are limited to that user's roles and patient groups.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -145,10 +145,8 @@ Read the oth://api-guide resource for full endpoint reference.`,
             environment: auth.environment,
             baseUrl: auth.baseUrl,
             authenticated: auth.isAuthenticated,
+            user: { username: await auth.configuredUsername() },
         };
-        if (auth.isAuthenticated) {
-            info.user = auth.userInfo;
-        }
         return {
             content: [
                 { type: "text", text: JSON.stringify(info, null, 2) },

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "oth-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "MCP server for the OTH (OpenTeleHealth) API",
   "type": "module",
   "bin": {
-    "oth-mcp": "./dist/index.js"
+    "oth-mcp": "dist/index.js"
   },
   "files": [
     "dist"