oth-mcp 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# 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.
+
+## Setup
+
+### 1. Configure credentials
+
+**Environment variables** (works everywhere):
+
+```bash
+export OTH_USERNAME="your-username"
+export OTH_PASSWORD="your-password"
+export OTH_ENV="dev"  # optional, defaults to dev
+```
+
+**macOS Keychain** (no plaintext on disk):
+
+```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
+```
+
+### 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"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `oth_get`
+
+GET any OTH API endpoint. Common paths are listed in the tool description; read the `oth://api-guide` resource for the full reference.
+
+```
+oth_get({ path: "/clinician/api/patients", query: { max: "10" } })
+```
+
+### `oth_mutate`
+
+POST, PUT, PATCH, or DELETE to any OTH API endpoint.
+
+```
+oth_mutate({ method: "POST", path: "/clinician/api/patient-notes", body: { note: "Test", type: "normal", links: { patient: "https://doccla-dev.oth.io/clinician/api/patients/123" } } })
+```
+
+### `oth_env`
+
+Switch environment or check current state.
+
+```
+oth_env({ environment: "stag" })
+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.

package/dist/api-guide.d.ts

@@ -0,0 +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";

package/dist/api-guide.js

@@ -0,0 +1,187 @@
+export const API_GUIDE = `# OTH API Endpoint Reference
+
+## Patients
+GET /clinician/api/patients                     ?username= &firstName= &lastName= &uniqueId= &status= &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
+
+## Clinicians
+GET /clinician/api/clinicians                    ?max= &offset=
+POST /clinician/api/clinicians
+GET /clinician/api/clinicians/{id}
+PUT /clinician/api/clinicians/{id}
+GET /clinician/api/clinicians/me
+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}
+PUT /clinician/api/questionnaire_definitions/{id}
+
+## Questionnaires (node graph)
+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}
+
+## Questionnaire Schedules
+GET /clinician/api/questionnaire_schedules       ?max= &offset=
+
+## Questionnaire Groups
+GET /questionnaires/questionnaire-groups         ?max=
+POST /questionnaires/questionnaire-groups        {name, questionnaireDefinitions}
+
+## Patient Notes
+GET /clinician/api/patient-notes                 ?max= &offset=
+POST /clinician/api/patient-notes
+GET /clinician/api/patient-notes/{id}
+PUT /clinician/api/patient-notes/{id}
+DELETE /clinician/api/patient-notes/{id}
+POST /clinician/api/patient-notes/{id}/read
+
+## Measurements
+GET /measurements/measurement-types
+GET /measurements/measurement-captures           ?patient= &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=
+POST /measurements/measurement-streams
+GET /measurements/measurement-streams/{uuid}
+GET /measurements/measurement-streams/{uuid}/measurements
+GET /measurements/measurement-streams/{uuid}/incidents
+GET /measurements/measurement-streams/incidents
+POST /measurements/measurement-streams/acknowledgements
+GET /measurements/processors
+GET /measurements/processors/{name}
+
+## Thresholds
+GET /thresholds/patient-thresholds               ?patient= &max=
+POST /thresholds/patient-thresholds
+GET /thresholds/patient-thresholds/{uuid}
+PUT /thresholds/patient-thresholds/{uuid}
+DELETE /thresholds/patient-thresholds/{uuid}
+GET /thresholds/patient-group-thresholds         ?max=
+POST /thresholds/patient-group-thresholds
+GET /thresholds/patient-group-thresholds/{uuid}
+PUT /thresholds/patient-group-thresholds/{uuid}
+DELETE /thresholds/patient-group-thresholds/{uuid}
+POST /thresholds/evaluation
+
+## Organizations
+GET /organizations/organizations
+GET /organizations/organizations/{uuid}
+PUT /organizations/organizations/{uuid}
+GET /organizations/organizations/{uuid}/metadata-fields
+GET /organizations/patients/{id}/metadata
+PUT /organizations/patients/{id}/metadata
+
+## Users & IDP
+GET /idp2/users/{id}
+PUT /idp2/users/{id}/locked
+DELETE /idp2/users/{id}/password
+GET /idp2/roles
+GET /idp2/permissions
+
+## Patient Groups
+GET /clinician/api/patientgroups                 ?max= &offset=
+GET /clinician/api/patientgroups/{id}
+POST /clinician/api/patientgroups
+PUT /clinician/api/patientgroups/{id}
+DELETE /clinician/api/patientgroups/{id}
+
+## Audit
+GET /audit/resources/{resourceUrl}               ?max= &offset=
+
+## Calendar
+GET /calendar/events                             ?patient= &from= &to=
+POST /calendar/events
+GET /calendar/events/{uuid}
+PUT /calendar/events/{uuid}
+DELETE /calendar/events/{uuid}
+
+## Chat
+GET /chat/threads                                ?patient=
+GET /chat/threads/{uuid}
+GET /chat/threads/{uuid}/messages
+POST /chat/threads/{uuid}/read
+POST /chat/messages
+GET /chat/messages/{uuid}
+POST /chat/messages/{uuid}/read
+GET /chat/snippets
+POST /chat/snippets
+PUT /chat/snippets/{uuid}
+DELETE /chat/snippets/{uuid}
+
+## Notifications
+GET /notifications/devices                       ?user=
+POST /notifications/devices
+GET /notifications/subscriptions
+POST /notifications/subscriptions
+DELETE /notifications/subscriptions/{uuid}
+
+## Mutation Request Bodies
+
+POST /clinician/api/patients
+  required: uniqueId, username, firstName, lastName, sex(male|female|unknown),
+            address, postalCode, city, links.patientGroups[uri...]
+  optional: dateOfBirth(YYYY-MM-DD), phone, mobilePhone, email, comment,
+            dueDate, profilePicture, place, relatives[{firstName,lastName,relation,phone}]
+
+PUT /clinician/api/patients/{id}
+  same fields as create, all optional except links.patientGroups
+
+POST /clinician/api/clinicians
+  required: username, firstName, lastName, links.patientGroups[uri...], links.roles[uri...]
+  optional: email, phone, mobilePhone, uniqueId
+
+POST /clinician/api/patient-notes
+  required: note, type(normal|important), links.patient(uri)
+  optional: reminderDate(date-time)
+
+POST /clinician/api/patientgroups
+  required: name, messagingEnabled, blueAlarmsEnabled, links.organization(uri)
+  optional: dueDateVisible, calculateBloodPressureWeeklyAverage, copdPrediction
+
+POST /clinician/api/patients/{id}/questionnaire_schedules
+  required: links.questionnaireDefinition(uri)
+  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)
+  optional: historic
+  note: source+sourceId must be unique per capture
+
+POST /chat/messages
+  required: body, links.organization(uri)
+  variant 1: links.patient(uri), optional links.attachments[uri...]
+  variant 2: links.patientGroup(uri)
+
+POST /calendar/events
+  required: type, description, schedule.startTime(date-time),
+            party.clinicians[{links.clinician(uri)}],
+            party.patients[{links.patient(uri)}],
+            links.origin(uri)
+  optional: schedule.endTime(date-time), party.name
+
+## Notes
+- Dates use ISO 8601: 2024-01-01T00:00:00.000Z
+- Default max is 100, default offset is 0
+- 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
+- Schemas discoverable via each service's root links.schemas; filenames vary by endpoint
+`;

package/dist/auth.d.ts

@@ -0,0 +1,26 @@
+export type Environment = string;
+interface Credentials {
+    username: string;
+    password: string;
+}
+export declare class AuthManager {
+    private env;
+    private state;
+    private fetchFn;
+    constructor(env?: Environment, fetchFn?: typeof fetch);
+    get environment(): Environment;
+    get baseUrl(): string;
+    get isAuthenticated(): boolean;
+    get userInfo(): {
+        username: string | null;
+    } | null;
+    switchEnvironment(env: Environment): void;
+    getToken(): Promise<string>;
+    private isExpiringSoon;
+    private authenticate;
+    private refresh;
+    private handleAuthError;
+    private extractTokenVerifier;
+    resolveCredentials(): Promise<Credentials>;
+}
+export {};

package/dist/auth.js

@@ -0,0 +1,192 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+function envBaseUrl(env) {
+    return `https://doccla-${env}.oth.io`;
+}
+const REFRESH_BUFFER_SECONDS = 60;
+const AUTH_ERROR_MESSAGES = {
+    locked: "Account is locked. Contact your administrator.",
+    inactive: "Account is deactivated.",
+    invalid: "Invalid credentials. Check your username and password.",
+    missing: "User not found.",
+    unknown: "User not found.",
+    expired: "Password has expired. Reset your password via the OTH web UI.",
+    pincode_required: "MFA is enabled on this account. The MCP server does not support MFA. " +
+        "Use an account without MFA enabled, or disable MFA for this account.",
+};
+export class AuthManager {
+    env;
+    state = null;
+    fetchFn;
+    constructor(env, fetchFn) {
+        this.env = env ?? process.env.OTH_ENV ?? "dev";
+        this.fetchFn = fetchFn ?? fetch;
+    }
+    get environment() {
+        return this.env;
+    }
+    get baseUrl() {
+        return envBaseUrl(this.env);
+    }
+    get isAuthenticated() {
+        return this.state !== null;
+    }
+    get userInfo() {
+        if (!this.state)
+            return null;
+        return { username: this.state.username };
+    }
+    switchEnvironment(env) {
+        if (env === this.env)
+            return;
+        this.env = env;
+        this.state = null;
+    }
+    async getToken() {
+        if (this.state && !this.isExpiringSoon()) {
+            return this.state.token;
+        }
+        if (this.state && this.isExpiringSoon()) {
+            try {
+                await this.refresh();
+                return this.state.token;
+            }
+            catch {
+                // Refresh failed — fall through to full re-auth
+                this.state = null;
+            }
+        }
+        await this.authenticate();
+        return this.state.token;
+    }
+    isExpiringSoon() {
+        if (!this.state)
+            return true;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        return this.state.exp - nowSeconds < REFRESH_BUFFER_SECONDS;
+    }
+    async authenticate() {
+        const creds = await this.resolveCredentials();
+        const basic = Buffer.from(`${creds.username}:${creds.password}`).toString("base64");
+        const response = await this.fetchFn(`${this.baseUrl}/idp2/users/auth`, {
+            method: "GET",
+            headers: {
+                Authorization: `Basic ${basic}`,
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            await this.handleAuthError(response);
+        }
+        const cookieHeader = response.headers.get("set-cookie");
+        const tokenVerifier = this.extractTokenVerifier(cookieHeader);
+        const body = await response.json();
+        this.state = {
+            token: body.token,
+            refreshToken: body.refreshToken ?? null,
+            tokenVerifier,
+            exp: body.exp,
+            username: creds.username,
+        };
+    }
+    async refresh() {
+        if (!this.state?.refreshToken) {
+            throw new Error("No refresh token available");
+        }
+        const headers = {
+            Authorization: `Refresh ${this.state.refreshToken}`,
+            Accept: "application/json",
+        };
+        if (this.state.tokenVerifier) {
+            headers["Cookie"] = `tokenverifier=${this.state.tokenVerifier}`;
+        }
+        const response = await this.fetchFn(`${this.baseUrl}/idp2/users/auth`, { method: "GET", headers });
+        if (!response.ok) {
+            throw new Error(`Refresh failed: ${response.status}`);
+        }
+        const cookieHeader = response.headers.get("set-cookie");
+        const tokenVerifier = this.extractTokenVerifier(cookieHeader);
+        const body = await response.json();
+        this.state = {
+            ...this.state,
+            token: body.token,
+            refreshToken: body.refreshToken ?? this.state.refreshToken,
+            tokenVerifier: tokenVerifier ?? this.state.tokenVerifier,
+            exp: body.exp,
+        };
+    }
+    async handleAuthError(response) {
+        let errorCode = "unknown";
+        try {
+            const body = await response.json();
+            if (body.errors?.[0]?.error) {
+                errorCode = body.errors[0].error;
+            }
+            const message = AUTH_ERROR_MESSAGES[errorCode] ??
+                body.message ??
+                `Authentication failed (${response.status})`;
+            throw new Error(message);
+        }
+        catch (e) {
+            if (e instanceof Error && AUTH_ERROR_MESSAGES[errorCode])
+                throw e;
+            throw new Error(`Authentication failed (${response.status})`);
+        }
+    }
+    extractTokenVerifier(cookieHeader) {
+        if (!cookieHeader)
+            return null;
+        const match = cookieHeader.match(/tokenverifier=([^;]+)/);
+        return match?.[1] ?? null;
+    }
+    async resolveCredentials() {
+        // 1. Environment variables
+        const envUser = process.env.OTH_USERNAME;
+        const envPass = process.env.OTH_PASSWORD;
+        if (envUser && envPass) {
+            return { username: envUser, password: envPass };
+        }
+        // 2. macOS Keychain
+        if (process.platform === "darwin") {
+            try {
+                const account = `oth-${this.env}`;
+                const [userResult, passResult] = await Promise.all([
+                    execFileAsync("security", [
+                        "find-generic-password",
+                        "-a",
+                        account,
+                        "-s",
+                        "oth-mcp-username",
+                        "-w",
+                    ]),
+                    execFileAsync("security", [
+                        "find-generic-password",
+                        "-a",
+                        account,
+                        "-s",
+                        "oth-mcp-password",
+                        "-w",
+                    ]),
+                ]);
+                const username = userResult.stdout.trim();
+                const password = passResult.stdout.trim();
+                if (username && password) {
+                    return { username, password };
+                }
+            }
+            catch {
+                // Keychain lookup failed — fall through to error
+            }
+        }
+        // 3. Fail with instructions
+        throw new Error(`No OTH credentials found for environment "${this.env}".\n\n` +
+            "Set credentials via environment variables:\n" +
+            "  OTH_USERNAME=your-username\n" +
+            "  OTH_PASSWORD=your-password\n" +
+            "  OTH_ENV=dev  (optional, defaults to dev)\n\n" +
+            "Or on macOS, store in Keychain:\n" +
+            `  security add-generic-password -a "oth-${this.env}" -s "oth-mcp-username" -w\n` +
+            `  security add-generic-password -a "oth-${this.env}" -s "oth-mcp-password" -w`);
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { AuthManager } from "./auth.js";
+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>;
+    private validatePath;
+    private buildUrl;
+    private processResponse;
+    private normalizeError;
+}

package/dist/client.js

@@ -0,0 +1,90 @@
+export class OthClient {
+    auth;
+    constructor(auth) {
+        this.auth = auth;
+    }
+    async get(path, query) {
+        this.validatePath(path);
+        const url = this.buildUrl(path, query);
+        const token = await this.auth.getToken();
+        const response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+            },
+        });
+        return this.processResponse(response);
+    }
+    async mutate(method, path, body) {
+        this.validatePath(path);
+        const url = this.buildUrl(path);
+        const token = await this.auth.getToken();
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const response = await fetch(url.toString(), init);
+        return this.processResponse(response);
+    }
+    validatePath(path) {
+        if (/^https?:\/\//i.test(path)) {
+            throw new Error("Absolute URLs are not allowed. Use a relative path like /clinician/api/patients");
+        }
+    }
+    buildUrl(path, query) {
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        const url = new URL(normalized, this.auth.baseUrl);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url;
+    }
+    async processResponse(response) {
+        if (response.ok) {
+            if (response.status === 204)
+                return { success: true };
+            return response.json();
+        }
+        return this.normalizeError(response);
+    }
+    async normalizeError(response) {
+        const contentType = response.headers.get("content-type") ?? "";
+        let message;
+        try {
+            if (contentType.includes("application/json")) {
+                const body = (await response.json());
+                if (body.message) {
+                    message = body.message;
+                }
+                else if (body.errors?.length) {
+                    message = body.errors
+                        .map((e) => `${e.error}${e.field ? ` (${e.field})` : ""}${e.resource ? ` on ${e.resource}` : ""}`)
+                        .join("; ");
+                }
+                else {
+                    message = `HTTP ${response.status} ${response.statusText}`;
+                }
+            }
+            else {
+                const text = await response.text();
+                // Strip HTML tags if present
+                message = text.replace(/<[^>]*>/g, "").trim();
+                if (!message || message.length > 500) {
+                    message = `HTTP ${response.status} ${response.statusText}`;
+                }
+            }
+        }
+        catch {
+            message = `HTTP ${response.status} ${response.statusText}`;
+        }
+        return { error: true, status: response.status, message };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AuthManager } from "./auth.js";
+import { OthClient } from "./client.js";
+import { registerTools } from "./tools.js";
+import { API_GUIDE } from "./api-guide.js";
+const server = new McpServer({
+    name: "oth-mcp",
+    version: "0.1.0",
+});
+const auth = new AuthManager();
+const client = new OthClient(auth);
+registerTools(server, auth, client);
+server.registerResource("api-guide", "oth://api-guide", {
+    description: "OTH API endpoint reference — paths, query params, and request body schemas",
+    mimeType: "text/markdown",
+    annotations: {
+        audience: ["assistant"],
+    },
+}, async () => ({
+    contents: [
+        {
+            uri: "oth://api-guide",
+            mimeType: "text/markdown",
+            text: API_GUIDE,
+        },
+    ],
+}));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("oth-mcp server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { OthClient } from "./client.js";
+import { AuthManager } from "./auth.js";
+export declare function registerTools(server: McpServer, auth: AuthManager, client: OthClient): void;

package/dist/tools.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+function isApiError(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "error" in result &&
+        result.error === true);
+}
+export function registerTools(server, auth, client) {
+    server.registerTool("oth_get", {
+        title: "OTH GET Request",
+        description: `GET any OTH API endpoint. Auth handled automatically.
+Common paths:
+  /clinician/api/patients?username=&firstName=&max=
+  /clinician/api/patients/{id}
+  /clinician/api/questionnaire_definitions?max=
+  /clinician/api/questionnaires/{id}
+  /clinician/api/questionnaire-results?from=&to=&max=
+  /measurements/measurement-types
+  /organizations/organizations
+Read the oth://api-guide resource for full endpoint reference.`,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            path: z
+                .string()
+                .describe("API path, e.g. /clinician/api/patients/123"),
+            query: z
+                .record(z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe("Query parameters as key-value pairs"),
+        },
+    }, async ({ path, query }) => {
+        try {
+            const coerced = query
+                ? Object.fromEntries(Object.entries(query).map(([k, v]) => [k, String(v)]))
+                : undefined;
+            const result = await client.get(path, coerced);
+            if (isApiError(result)) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: e instanceof Error ? e.message : String(e),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("oth_mutate", {
+        title: "OTH Mutate Request",
+        description: "POST, PUT, PATCH, or DELETE to any OTH API endpoint. Auth handled automatically.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            method: z
+                .enum(["POST", "PUT", "PATCH", "DELETE"])
+                .default("POST")
+                .describe("HTTP method"),
+            path: z.string().describe("API path"),
+            body: z
+                .record(z.unknown())
+                .optional()
+                .describe("Request body (JSON)"),
+        },
+    }, async ({ method, path, body }) => {
+        try {
+            const result = await client.mutate(method, path, body);
+            if (isApiError(result)) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: e instanceof Error ? e.message : String(e),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("oth_env", {
+        title: "OTH Environment",
+        description: "Switch OTH environment or show current state. Returns environment, base URL, and authenticated user info.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            environment: z
+                .enum(["dev", "stag", "demo"])
+                .optional()
+                .describe("Target environment. Omit to show current state."),
+        },
+    }, async ({ environment }) => {
+        if (environment) {
+            auth.switchEnvironment(environment);
+        }
+        const info = {
+            environment: auth.environment,
+            baseUrl: auth.baseUrl,
+            authenticated: auth.isAuthenticated,
+        };
+        if (auth.isAuthenticated) {
+            info.user = auth.userInfo;
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(info, null, 2) },
+            ],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "oth-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the OTH (OpenTeleHealth) API",
+  "type": "module",
+  "bin": {
+    "oth-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}