pulsemcp-cms-admin-mcp-server 0.6.8 → 0.6.10

package/README.md

@@ -82,6 +82,18 @@ This server is built and tested on macOS with Claude Desktop. It should work wit
 | `create_redirect`                      | redirects          | write      | Create a new URL redirect entry.                                              |
 | `update_redirect`                      | redirects          | write      | Update an existing URL redirect by ID.                                        |
 | `delete_redirect`                      | redirects          | write      | Delete a URL redirect by ID (irreversible).                                   |
+| `list_good_jobs`                       | good_jobs          | read       | List and filter background jobs by queue, status, job class, and date range.  |
+| `get_good_job`                         | good_jobs          | read       | Get detailed information about a specific background job.                     |
+| `list_good_job_cron_schedules`         | good_jobs          | read       | List all configured cron schedules.                                           |
+| `list_good_job_processes`              | good_jobs          | read       | List active worker processes.                                                 |
+| `get_good_job_queue_statistics`        | good_jobs          | read       | Get aggregate job statistics by status.                                       |
+| `retry_good_job`                       | good_jobs          | write      | Retry a failed or discarded background job.                                   |
+| `discard_good_job`                     | good_jobs          | write      | Discard a background job to prevent retries.                                  |
+| `reschedule_good_job`                  | good_jobs          | write      | Reschedule a background job to a new time.                                    |
+| `force_trigger_good_job_cron`          | good_jobs          | write      | Force trigger a cron schedule immediately.                                    |
+| `cleanup_good_jobs`                    | good_jobs          | write      | Clean up old background jobs by status and age.                               |
+| `run_exam_for_mirror`                  | proctor            | write      | Run proctor exams against unofficial mirrors via Fly Machines.                |
+| `save_results_for_mirror`              | proctor            | write      | Save proctor exam results (must use output from `run_exam_for_mirror`).       |
 
 # Tool Groups
 
@@ -92,35 +104,38 @@ This server organizes tools into groups that can be selectively enabled or disab
 
 ## Available Groups
 
-| Group                         | Tools | Description                                 |
-| ----------------------------- | ----- | ------------------------------------------- |
-| `newsletter`                  | 6     | Full newsletter management (read + write)   |
-| `newsletter_readonly`         | 3     | Newsletter read-only (get posts, authors)   |
-| `server_directory`            | 5     | Full MCP server directory (read + write)    |
-| `server_directory_readonly`   | 3     | MCP server directory read-only              |
-| `official_queue`              | 7     | Full official mirror queue (read + write)   |
-| `official_queue_readonly`     | 2     | Official mirror queue read-only             |
-| `unofficial_mirrors`          | 5     | Full unofficial mirrors CRUD (read + write) |
-| `unofficial_mirrors_readonly` | 2     | Unofficial mirrors read-only                |
-| `official_mirrors`            | 2     | Official mirrors REST API (read-only)       |
-| `official_mirrors_readonly`   | 2     | Official mirrors read-only (alias)          |
-| `tenants`                     | 2     | Tenants REST API (read-only)                |
-| `tenants_readonly`            | 2     | Tenants read-only (alias)                   |
-| `mcp_jsons`                   | 5     | Full MCP JSON configurations (read + write) |
-| `mcp_jsons_readonly`          | 2     | MCP JSON configurations read-only           |
-| `mcp_servers`                 | 3     | Full MCP servers management (read + write)  |
-| `mcp_servers_readonly`        | 2     | MCP servers read-only (list, get)           |
-| `redirects`                   | 5     | Full URL redirect management (read + write) |
-| `redirects_readonly`          | 2     | URL redirects read-only (list, get)         |
+| Group                         | Tools | Description                                                                                                                                                                 |
+| ----------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `newsletter`                  | 6     | Full newsletter management (read + write)                                                                                                                                   |
+| `newsletter_readonly`         | 3     | Newsletter read-only (get posts, authors)                                                                                                                                   |
+| `server_directory`            | 27    | Comprehensive superset: includes all tools from mcp_servers, unofficial_mirrors, official_mirrors, official_queue, mcp_jsons, plus implementations/providers (read + write) |
+| `server_directory_readonly`   | 13    | Server directory read-only subset                                                                                                                                           |
+| `official_queue`              | 7     | Full official mirror queue (read + write)                                                                                                                                   |
+| `official_queue_readonly`     | 2     | Official mirror queue read-only                                                                                                                                             |
+| `unofficial_mirrors`          | 5     | Full unofficial mirrors CRUD (read + write)                                                                                                                                 |
+| `unofficial_mirrors_readonly` | 2     | Unofficial mirrors read-only                                                                                                                                                |
+| `official_mirrors`            | 2     | Official mirrors REST API (read-only)                                                                                                                                       |
+| `official_mirrors_readonly`   | 2     | Official mirrors read-only (alias)                                                                                                                                          |
+| `tenants`                     | 2     | Tenants REST API (read-only)                                                                                                                                                |
+| `tenants_readonly`            | 2     | Tenants read-only (alias)                                                                                                                                                   |
+| `mcp_jsons`                   | 5     | Full MCP JSON configurations (read + write)                                                                                                                                 |
+| `mcp_jsons_readonly`          | 2     | MCP JSON configurations read-only                                                                                                                                           |
+| `mcp_servers`                 | 3     | Full MCP servers management (read + write)                                                                                                                                  |
+| `mcp_servers_readonly`        | 2     | MCP servers read-only (list, get)                                                                                                                                           |
+| `redirects`                   | 5     | Full URL redirect management (read + write)                                                                                                                                 |
+| `redirects_readonly`          | 2     | URL redirects read-only (list, get)                                                                                                                                         |
+| `good_jobs`                   | 10    | Full GoodJob background job management (read + write)                                                                                                                       |
+| `good_jobs_readonly`          | 5     | GoodJob read-only (list, get, stats, processes, cron)                                                                                                                       |
+| `proctor`                     | 2     | Proctor exam execution and result storage (write-only, no readonly variant)                                                                                                 |
 
 ### Tools by Group
 
 - **newsletter** / **newsletter_readonly**:
   - Read-only: `get_newsletter_posts`, `get_newsletter_post`, `get_authors`
   - Write: `draft_newsletter_post`, `update_newsletter_post`, `upload_image`
-- **server_directory** / **server_directory_readonly**:
-  - Read-only: `search_mcp_implementations`, `get_draft_mcp_implementations`, `find_providers`
-  - Write: `save_mcp_implementation`, `send_impl_posted_notif`
+- **server_directory** / **server_directory_readonly** (superset — includes tools from mcp_servers, unofficial_mirrors, official_mirrors, official_queue, and mcp_jsons):
+  - Read-only: `search_mcp_implementations`, `get_draft_mcp_implementations`, `find_providers`, `list_mcp_servers`, `get_mcp_server`, `get_unofficial_mirrors`, `get_unofficial_mirror`, `get_official_mirrors`, `get_official_mirror`, `get_official_mirror_queue_items`, `get_official_mirror_queue_item`, `get_mcp_jsons`, `get_mcp_json`
+  - Write: `save_mcp_implementation`, `send_impl_posted_notif`, `update_mcp_server`, `create_unofficial_mirror`, `update_unofficial_mirror`, `delete_unofficial_mirror`, `approve_official_mirror_queue_item`, `approve_mirror_no_modify`, `reject_official_mirror_queue_item`, `add_official_mirror_to_regular_queue`, `unlink_official_mirror_queue_item`, `create_mcp_json`, `update_mcp_json`, `delete_mcp_json`
 - **official_queue** / **official_queue_readonly**:
   - Read-only: `get_official_mirror_queue_items`, `get_official_mirror_queue_item`
   - Write: `approve_official_mirror_queue_item`, `approve_mirror_no_modify`, `reject_official_mirror_queue_item`, `add_official_mirror_to_regular_queue`, `unlink_official_mirror_queue_item`
@@ -140,12 +155,17 @@ This server organizes tools into groups that can be selectively enabled or disab
 - **redirects** / **redirects_readonly**:
   - Read-only: `get_redirects`, `get_redirect`
   - Write: `create_redirect`, `update_redirect`, `delete_redirect`
+- **good_jobs** / **good_jobs_readonly**:
+  - Read-only: `list_good_jobs`, `get_good_job`, `list_good_job_cron_schedules`, `list_good_job_processes`, `get_good_job_queue_statistics`
+  - Write: `retry_good_job`, `discard_good_job`, `reschedule_good_job`, `force_trigger_good_job_cron`, `cleanup_good_jobs`
+- **proctor** (no readonly variant — both tools trigger side effects):
+  - Write: `run_exam_for_mirror`, `save_results_for_mirror`
 
 ## Environment Variables
 
-| Variable      | Description                                 | Default                                                                                                                                    |
-| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `TOOL_GROUPS` | Comma-separated list of enabled tool groups | `newsletter,server_directory,official_queue,unofficial_mirrors,official_mirrors,tenants,mcp_jsons,mcp_servers,redirects` (all base groups) |
+| Variable      | Description                                 | Default                                                                                                                                                      |
+| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TOOL_GROUPS` | Comma-separated list of enabled tool groups | `newsletter,server_directory,official_queue,unofficial_mirrors,official_mirrors,tenants,mcp_jsons,mcp_servers,redirects,good_jobs,proctor` (all base groups) |
 
 ## Examples
 
@@ -170,9 +190,11 @@ TOOL_GROUPS=server_directory_readonly
 Enable all groups with read-only access:
 
 ```bash
-TOOL_GROUPS=newsletter_readonly,server_directory_readonly,official_queue_readonly,unofficial_mirrors_readonly,official_mirrors_readonly,tenants_readonly,mcp_jsons_readonly,mcp_servers_readonly,redirects_readonly
+TOOL_GROUPS=newsletter_readonly,server_directory_readonly,official_queue_readonly,unofficial_mirrors_readonly,official_mirrors_readonly,tenants_readonly,mcp_jsons_readonly,mcp_servers_readonly,redirects_readonly,good_jobs_readonly
 ```
 
+Note: `proctor` has no readonly variant since both tools trigger side effects.
+
 Mix full and read-only access per group:
 
 ```bash
@@ -306,7 +328,7 @@ Add to your Claude Desktop configuration:
       "args": ["/path/to/pulsemcp-cms-admin/local/build/index.js"],
       "env": {
         "PULSEMCP_ADMIN_API_KEY": "your-api-key-here",
-        "TOOL_GROUPS": "newsletter,server_directory,official_queue,unofficial_mirrors,official_mirrors,tenants,mcp_jsons,mcp_servers,redirects"
+        "TOOL_GROUPS": "newsletter,server_directory,official_queue,unofficial_mirrors,official_mirrors,tenants,mcp_jsons,mcp_servers,redirects,good_jobs,proctor"
       }
     }
   }
@@ -323,7 +345,7 @@ For read-only access:
       "args": ["/path/to/pulsemcp-cms-admin/local/build/index.js"],
       "env": {
         "PULSEMCP_ADMIN_API_KEY": "your-api-key-here",
-        "TOOL_GROUPS": "newsletter_readonly,server_directory_readonly,official_queue_readonly,unofficial_mirrors_readonly,official_mirrors_readonly,tenants_readonly,mcp_jsons_readonly,mcp_servers_readonly,redirects_readonly"
+        "TOOL_GROUPS": "newsletter_readonly,server_directory_readonly,official_queue_readonly,unofficial_mirrors_readonly,official_mirrors_readonly,tenants_readonly,mcp_jsons_readonly,mcp_servers_readonly,redirects_readonly,good_jobs_readonly"
       }
     }
   }

package/build/shared/src/pulsemcp-admin-client/lib/cleanup-good-jobs.js

@@ -0,0 +1,34 @@
+export async function cleanupGoodJobs(apiKey, baseUrl, params) {
+    const url = new URL('/api/good_jobs/cleanup', baseUrl);
+    const body = {};
+    if (params?.older_than_days !== undefined) {
+        body.older_than_days = params.older_than_days;
+    }
+    if (params?.status !== undefined) {
+        body.status = params.status;
+    }
+    const response = await fetch(url.toString(), {
+        method: 'DELETE',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks write privileges');
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation failed: ${errorData.errors?.join(', ') || 'Unknown error'}`);
+        }
+        throw new Error(`Failed to cleanup good jobs: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/discard-good-job.js

@@ -0,0 +1,24 @@
+export async function discardGoodJob(apiKey, baseUrl, id) {
+    const url = new URL(`/api/good_jobs/${id}/discard`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks write privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`GoodJob with ID ${id} not found`);
+        }
+        throw new Error(`Failed to discard good job: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/force-trigger-good-job-cron.js

@@ -0,0 +1,24 @@
+export async function forceTriggerGoodJobCron(apiKey, baseUrl, cronKey) {
+    const url = new URL(`/api/good_jobs/cron_schedules/${cronKey}/trigger`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks write privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`Cron schedule with key "${cronKey}" not found`);
+        }
+        throw new Error(`Failed to trigger cron schedule: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-good-job-cron-schedules.js

@@ -0,0 +1,28 @@
+export async function getGoodJobCronSchedules(apiKey, baseUrl) {
+    const url = new URL('/api/good_jobs/cron_schedules', baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch cron schedules: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data.map((schedule) => ({
+        cron_key: schedule.cron_key,
+        job_class: schedule.job_class,
+        cron_expression: schedule.cron_expression,
+        description: schedule.description,
+        next_scheduled_at: schedule.next_scheduled_at,
+        last_run_at: schedule.last_run_at,
+    }));
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-good-job-processes.js

@@ -0,0 +1,34 @@
+export async function getGoodJobProcesses(apiKey, baseUrl) {
+    const url = new URL('/api/good_jobs/processes', baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch good job processes: ${response.status} ${response.statusText}`);
+    }
+    const json = (await response.json());
+    const processes = json.data;
+    return processes.map((proc) => {
+        const schedulers = proc.state.schedulers ?? [];
+        const queues = schedulers.map((s) => s.queues);
+        const maxThreads = schedulers.reduce((sum, s) => sum + s.max_threads, 0);
+        return {
+            id: proc.id,
+            hostname: proc.state.hostname,
+            pid: proc.state.pid,
+            queues,
+            max_threads: maxThreads || undefined,
+            started_at: proc.created_at,
+        };
+    });
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-good-job-statistics.js

@@ -0,0 +1,29 @@
+export async function getGoodJobStatistics(apiKey, baseUrl) {
+    const url = new URL('/api/good_jobs/statistics', baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch job statistics: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        total: data.total,
+        scheduled: data.by_status.scheduled,
+        queued: data.by_status.queued,
+        running: data.by_status.running,
+        succeeded: data.by_status.succeeded,
+        failed: data.by_status.retried ?? 0,
+        discarded: data.by_status.discarded,
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-good-job.js

@@ -0,0 +1,36 @@
+export async function getGoodJob(apiKey, baseUrl, id) {
+    const url = new URL(`/api/good_jobs/${id}`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`GoodJob with ID ${id} not found`);
+        }
+        throw new Error(`Failed to fetch good job: ${response.status} ${response.statusText}`);
+    }
+    const job = (await response.json());
+    return {
+        id: job.id,
+        job_class: job.job_class,
+        queue_name: job.queue_name,
+        status: job.status,
+        scheduled_at: job.scheduled_at,
+        performed_at: job.performed_at,
+        finished_at: job.finished_at,
+        error: job.error,
+        serialized_params: job.serialized_params,
+        created_at: job.created_at,
+        updated_at: job.updated_at,
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-good-jobs.js

@@ -0,0 +1,66 @@
+function mapGoodJob(job) {
+    return {
+        id: job.id,
+        job_class: job.job_class,
+        queue_name: job.queue_name,
+        status: job.status,
+        scheduled_at: job.scheduled_at,
+        performed_at: job.performed_at,
+        finished_at: job.finished_at,
+        error: job.error,
+        serialized_params: job.serialized_params,
+        created_at: job.created_at,
+        updated_at: job.updated_at,
+    };
+}
+export async function getGoodJobs(apiKey, baseUrl, params) {
+    const url = new URL('/api/good_jobs', baseUrl);
+    if (params?.queue_name) {
+        url.searchParams.append('queue_name', params.queue_name);
+    }
+    if (params?.status) {
+        url.searchParams.append('status', params.status);
+    }
+    if (params?.job_class) {
+        url.searchParams.append('job_class', params.job_class);
+    }
+    if (params?.after) {
+        url.searchParams.append('after', params.after);
+    }
+    if (params?.before) {
+        url.searchParams.append('before', params.before);
+    }
+    if (params?.limit) {
+        url.searchParams.append('limit', params.limit.toString());
+    }
+    if (params?.offset) {
+        url.searchParams.append('offset', params.offset.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch good jobs: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        jobs: data.data.map(mapGoodJob),
+        pagination: {
+            current_page: data.meta.current_page,
+            total_pages: data.meta.total_pages,
+            total_count: data.meta.total_count,
+            has_next: data.meta.has_next,
+            limit: data.meta.limit,
+        },
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/reschedule-good-job.js

@@ -0,0 +1,30 @@
+export async function rescheduleGoodJob(apiKey, baseUrl, id, scheduledAt) {
+    const url = new URL(`/api/good_jobs/${id}/reschedule`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify({ scheduled_at: scheduledAt }),
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks write privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`GoodJob with ID ${id} not found`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation failed: ${errorData.errors?.join(', ') || 'Unknown error'}`);
+        }
+        throw new Error(`Failed to reschedule good job: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/retry-good-job.js

@@ -0,0 +1,24 @@
+export async function retryGoodJob(apiKey, baseUrl, id) {
+    const url = new URL(`/api/good_jobs/${id}/retry`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks write privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`GoodJob with ID ${id} not found`);
+        }
+        throw new Error(`Failed to retry good job: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/run-exam-for-mirror.js

@@ -0,0 +1,49 @@
+export async function runExamForMirror(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor/run_exam_for_mirror', baseUrl);
+    const body = {
+        mirror_ids: params.mirror_ids,
+        runtime_id: params.runtime_id,
+        exam_type: params.exam_type,
+    };
+    if (params.max_retries !== undefined) {
+        body.max_retries = params.max_retries;
+    }
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'application/x-ndjson',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation failed: ${errorData.error || 'Unknown error'}`);
+        }
+        throw new Error(`Failed to run proctor exam: ${response.status} ${response.statusText}`);
+    }
+    // Parse NDJSON response - each line is a separate JSON object
+    const text = await response.text();
+    const lines = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed) {
+            try {
+                lines.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Include malformed lines as error entries so they're visible in output
+                lines.push({ type: 'error', message: `Malformed NDJSON line: ${trimmed}` });
+            }
+        }
+    }
+    return { lines };
+}

package/build/shared/src/pulsemcp-admin-client/lib/save-results-for-mirror.js

@@ -0,0 +1,34 @@
+export async function saveResultsForMirror(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor/save_results_for_mirror', baseUrl);
+    const body = {
+        mirror_id: params.mirror_id,
+        runtime_id: params.runtime_id,
+        results: params.results,
+    };
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        if (response.status === 404) {
+            throw new Error(`Mirror not found with ID: ${params.mirror_id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation failed: ${errorData.error || 'Unknown error'}`);
+        }
+        throw new Error(`Failed to save proctor results: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}