pulsemcp-cms-admin-mcp-server 0.6.14 → 0.7.1

package/README.md

@@ -40,60 +40,61 @@ This is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) Serv
 
 This server is built and tested on macOS with Claude Desktop. It should work with other MCP clients as well.
 
-| Tool Name                              | Tool Group         | Read/Write | Description                                                                   |
-| -------------------------------------- | ------------------ | ---------- | ----------------------------------------------------------------------------- |
-| `get_newsletter_posts`                 | newsletter         | read       | List newsletter posts with search, sorting, and pagination options.           |
-| `get_newsletter_post`                  | newsletter         | read       | Retrieve a specific newsletter post by its unique slug.                       |
-| `draft_newsletter_post`                | newsletter         | write      | Create a new draft newsletter post with title, body, and metadata.            |
-| `update_newsletter_post`               | newsletter         | write      | Update an existing newsletter post's content and metadata (except status).    |
-| `upload_image`                         | newsletter         | write      | Upload an image and attach it to a specific newsletter post.                  |
-| `get_authors`                          | newsletter         | read       | Get a list of authors with optional search and pagination.                    |
-| `search_mcp_implementations`           | server_directory   | read       | Search for MCP servers and clients in the PulseMCP registry.                  |
-| `get_draft_mcp_implementations`        | server_directory   | read       | Retrieve paginated list of draft MCP implementations needing review.          |
-| `find_providers`                       | server_directory   | read       | Search for providers by ID, name, URL, or slug.                               |
-| `save_mcp_implementation`              | server_directory   | write      | Update an MCP implementation (replicates Admin panel "Save Changes" button).  |
-| `send_impl_posted_notif`               | server_directory   | write      | Send email notification when MCP implementation goes live.                    |
-| `get_official_mirror_queue_items`      | official_queue     | read       | List and filter official mirror queue entries with pagination and search.     |
-| `get_official_mirror_queue_item`       | official_queue     | read       | Get detailed information about a single official mirror queue entry.          |
-| `approve_official_mirror_queue_item`   | official_queue     | write      | Approve a queue entry and link it to an existing MCP server (async).          |
-| `approve_mirror_no_modify`             | official_queue     | write      | Approve without updating the linked server.                                   |
-| `reject_official_mirror_queue_item`    | official_queue     | write      | Reject a queue entry (async operation).                                       |
-| `add_official_mirror_to_regular_queue` | official_queue     | write      | Convert a queue entry to a draft MCP implementation (async).                  |
-| `unlink_official_mirror_queue_item`    | official_queue     | write      | Unlink a queue entry from its linked MCP server.                              |
-| `get_unofficial_mirrors`               | unofficial_mirrors | read       | List unofficial mirrors with search, pagination, and MCP server filtering.    |
-| `get_unofficial_mirror`                | unofficial_mirrors | read       | Get detailed unofficial mirror info by ID or name.                            |
-| `create_unofficial_mirror`             | unofficial_mirrors | write      | Create a new unofficial mirror entry with JSON data.                          |
-| `update_unofficial_mirror`             | unofficial_mirrors | write      | Update an existing unofficial mirror by ID.                                   |
-| `delete_unofficial_mirror`             | unofficial_mirrors | write      | Delete an unofficial mirror by ID (irreversible).                             |
-| `get_official_mirrors`                 | official_mirrors   | read       | List official mirrors with search, status, and processing filters.            |
-| `get_official_mirror`                  | official_mirrors   | read       | Get detailed official mirror info by ID or name.                              |
-| `get_tenants`                          | tenants            | read       | List tenants with search and admin status filtering.                          |
-| `get_tenant`                           | tenants            | read       | Get detailed tenant info by ID or slug.                                       |
-| `get_mcp_jsons`                        | mcp_jsons          | read       | List MCP JSON configs with mirror and server filtering.                       |
-| `get_mcp_json`                         | mcp_jsons          | read       | Get a single MCP JSON configuration by ID.                                    |
-| `create_mcp_json`                      | mcp_jsons          | write      | Create a new MCP JSON configuration for an unofficial mirror.                 |
-| `update_mcp_json`                      | mcp_jsons          | write      | Update an existing MCP JSON configuration by ID.                              |
-| `delete_mcp_json`                      | mcp_jsons          | write      | Delete an MCP JSON configuration by ID (irreversible).                        |
-| `list_mcp_servers`                     | mcp_servers        | read       | List/search MCP servers with filtering by status, classification, pagination. |
-| `get_mcp_server`                       | mcp_servers        | read       | Get detailed MCP server info by slug (unified view of all admin UI fields).   |
-| `update_mcp_server`                    | mcp_servers        | write      | Update an MCP server's fields (all admin UI fields supported).                |
-| `get_redirects`                        | redirects          | read       | List URL redirects with search, status filtering, and pagination.             |
-| `get_redirect`                         | redirects          | read       | Get detailed redirect info by ID.                                             |
-| `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 Name                              | Tool Group         | Read/Write | Description                                                                                                |
+| -------------------------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `get_newsletter_posts`                 | newsletter         | read       | List newsletter posts with search, sorting, and pagination options.                                        |
+| `get_newsletter_post`                  | newsletter         | read       | Retrieve a specific newsletter post by its unique slug.                                                    |
+| `draft_newsletter_post`                | newsletter         | write      | Create a new draft newsletter post with title, body, and metadata.                                         |
+| `update_newsletter_post`               | newsletter         | write      | Update an existing newsletter post's content and metadata (except status).                                 |
+| `upload_image`                         | newsletter         | write      | Upload an image and attach it to a specific newsletter post.                                               |
+| `get_authors`                          | newsletter         | read       | Get a list of authors with optional search and pagination.                                                 |
+| `search_mcp_implementations`           | server_directory   | read       | Search for MCP servers and clients in the PulseMCP registry.                                               |
+| `get_draft_mcp_implementations`        | server_directory   | read       | Retrieve paginated list of draft MCP implementations needing review.                                       |
+| `find_providers`                       | server_directory   | read       | Search for providers by ID, name, URL, or slug.                                                            |
+| `save_mcp_implementation`              | server_directory   | write      | Update an MCP implementation (replicates Admin panel "Save Changes" button).                               |
+| `send_impl_posted_notif`               | server_directory   | write      | Send email notification when MCP implementation goes live.                                                 |
+| `get_official_mirror_queue_items`      | official_queue     | read       | List and filter official mirror queue entries with pagination and search.                                  |
+| `get_official_mirror_queue_item`       | official_queue     | read       | Get detailed information about a single official mirror queue entry.                                       |
+| `approve_official_mirror_queue_item`   | official_queue     | write      | Approve a queue entry and link it to an existing MCP server (async).                                       |
+| `approve_mirror_no_modify`             | official_queue     | write      | Approve without updating the linked server.                                                                |
+| `reject_official_mirror_queue_item`    | official_queue     | write      | Reject a queue entry (async operation).                                                                    |
+| `add_official_mirror_to_regular_queue` | official_queue     | write      | Convert a queue entry to a draft MCP implementation (async).                                               |
+| `unlink_official_mirror_queue_item`    | official_queue     | write      | Unlink a queue entry from its linked MCP server.                                                           |
+| `get_unofficial_mirrors`               | unofficial_mirrors | read       | List unofficial mirrors with search, pagination, and MCP server filtering.                                 |
+| `get_unofficial_mirror`                | unofficial_mirrors | read       | Get detailed unofficial mirror info by ID or name.                                                         |
+| `create_unofficial_mirror`             | unofficial_mirrors | write      | Create a new unofficial mirror entry with JSON data.                                                       |
+| `update_unofficial_mirror`             | unofficial_mirrors | write      | Update an existing unofficial mirror by ID.                                                                |
+| `delete_unofficial_mirror`             | unofficial_mirrors | write      | Delete an unofficial mirror by ID (irreversible).                                                          |
+| `get_official_mirrors`                 | official_mirrors   | read       | List official mirrors with search, status, and processing filters.                                         |
+| `get_official_mirror`                  | official_mirrors   | read       | Get detailed official mirror info by ID or name.                                                           |
+| `get_tenants`                          | tenants            | read       | List tenants with search and admin status filtering.                                                       |
+| `get_tenant`                           | tenants            | read       | Get detailed tenant info by ID or slug.                                                                    |
+| `get_mcp_jsons`                        | mcp_jsons          | read       | List MCP JSON configs with mirror and server filtering.                                                    |
+| `get_mcp_json`                         | mcp_jsons          | read       | Get a single MCP JSON configuration by ID.                                                                 |
+| `create_mcp_json`                      | mcp_jsons          | write      | Create a new MCP JSON configuration for an unofficial mirror.                                              |
+| `update_mcp_json`                      | mcp_jsons          | write      | Update an existing MCP JSON configuration by ID.                                                           |
+| `delete_mcp_json`                      | mcp_jsons          | write      | Delete an MCP JSON configuration by ID (irreversible).                                                     |
+| `list_mcp_servers`                     | mcp_servers        | read       | List/search MCP servers with filtering by status, classification, pagination.                              |
+| `get_mcp_server`                       | mcp_servers        | read       | Get detailed MCP server info by slug (unified view of all admin UI fields).                                |
+| `update_mcp_server`                    | mcp_servers        | write      | Update an MCP server's fields (all admin UI fields supported).                                             |
+| `get_redirects`                        | redirects          | read       | List URL redirects with search, status filtering, and pagination.                                          |
+| `get_redirect`                         | redirects          | read       | Get detailed redirect info by ID.                                                                          |
+| `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. Returns truncated summary with `result_id`. |
+| `get_exam_result`                      | proctor            | read       | Retrieve full untruncated exam results by `result_id`, with optional section/mirror filtering.             |
+| `save_results_for_mirror`              | proctor            | write      | Save proctor exam results. Accepts `result_id` or explicit results array.                                  |
 
 # Tool Groups
 
@@ -126,7 +127,8 @@ This server organizes tools into groups that can be selectively enabled or disab
 | `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)                                                                                                 |
+| `proctor`                     | 3     | Proctor exam execution, result retrieval, and result storage (read + write)                                                                                                 |
+| `proctor_readonly`            | 1     | Proctor results read-only (`get_exam_result`)                                                                                                                               |
 
 ### Tools by Group
 
@@ -158,7 +160,8 @@ This server organizes tools into groups that can be selectively enabled or disab
 - **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):
+- **proctor** / **proctor_readonly**:
+  - Read-only: `get_exam_result`
   - Write: `run_exam_for_mirror`, `save_results_for_mirror`
 
 ## Environment Variables
@@ -190,10 +193,10 @@ 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,good_jobs_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,proctor_readonly
 ```
 
-Note: `proctor` has no readonly variant since both tools trigger side effects.
+Note: `proctor_readonly` includes only `get_exam_result` for retrieving stored results. `notifications` has no readonly variant since sending emails is always a write operation.
 
 Mix full and read-only access per group:
 

package/build/shared/src/exam-result-store.js

@@ -0,0 +1,171 @@
+import { randomUUID } from 'crypto';
+import { readFileSync, writeFileSync, unlinkSync, readdirSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+/**
+ * Extract exam_id from a proctor exam stream line, checking both the
+ * data payload and top-level fields. The API may place exam_id in
+ * either location depending on the exam type.
+ */
+export function extractExamId(line) {
+    const data = line.data;
+    return (data?.exam_id ||
+        line.exam_id ||
+        data?.exam_type ||
+        line.exam_type ||
+        'unknown');
+}
+/**
+ * Extract status from a proctor exam stream line, checking both the
+ * data payload and top-level fields.
+ */
+export function extractStatus(line) {
+    const data = line.data;
+    return data?.status || line.status || 'unknown';
+}
+/**
+ * Maximum number of results to keep on disk. Oldest results are evicted
+ * when this limit is reached (FIFO by insertion order).
+ */
+const MAX_RESULTS = 100;
+const STORE_DIR = join(tmpdir(), 'pulsemcp-exam-results');
+const FILE_SUFFIX = '.json';
+/**
+ * File-based store for proctor exam results.
+ *
+ * When `run_exam_for_mirror` completes, the full result is written to a
+ * JSON file in /tmp/ and a UUID `result_id` is returned. This avoids
+ * dumping large payloads (~60KB+ for servers with many tools) into the
+ * LLM context, and survives across tool calls without relying on
+ * in-memory state.
+ *
+ * Files are named with a zero-padded sequence number prefix so that
+ * lexicographic sorting preserves insertion order for FIFO eviction.
+ * The sequence counter is initialized from existing files on disk so
+ * that new entries sort after old ones even across process restarts.
+ *
+ * Eviction: When the store exceeds MAX_RESULTS files, the oldest result
+ * is evicted (FIFO). Results are also deleted after successful save via
+ * `save_results_for_mirror`.
+ *
+ * Consumers can:
+ * - Use `get_exam_result` to drill into the full result on demand
+ * - Pass `result_id` to `save_results_for_mirror` instead of the full payload
+ */
+class ExamResultStore {
+    seq;
+    constructor() {
+        this.seq = this.initSeqFromDisk();
+    }
+    /**
+     * Scan existing files to find the highest sequence number and start
+     * one past it. This ensures new files always sort after existing ones,
+     * even across process restarts.
+     */
+    initSeqFromDisk() {
+        this.ensureDir();
+        const files = readdirSync(STORE_DIR)
+            .filter((f) => f.endsWith(FILE_SUFFIX) && f.length > FILE_SUFFIX.length)
+            .sort();
+        if (files.length === 0)
+            return 0;
+        const lastFile = files[files.length - 1];
+        const seqStr = lastFile.slice(0, 10);
+        const parsed = parseInt(seqStr, 10);
+        return isNaN(parsed) ? 0 : parsed + 1;
+    }
+    ensureDir() {
+        if (!existsSync(STORE_DIR)) {
+            mkdirSync(STORE_DIR, { recursive: true, mode: 0o700 });
+        }
+    }
+    /** Filename format: {seq}-{uuid}.json — seq is zero-padded for lexicographic ordering */
+    fileName(seq, resultId) {
+        return `${String(seq).padStart(10, '0')}-${resultId}${FILE_SUFFIX}`;
+    }
+    extractResultId(fileName) {
+        // Format: 0000000001-<uuid>.json
+        return fileName.slice(11, -FILE_SUFFIX.length);
+    }
+    listResultFiles() {
+        this.ensureDir();
+        return readdirSync(STORE_DIR)
+            .filter((f) => f.endsWith(FILE_SUFFIX) && f.length > FILE_SUFFIX.length)
+            .sort(); // Lexicographic sort gives insertion order via zero-padded seq
+    }
+    findFileForResult(resultId) {
+        const files = this.listResultFiles();
+        return files.find((f) => this.extractResultId(f) === resultId);
+    }
+    store(mirrorIds, runtimeId, examType, lines) {
+        this.ensureDir();
+        const resultId = randomUUID();
+        const seqNum = this.seq++;
+        // Evict oldest entries if at capacity (files are sorted by seq prefix)
+        const files = this.listResultFiles();
+        const toEvict = files.length - MAX_RESULTS + 1;
+        for (let i = 0; i < toEvict; i++) {
+            try {
+                unlinkSync(join(STORE_DIR, files[i]));
+            }
+            catch {
+                // ignore
+            }
+        }
+        const stored = {
+            result_id: resultId,
+            mirror_ids: mirrorIds,
+            runtime_id: runtimeId,
+            exam_type: examType,
+            lines,
+            stored_at: new Date().toISOString(),
+        };
+        writeFileSync(join(STORE_DIR, this.fileName(seqNum, resultId)), JSON.stringify(stored), {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+        return resultId;
+    }
+    get(resultId) {
+        const file = this.findFileForResult(resultId);
+        if (!file)
+            return undefined;
+        try {
+            const content = readFileSync(join(STORE_DIR, file), 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    delete(resultId) {
+        const file = this.findFileForResult(resultId);
+        if (!file)
+            return false;
+        try {
+            unlinkSync(join(STORE_DIR, file));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    get size() {
+        return this.listResultFiles().length;
+    }
+    /** For testing only — removes all result files and resets the sequence counter */
+    clear() {
+        this.ensureDir();
+        for (const file of this.listResultFiles()) {
+            try {
+                unlinkSync(join(STORE_DIR, file));
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.seq = 0;
+    }
+}
+/** Singleton instance shared across all tool factories */
+export const examResultStore = new ExamResultStore();

package/build/shared/src/tools/get-exam-result.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { examResultStore } from '../exam-result-store.js';
+const PARAM_DESCRIPTIONS = {
+    result_id: 'The UUID returned by run_exam_for_mirror identifying the stored result to retrieve.',
+    section: 'Optional filter to retrieve only a specific section of the result. "exam_results" returns only exam_result lines, "logs" returns only log lines, "summary" returns only the summary line, "errors" returns only error lines. If omitted, returns all lines.',
+    mirror_id: 'Optional mirror ID filter. When provided, only returns exam_result lines for this specific mirror. Useful when the exam was run against multiple mirrors.',
+};
+const GetExamResultSchema = z.object({
+    result_id: z.string().uuid().describe(PARAM_DESCRIPTIONS.result_id),
+    section: z
+        .enum(['exam_results', 'logs', 'summary', 'errors'])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.section),
+    mirror_id: z.number().optional().describe(PARAM_DESCRIPTIONS.mirror_id),
+});
+export function getExamResult(_server, _clientFactory) {
+    return {
+        name: 'get_exam_result',
+        description: `Retrieve the full, untruncated proctor exam result stored by a prior run_exam_for_mirror call.
+
+run_exam_for_mirror returns a truncated summary to keep the response within MCP size limits. This tool provides on-demand access to the complete result data, including full tool input schemas and detailed exam output.
+
+Supports filtering by section (exam_results, logs, summary, errors) and by mirror_id to drill into specific parts of the result without loading the entire payload.
+
+**Tip**: For servers with many tools, the full result can be very large. Use the section and/or mirror_id filters to retrieve only the data you need.
+
+Typical usage:
+1. Call run_exam_for_mirror — note the returned result_id
+2. Call get_exam_result with that result_id and a section filter (e.g., section="exam_results")
+3. Optionally add mirror_id to narrow further for multi-mirror exams`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                result_id: { type: 'string', format: 'uuid', description: PARAM_DESCRIPTIONS.result_id },
+                section: {
+                    type: 'string',
+                    enum: ['exam_results', 'logs', 'summary', 'errors'],
+                    description: PARAM_DESCRIPTIONS.section,
+                },
+                mirror_id: { type: 'number', description: PARAM_DESCRIPTIONS.mirror_id },
+            },
+            required: ['result_id'],
+        },
+        handler: async (args) => {
+            const validatedArgs = GetExamResultSchema.parse(args);
+            const stored = examResultStore.get(validatedArgs.result_id);
+            if (!stored) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No stored result found for result_id "${validatedArgs.result_id}". The result file may have been cleaned up or the /tmp directory cleared.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            let lines = stored.lines;
+            // Filter by section
+            if (validatedArgs.section) {
+                const typeMap = {
+                    exam_results: 'exam_result',
+                    logs: 'log',
+                    summary: 'summary',
+                    errors: 'error',
+                };
+                const targetType = typeMap[validatedArgs.section];
+                lines = lines.filter((line) => line.type === targetType);
+            }
+            // Filter by mirror_id
+            if (validatedArgs.mirror_id !== undefined) {
+                lines = lines.filter((line) => line.type !== 'exam_result' || line.mirror_id === validatedArgs.mirror_id);
+            }
+            let content = `**Exam Result Details**\n\n`;
+            content += `Result ID: ${stored.result_id}\n`;
+            content += `Mirrors: ${stored.mirror_ids.join(', ')}\n`;
+            content += `Exam Type: ${stored.exam_type}\n`;
+            content += `Runtime: ${stored.runtime_id}\n`;
+            content += `Stored At: ${stored.stored_at}\n`;
+            if (validatedArgs.section) {
+                content += `Section Filter: ${validatedArgs.section}\n`;
+            }
+            if (validatedArgs.mirror_id !== undefined) {
+                content += `Mirror Filter: ${validatedArgs.mirror_id}\n`;
+            }
+            content += `\n---\n\n`;
+            if (lines.length === 0) {
+                content += 'No matching lines found for the given filters.\n';
+            }
+            else {
+                for (const line of lines) {
+                    content += JSON.stringify(line, null, 2) + '\n\n';
+                }
+            }
+            return { content: [{ type: 'text', text: content.trim() }] };
+        },
+    };
+}

package/build/shared/src/tools/run-exam-for-mirror.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { examResultStore, extractExamId, extractStatus } from '../exam-result-store.js';
 const PARAM_DESCRIPTIONS = {
     mirror_ids: 'Array of unofficial mirror IDs to run exams against. Mirrors without saved mcp_json configs will be skipped.',
     runtime_id: 'The Fly Machines runtime ID to use for running the exam containers (e.g., "fly-machines-v1")',
@@ -13,6 +14,46 @@ const RunExamForMirrorSchema = z.object({
         .describe(PARAM_DESCRIPTIONS.exam_type),
     max_retries: z.number().min(0).max(10).optional().describe(PARAM_DESCRIPTIONS.max_retries),
 });
+/**
+ * Build a truncated summary of exam results for the LLM response.
+ * Omits large keys like full input schemas from tool listings to keep
+ * the payload within MCP size limits. The full result is accessible
+ * via the `get_exam_result` tool using the returned `result_id`.
+ */
+function truncateExamResultData(data) {
+    const truncated = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key === 'tools' && Array.isArray(value)) {
+            // For tool listings, include only name and description, omit inputSchema
+            truncated[key] = value.map((tool) => ({
+                name: tool.name,
+                ...(tool.description ? { description: String(tool.description).slice(0, 100) } : {}),
+            }));
+            truncated['tools_count'] = value.length;
+            truncated['tools_truncated'] = true;
+        }
+        else if (key === 'inputSchema' || key === 'input_schema') {
+            // Omit full input schemas
+            truncated[key] = '(truncated — use get_exam_result to see full data)';
+        }
+        else if (typeof value === 'string' && value.length > 500) {
+            truncated[key] = value.slice(0, 500) + '... (truncated)';
+        }
+        else if (typeof value === 'object' && value !== null) {
+            const serialized = JSON.stringify(value);
+            if (serialized.length > 1000) {
+                truncated[key] = '(truncated — use get_exam_result to see full data)';
+            }
+            else {
+                truncated[key] = value;
+            }
+        }
+        else {
+            truncated[key] = value;
+        }
+    }
+    return truncated;
+}
 export function runExamForMirror(_server, clientFactory) {
     return {
         name: 'run_exam_for_mirror',
@@ -23,7 +64,9 @@ Available exam types:
 - **init-tools-list**: Connects to the mirror and retrieves its list of MCP tools, verifying the server initializes properly
 - **both**: Runs both exams sequentially
 
-Mirrors without saved mcp_json configurations are automatically skipped. Results are returned as a stream of events including logs, exam results, and a final summary.
+Mirrors without saved mcp_json configurations are automatically skipped.
+
+Results are stored server-side in a local file and a \`result_id\` UUID is returned. The response includes a truncated summary (status, tool names/counts, errors) that fits within MCP size limits. Use \`get_exam_result\` to drill into full details, or pass the \`result_id\` directly to \`save_results_for_mirror\`.
 
 Use cases:
 - Test if an unofficial mirror's MCP server is working correctly before linking it
@@ -64,7 +107,10 @@ Use cases:
                     exam_type: validatedArgs.exam_type,
                     max_retries: validatedArgs.max_retries,
                 });
+                // Store the full result server-side
+                const resultId = examResultStore.store(validatedArgs.mirror_ids, validatedArgs.runtime_id, validatedArgs.exam_type, response.lines);
                 let content = `**Proctor Exam Results**\n\n`;
+                content += `Result ID: ${resultId}\n`;
                 content += `Mirrors: ${validatedArgs.mirror_ids.join(', ')}\n`;
                 content += `Exam Type: ${validatedArgs.exam_type}\n`;
                 content += `Runtime: ${validatedArgs.runtime_id}\n\n`;
@@ -73,14 +119,18 @@ Use cases:
                         case 'log':
                             content += `[LOG] ${line.message || JSON.stringify(line)}\n`;
                             break;
-                        case 'exam_result':
-                            content += `\n**Exam Result** (Mirror: ${line.mirror_id || 'unknown'})\n`;
-                            content += `  Exam: ${line.exam_id || line.exam_type || 'unknown'}\n`;
-                            content += `  Status: ${line.status || 'unknown'}\n`;
-                            if (line.data) {
-                                content += `  Data: ${JSON.stringify(line.data, null, 2)}\n`;
+                        case 'exam_result': {
+                            const data = line.data;
+                            const mirrorId = line.mirror_id ?? data?.mirror_id ?? 'unknown';
+                            content += `\n**Exam Result** (Mirror: ${mirrorId})\n`;
+                            content += `  Exam: ${extractExamId(line)}\n`;
+                            content += `  Status: ${extractStatus(line)}\n`;
+                            if (data) {
+                                const truncatedData = truncateExamResultData(data);
+                                content += `  Data: ${JSON.stringify(truncatedData, null, 2)}\n`;
                             }
                             break;
+                        }
                         case 'summary':
                             content += `\n**Summary**\n`;
                             content += `  Total: ${line.total || 0}\n`;
@@ -95,6 +145,8 @@ Use cases:
                             content += `${JSON.stringify(line)}\n`;
                     }
                 }
+                content += `\n\nUse \`get_exam_result\` with result_id "${resultId}" to see full untruncated data.`;
+                content += `\nUse \`save_results_for_mirror\` with result_id "${resultId}" to save these results.`;
                 return { content: [{ type: 'text', text: content.trim() }] };
             }
             catch (error) {