pulsemcp-cms-admin-mcp-server 0.7.4 → 0.9.1

package/shared/tools/save-results-for-mirror.js

@@ -3,38 +3,19 @@ import { examResultStore, extractExamId, extractStatus } from '../exam-result-st
 const PARAM_DESCRIPTIONS = {
     mirror_id: 'The ID of the unofficial mirror to save results for',
     runtime_id: 'The runtime ID that was used to run the exams',
-    result_id: 'The UUID returned by run_exam_for_mirror. When provided, the server retrieves the full result from the local file store — no need to pass the results array. This is the preferred approach.',
-    results: 'Array of exam results to save. Each result must include exam_id, status, and optional data. Only needed if result_id is not provided.',
-    exam_id: 'The exam identifier (e.g., "auth-check", "init-tools-list")',
-    status: 'The result status (e.g., "pass", "fail", "error", "skip")',
-    data: 'Optional detailed result data. Sensitive fields (tokens, secrets, passwords) will be automatically redacted before storage.',
+    result_id: 'The UUID returned by run_exam_for_mirror. The server retrieves the full result from the local file store automatically.',
 };
-const ResultSchema = z.object({
-    exam_id: z.string().describe(PARAM_DESCRIPTIONS.exam_id),
-    status: z.string().describe(PARAM_DESCRIPTIONS.status),
-    data: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.data),
-});
-const SaveResultsForMirrorSchema = z
-    .object({
+const SaveResultsForMirrorSchema = z.object({
     mirror_id: z.number().describe(PARAM_DESCRIPTIONS.mirror_id),
     runtime_id: z.string().optional().describe(PARAM_DESCRIPTIONS.runtime_id),
-    result_id: z.string().uuid().optional().describe(PARAM_DESCRIPTIONS.result_id),
-    results: z.array(ResultSchema).optional().describe(PARAM_DESCRIPTIONS.results),
-})
-    .refine((data) => data.result_id || (data.results && data.results.length > 0), {
-    message: 'Either result_id or a non-empty results array must be provided',
-})
-    .refine((data) => !(data.result_id && data.results && data.results.length > 0), {
-    message: 'Provide either result_id or results, not both. Use result_id (preferred) to retrieve from the store, or results for direct submission.',
+    result_id: z.string().uuid().describe(PARAM_DESCRIPTIONS.result_id),
 });
 export function saveResultsForMirror(_server, clientFactory) {
     return {
         name: 'save_results_for_mirror',
         description: `Save proctor exam results for an unofficial mirror.
 
-**Preferred**: Pass the \`result_id\` returned by \`run_exam_for_mirror\`. The full result is retrieved from the local file store server-side — no need to pass the large results payload through the LLM context.
-
-**Fallback**: Pass results directly (as before) if result_id is not available.
+Pass the \`result_id\` returned by \`run_exam_for_mirror\`. The full result is retrieved from the local file store server-side — no need to pass the large results payload through the LLM context.
 
 Results are sanitized server-side to redact sensitive data (OAuth tokens, client secrets, passwords, etc.) before being persisted.
 
@@ -54,109 +35,85 @@ Typical workflow:
                     format: 'uuid',
                     description: PARAM_DESCRIPTIONS.result_id,
                 },
-                results: {
-                    type: 'array',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            exam_id: { type: 'string', description: PARAM_DESCRIPTIONS.exam_id },
-                            status: { type: 'string', description: PARAM_DESCRIPTIONS.status },
-                            data: {
-                                type: 'object',
-                                additionalProperties: true,
-                                description: PARAM_DESCRIPTIONS.data,
-                            },
-                        },
-                        required: ['exam_id', 'status'],
-                    },
-                    description: PARAM_DESCRIPTIONS.results,
-                },
             },
-            required: ['mirror_id'],
+            required: ['mirror_id', 'result_id'],
         },
         handler: async (args) => {
             const validatedArgs = SaveResultsForMirrorSchema.parse(args);
             const client = clientFactory();
             try {
-                let results = validatedArgs.results;
-                let runtimeId = validatedArgs.runtime_id;
-                // If result_id is provided, retrieve from the store
-                if (validatedArgs.result_id) {
-                    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. Pass the results array directly instead.`,
-                                },
-                            ],
-                            isError: true,
-                        };
-                    }
-                    // Extract exam_result lines from stored data.
-                    //
-                    // The real proctor API returns a deeply nested structure:
-                    //   line.data = {
-                    //     mirror_id, server_slug, exam_id, ...,
-                    //     result: {                          ← envelope
-                    //       exam_id, machine_id, status,
-                    //       result: {                        ← actual payload
-                    //         input: {...}, output: {...}, processedBy: {...}
-                    //       },
-                    //       error, logs
-                    //     }
-                    //   }
-                    //
-                    // The PulseMCP API expects the actual payload { input, output,
-                    // processedBy } at the top level of the saved results column.
-                    // We must unwrap through data.result.result to reach it.
-                    results = stored.lines
-                        .filter((line) => line.type === 'exam_result')
-                        .map((line) => {
-                        const data = line.data;
-                        // Unwrap nested result objects to find the exam payload
-                        // containing { input, output, processedBy }.
-                        let resultData = data;
-                        // Level 1: data.result (envelope with exam_id, machine_id, logs, etc.)
-                        if (resultData?.result &&
+                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. Re-run run_exam_for_mirror to generate a new result.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Extract exam_result lines from stored data.
+                //
+                // The real proctor API returns a deeply nested structure:
+                //   line.data = {
+                //     mirror_id, server_slug, exam_id, ...,
+                //     result: {                          ← envelope
+                //       exam_id, machine_id, status,
+                //       result: {                        ← actual payload
+                //         input: {...}, output: {...}, processedBy: {...}
+                //       },
+                //       error, logs
+                //     }
+                //   }
+                //
+                // The PulseMCP API expects the actual payload { input, output,
+                // processedBy } at the top level of the saved results column.
+                // We must unwrap through data.result.result to reach it.
+                const results = stored.lines
+                    .filter((line) => line.type === 'exam_result')
+                    .map((line) => {
+                    const data = line.data;
+                    // Unwrap nested result objects to find the exam payload
+                    // containing { input, output, processedBy }.
+                    let resultData = data;
+                    // Level 1: data.result (envelope with exam_id, machine_id, logs, etc.)
+                    if (resultData?.result &&
+                        typeof resultData.result === 'object' &&
+                        !Array.isArray(resultData.result)) {
+                        resultData = resultData.result;
+                        // Level 2: data.result.result (actual payload with input, output, processedBy)
+                        if (resultData.result &&
                             typeof resultData.result === 'object' &&
                             !Array.isArray(resultData.result)) {
                             resultData = resultData.result;
-                            // Level 2: data.result.result (actual payload with input, output, processedBy)
-                            if (resultData.result &&
-                                typeof resultData.result === 'object' &&
-                                !Array.isArray(resultData.result)) {
-                                resultData = resultData.result;
-                            }
                         }
-                        return {
-                            exam_id: extractExamId(line),
-                            status: extractStatus(line),
-                            ...(resultData ? { data: resultData } : {}),
-                        };
-                    });
-                    if (!runtimeId) {
-                        runtimeId = stored.runtime_id;
                     }
-                }
-                if (!results || results.length === 0) {
+                    return {
+                        exam_id: extractExamId(line),
+                        status: extractStatus(line),
+                        ...(resultData ? { data: resultData } : {}),
+                    };
+                });
+                if (results.length === 0) {
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'No exam results to save. Either provide a result_id from run_exam_for_mirror or pass results directly.',
+                                text: 'No exam results found in the stored result. The stored data may not contain any exam_result lines.',
                             },
                         ],
                         isError: true,
                     };
                 }
+                const runtimeId = validatedArgs.runtime_id || stored.runtime_id;
                 if (!runtimeId) {
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'runtime_id is required. Provide it directly or use a result_id which includes the runtime_id.',
+                                text: 'runtime_id is required. Provide it directly or ensure the stored result includes it.',
                             },
                         ],
                         isError: true,
@@ -170,9 +127,7 @@ Typical workflow:
                 let content = `**Proctor Results Saved**\n\n`;
                 content += `Mirror ID: ${validatedArgs.mirror_id}\n`;
                 content += `Runtime: ${runtimeId}\n`;
-                if (validatedArgs.result_id) {
-                    content += `Result ID: ${validatedArgs.result_id}\n`;
-                }
+                content += `Result ID: ${validatedArgs.result_id}\n`;
                 content += '\n';
                 if (response.saved.length > 0) {
                     content += `**Successfully Saved (${response.saved.length}):**\n`;
@@ -193,7 +148,7 @@ Typical workflow:
                     }
                 }
                 // Clean up stored result after successful save (all results persisted)
-                if (validatedArgs.result_id && response.errors.length === 0) {
+                if (response.errors.length === 0) {
                     examResultStore.delete(validatedArgs.result_id);
                 }
                 return { content: [{ type: 'text', text: content.trim() }] };

package/shared/tools/update-mcp-server.js

@@ -25,8 +25,8 @@ const PARAM_DESCRIPTIONS = {
 const CanonicalUrlSchema = z.object({
     url: z.string().describe('The canonical URL'),
     scope: z
-        .enum(['domain', 'subdomain', 'subfolder', 'url'])
-        .describe('Scope of the canonical: domain, subdomain, subfolder, or url (exact match)'),
+        .enum(['domain', 'subdomain', 'url'])
+        .describe('Scope of the canonical: domain, subdomain, or url (exact match)'),
     note: z.string().optional().describe('Optional note about this canonical URL'),
 });
 const RemoteEndpointSchema = z.object({
@@ -126,7 +126,7 @@ Providing canonical_urls replaces ALL existing canonical URLs:
 {
   "implementation_id": 456,
   "canonical_urls": [
-    { "url": "https://github.com/org/repo", "scope": "subfolder" },
+    { "url": "https://github.com/org/repo", "scope": "domain" },
     { "url": "https://npmjs.com/package/name", "scope": "url" }
   ]
 }
@@ -237,7 +237,7 @@ Create new provider:
                             url: { type: 'string', description: 'The canonical URL' },
                             scope: {
                                 type: 'string',
-                                enum: ['domain', 'subdomain', 'subfolder', 'url'],
+                                enum: ['domain', 'subdomain', 'url'],
                                 description: 'Scope of the canonical',
                             },
                             note: { type: 'string', description: 'Optional note' },

package/shared/tools.d.ts

@@ -23,7 +23,7 @@ import { ClientFactory } from './server.js';
  * - mcp_servers / mcp_servers_readonly: Unified MCP server tools (abstracted interface)
  * - redirects / redirects_readonly: URL redirect management tools
  * - good_jobs / good_jobs_readonly: GoodJob background job management tools
- * - proctor / proctor_readonly: Proctor exam execution and result storage tools. The readonly variant includes get_exam_result for retrieving stored results without running exams or saving
+ * - proctor / proctor_readonly: Proctor exam execution and result storage tools. The readonly variant includes get_exam_result and list_proctor_runs for retrieving stored results without running exams or saving
  * - discovered_urls / discovered_urls_readonly: Discovered URL management tools for processing URLs into MCP implementations
  * - notifications: Notification email tools (send_impl_posted_notif). Separated from server_directory so notification capability can be granted independently.
  */
@@ -69,7 +69,7 @@ export declare function parseEnabledToolGroups(enabledGroupsParam?: string): Too
  * - good_jobs: GoodJob background job management tools (read + write)
  * - good_jobs_readonly: GoodJob tools (read only)
  * - proctor: Proctor exam execution and result storage tools (read + write)
- * - proctor_readonly: Proctor tools (read only - get_exam_result for retrieving stored results)
+ * - proctor_readonly: Proctor tools (read only - get_exam_result and list_proctor_runs)
  * - discovered_urls: Discovered URL management tools for processing URLs into MCP implementations (read + write)
  * - discovered_urls_readonly: Discovered URL tools (read only - list and stats)
  * - notifications: Notification email tools - send_impl_posted_notif (write-only, no readonly variant)

package/shared/tools.js

@@ -60,6 +60,7 @@ import { cleanupGoodJobs } from './tools/cleanup-good-jobs.js';
 import { runExamForMirror } from './tools/run-exam-for-mirror.js';
 import { getExamResult } from './tools/get-exam-result.js';
 import { saveResultsForMirror } from './tools/save-results-for-mirror.js';
+import { listProctorRuns } from './tools/list-proctor-runs.js';
 // Discovered URLs tools
 import { listDiscoveredUrls } from './tools/list-discovered-urls.js';
 import { markDiscoveredUrlProcessed } from './tools/mark-discovered-url-processed.js';
@@ -230,6 +231,7 @@ const ALL_TOOLS = [
     { factory: runExamForMirror, groups: ['proctor'], isWriteOperation: true },
     { factory: getExamResult, groups: ['proctor'], isWriteOperation: false },
     { factory: saveResultsForMirror, groups: ['proctor'], isWriteOperation: true },
+    { factory: listProctorRuns, groups: ['proctor'], isWriteOperation: false },
     // Discovered URLs tools
     { factory: listDiscoveredUrls, groups: ['discovered_urls'], isWriteOperation: false },
     {
@@ -367,7 +369,7 @@ function shouldIncludeTool(toolDef, enabledGroups) {
  * - good_jobs: GoodJob background job management tools (read + write)
  * - good_jobs_readonly: GoodJob tools (read only)
  * - proctor: Proctor exam execution and result storage tools (read + write)
- * - proctor_readonly: Proctor tools (read only - get_exam_result for retrieving stored results)
+ * - proctor_readonly: Proctor tools (read only - get_exam_result and list_proctor_runs)
  * - discovered_urls: Discovered URL management tools for processing URLs into MCP implementations (read + write)
  * - discovered_urls_readonly: Discovered URL tools (read only - list and stats)
  * - notifications: Notification email tools - send_impl_posted_notif (write-only, no readonly variant)

package/shared/types.d.ts

@@ -105,7 +105,7 @@ export interface RemoteEndpointParams {
 }
 export interface CanonicalUrlParams {
     url: string;
-    scope: 'domain' | 'subdomain' | 'subfolder' | 'url';
+    scope: 'domain' | 'subdomain' | 'url';
     note?: string;
 }
 export interface MCPServer {
@@ -691,6 +691,43 @@ export interface ProctorSaveResultsResponse {
         error: string;
     }>;
 }
+export interface ProctorRun {
+    id: number;
+    slug: string;
+    name: string | null;
+    recommended: boolean;
+    mirrors_count: number;
+    tenant_count: number;
+    latest_version: string | null;
+    latest_mirror_id: number | null;
+    latest_mirror_name: string | null;
+    latest_tested: boolean;
+    last_auth_check_days: number | null;
+    last_tools_list_days: number | null;
+    auth_types: string[];
+    num_tools: number | null;
+    packages: string[];
+    remotes: string[];
+}
+export interface ProctorRunsResponse {
+    runs: ProctorRun[];
+    pagination?: {
+        current_page: number;
+        total_pages: number;
+        total_count: number;
+        has_next?: boolean;
+        limit?: number;
+    };
+}
+export interface GetProctorRunsParams {
+    q?: string;
+    recommended?: boolean;
+    tenant_ids?: string;
+    sort?: 'slug' | 'name' | 'mirrors' | 'recommended' | 'tenants' | 'latest_tested' | 'last_auth_check' | 'last_tools_list';
+    direction?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
 export type DiscoveredUrlResult = 'posted' | 'skipped' | 'rejected' | 'error';
 export interface DiscoveredUrl {
     id: number;