proctor-mcp-server 0.1.0

package/shared/proctor-client/lib/get-metadata.d.ts

@@ -0,0 +1,6 @@
+import type { ProctorMetadataResponse } from '../../types.js';
+/**
+ * Get available runtimes and exams from the Proctor API
+ */
+export declare function getMetadata(apiKey: string, baseUrl: string): Promise<ProctorMetadataResponse>;
+//# sourceMappingURL=get-metadata.d.ts.map

package/shared/proctor-client/lib/get-metadata.js

@@ -0,0 +1,23 @@
+/**
+ * Get available runtimes and exams from the Proctor API
+ */
+export async function getMetadata(apiKey, baseUrl) {
+    const url = new URL('/api/proctor/metadata', 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 or insufficient permissions');
+        }
+        throw new Error(`Failed to get metadata: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}

package/shared/proctor-client/lib/get-prior-result.d.ts

@@ -0,0 +1,6 @@
+import type { PriorResultParams, PriorResultResponse } from '../../types.js';
+/**
+ * Get a prior exam result for comparison
+ */
+export declare function getPriorResult(apiKey: string, baseUrl: string, params: PriorResultParams): Promise<PriorResultResponse>;
+//# sourceMappingURL=get-prior-result.d.ts.map

package/shared/proctor-client/lib/get-prior-result.js

@@ -0,0 +1,35 @@
+/**
+ * Get a prior exam result for comparison
+ */
+export async function getPriorResult(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor/prior_result', baseUrl);
+    url.searchParams.append('mirror_id', String(params.mirror_id));
+    url.searchParams.append('exam_id', params.exam_id);
+    if (params.input_json) {
+        url.searchParams.append('input_json', params.input_json);
+    }
+    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 or insufficient permissions');
+        }
+        if (response.status === 400) {
+            const errorData = (await response.json());
+            throw new Error(`Bad request: ${errorData.error || 'Missing required parameters'}`);
+        }
+        if (response.status === 404) {
+            throw new Error('No prior result found');
+        }
+        throw new Error(`Failed to get prior result: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}

package/shared/proctor-client/lib/run-exam.d.ts

@@ -0,0 +1,7 @@
+import type { RunExamParams, ExamStreamEntry } from '../../types.js';
+/**
+ * Run a Proctor exam against an MCP server.
+ * Returns an async generator that yields NDJSON stream entries.
+ */
+export declare function runExam(apiKey: string, baseUrl: string, params: RunExamParams): AsyncGenerator<ExamStreamEntry, void, unknown>;
+//# sourceMappingURL=run-exam.d.ts.map

package/shared/proctor-client/lib/run-exam.js

@@ -0,0 +1,90 @@
+/**
+ * Run a Proctor exam against an MCP server.
+ * Returns an async generator that yields NDJSON stream entries.
+ */
+export async function* runExam(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor/run_exam', baseUrl);
+    const body = {
+        runtime_id: params.runtime_id,
+        exam_id: params.exam_id,
+        mcp_config: params.mcp_config,
+    };
+    if (params.server_json) {
+        body.server_json = params.server_json;
+    }
+    if (params.custom_runtime_image) {
+        body.custom_runtime_image = params.custom_runtime_image;
+    }
+    if (params.max_retries !== undefined) {
+        body.max_retries = params.max_retries;
+    }
+    if (params.mcp_server_slug) {
+        body.mcp_server_slug = params.mcp_server_slug;
+    }
+    if (params.mcp_json_id !== undefined) {
+        body.mcp_json_id = params.mcp_json_id;
+    }
+    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 or insufficient permissions');
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation error: ${errorData.error || 'Unknown validation error'}`);
+        }
+        throw new Error(`Failed to run exam: ${response.status} ${response.statusText}`);
+    }
+    if (!response.body) {
+        throw new Error('No response body received');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                // Process any remaining data in buffer
+                if (buffer.trim()) {
+                    try {
+                        yield JSON.parse(buffer.trim());
+                    }
+                    catch {
+                        // Ignore parse errors for incomplete data
+                    }
+                }
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete lines (NDJSON format)
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || ''; // Keep incomplete line in buffer
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed) {
+                    try {
+                        yield JSON.parse(trimmed);
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/shared/proctor-client/lib/save-result.d.ts

@@ -0,0 +1,6 @@
+import type { SaveResultParams, SaveResultResponse } from '../../types.js';
+/**
+ * Save exam results to the database
+ */
+export declare function saveResult(apiKey: string, baseUrl: string, params: SaveResultParams): Promise<SaveResultResponse>;
+//# sourceMappingURL=save-result.d.ts.map

package/shared/proctor-client/lib/save-result.js

@@ -0,0 +1,42 @@
+/**
+ * Save exam results to the database
+ */
+export async function saveResult(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor/save_result', baseUrl);
+    const body = {
+        runtime_id: params.runtime_id,
+        exam_id: params.exam_id,
+        mcp_server_slug: params.mcp_server_slug,
+        mirror_id: params.mirror_id,
+        results: typeof params.results === 'string' ? params.results : JSON.stringify(params.results),
+    };
+    if (params.custom_runtime_image) {
+        body.custom_runtime_image = params.custom_runtime_image;
+    }
+    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 or insufficient permissions');
+        }
+        if (response.status === 404) {
+            throw new Error('Mirror not found');
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(`Validation error: ${errorData.error || 'Unknown validation error'}`);
+        }
+        throw new Error(`Failed to save result: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}

package/shared/server.d.ts

@@ -0,0 +1,66 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ProctorMetadataResponse, RunExamParams, ExamStreamEntry, SaveResultParams, SaveResultResponse, PriorResultParams, PriorResultResponse, MachinesResponse, CancelExamParams, CancelExamResponse } from './types.js';
+export interface IProctorClient {
+    getMetadata(): Promise<ProctorMetadataResponse>;
+    runExam(params: RunExamParams): AsyncGenerator<ExamStreamEntry, void, unknown>;
+    saveResult(params: SaveResultParams): Promise<SaveResultResponse>;
+    getPriorResult(params: PriorResultParams): Promise<PriorResultResponse>;
+    getMachines(): Promise<MachinesResponse>;
+    destroyMachine(machineId: string): Promise<{
+        success: boolean;
+    }>;
+    cancelExam(params: CancelExamParams): Promise<CancelExamResponse>;
+}
+export declare class ProctorClient implements IProctorClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    getMetadata(): Promise<ProctorMetadataResponse>;
+    runExam(params: RunExamParams): AsyncGenerator<ExamStreamEntry, void, unknown>;
+    saveResult(params: SaveResultParams): Promise<SaveResultResponse>;
+    getPriorResult(params: PriorResultParams): Promise<PriorResultResponse>;
+    getMachines(): Promise<MachinesResponse>;
+    destroyMachine(machineId: string): Promise<{
+        success: boolean;
+    }>;
+    cancelExam(params: CancelExamParams): Promise<CancelExamResponse>;
+}
+export type ClientFactory = () => IProctorClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/shared/server.js

@@ -0,0 +1,65 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { createRegisterTools } from './tools.js';
+// Proctor API client implementation
+export class ProctorClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl || 'https://admin.pulsemcp.com';
+    }
+    async getMetadata() {
+        const { getMetadata } = await import('./proctor-client/lib/get-metadata.js');
+        return getMetadata(this.apiKey, this.baseUrl);
+    }
+    async *runExam(params) {
+        const { runExam } = await import('./proctor-client/lib/run-exam.js');
+        yield* runExam(this.apiKey, this.baseUrl, params);
+    }
+    async saveResult(params) {
+        const { saveResult } = await import('./proctor-client/lib/save-result.js');
+        return saveResult(this.apiKey, this.baseUrl, params);
+    }
+    async getPriorResult(params) {
+        const { getPriorResult } = await import('./proctor-client/lib/get-prior-result.js');
+        return getPriorResult(this.apiKey, this.baseUrl, params);
+    }
+    async getMachines() {
+        const { getMachines } = await import('./proctor-client/lib/get-machines.js');
+        return getMachines(this.apiKey, this.baseUrl);
+    }
+    async destroyMachine(machineId) {
+        const { destroyMachine } = await import('./proctor-client/lib/destroy-machine.js');
+        return destroyMachine(this.apiKey, this.baseUrl, machineId);
+    }
+    async cancelExam(params) {
+        const { cancelExam } = await import('./proctor-client/lib/cancel-exam.js');
+        return cancelExam(this.apiKey, this.baseUrl, params);
+    }
+}
+export function createMCPServer() {
+    const server = new Server({
+        name: 'proctor-mcp-server',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory ||
+            (() => {
+                // Get configuration from environment variables
+                const apiKey = process.env.PROCTOR_API_KEY;
+                const baseUrl = process.env.PROCTOR_API_URL;
+                if (!apiKey) {
+                    throw new Error('PROCTOR_API_KEY environment variable must be configured');
+                }
+                return new ProctorClient(apiKey, baseUrl);
+            });
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/tools/cancel-exam.d.ts

@@ -0,0 +1,34 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function cancelExam(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            machine_id: {
+                type: string;
+                description: "ID of the Fly.io machine running the exam. Get this from get_machines. Must contain only alphanumeric characters, underscores, and hyphens.";
+            };
+            exam_id: {
+                type: string;
+                description: "ID of the exam to cancel. Must match the exam currently running on the machine. Must contain only alphanumeric characters and hyphens.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=cancel-exam.d.ts.map

package/shared/tools/cancel-exam.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+// Parameter descriptions - single source of truth
+const PARAM_DESCRIPTIONS = {
+    machine_id: 'ID of the Fly.io machine running the exam. Get this from get_machines. Must contain only alphanumeric characters, underscores, and hyphens.',
+    exam_id: 'ID of the exam to cancel. Must match the exam currently running on the machine. Must contain only alphanumeric characters and hyphens.',
+};
+const CancelExamSchema = z.object({
+    machine_id: z
+        .string()
+        .min(1)
+        .regex(/^[a-zA-Z0-9_-]+$/, 'Machine ID must contain only alphanumeric characters, underscores, and hyphens')
+        .describe(PARAM_DESCRIPTIONS.machine_id),
+    exam_id: z
+        .string()
+        .min(1)
+        .regex(/^[a-zA-Z0-9-]+$/, 'Exam ID must contain only alphanumeric characters and hyphens')
+        .describe(PARAM_DESCRIPTIONS.exam_id),
+});
+export function cancelExam(_server, clientFactory) {
+    return {
+        name: 'cancel_exam',
+        description: `Cancel a running Proctor exam.
+
+Stops an exam that is currently executing on a Fly machine. This is useful
+when you need to abort a test that is taking too long or encountering issues.
+
+**Returns:**
+- Result object indicating the cancellation status
+
+**Use cases:**
+- Stop a stuck or slow exam
+- Cancel a test started with wrong parameters
+- Free up resources for other tests
+- Gracefully terminate a running exam before destroying the machine
+
+**Note:**
+- The exam must be currently running on the specified machine
+- After cancellation, the machine may still need to be destroyed separately
+- Results from a cancelled exam will not be saved automatically`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                machine_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.machine_id,
+                },
+                exam_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.exam_id,
+                },
+            },
+            required: ['machine_id', 'exam_id'],
+        },
+        handler: async (args) => {
+            const validatedArgs = CancelExamSchema.parse(args);
+            const client = clientFactory();
+            try {
+                const response = await client.cancelExam({
+                    machine_id: validatedArgs.machine_id,
+                    exam_id: validatedArgs.exam_id,
+                });
+                let content = '## Exam Cancellation\n\n';
+                content += `**Machine ID:** ${validatedArgs.machine_id}\n`;
+                content += `**Exam ID:** ${validatedArgs.exam_id}\n\n`;
+                if (response.success) {
+                    content += 'The exam has been cancelled successfully.';
+                }
+                else if (response.message) {
+                    content += `Result: ${response.message}`;
+                }
+                else {
+                    content += 'Cancellation request sent.\n\n';
+                    content += '```json\n';
+                    content += JSON.stringify(response, null, 2);
+                    content += '\n```';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: content.trim(),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error cancelling exam: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/destroy-machine.d.ts

@@ -0,0 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function destroyMachine(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            machine_id: {
+                type: string;
+                description: "ID of the Fly.io machine to destroy. Get this from get_machines. Must contain only alphanumeric characters, underscores, and hyphens.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=destroy-machine.d.ts.map

package/shared/tools/destroy-machine.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+// Parameter descriptions - single source of truth
+const PARAM_DESCRIPTIONS = {
+    machine_id: 'ID of the Fly.io machine to destroy. Get this from get_machines. Must contain only alphanumeric characters, underscores, and hyphens.',
+};
+const DestroyMachineSchema = z.object({
+    machine_id: z
+        .string()
+        .min(1)
+        .regex(/^[a-zA-Z0-9_-]+$/, 'Machine ID must contain only alphanumeric characters, underscores, and hyphens')
+        .describe(PARAM_DESCRIPTIONS.machine_id),
+});
+export function destroyMachine(_server, clientFactory) {
+    return {
+        name: 'destroy_machine',
+        description: `Delete a Fly.io machine.
+
+Permanently removes a Fly machine that was used for Proctor exam execution.
+Use this to clean up machines that are no longer needed.
+
+**Returns:**
+- success: boolean indicating if the machine was deleted
+
+**Use cases:**
+- Clean up machines after exam completion
+- Remove stuck or failed machines
+- Free up resources
+- Remove machines that are no longer needed
+
+**Warning:**
+- This action is irreversible
+- Any running processes on the machine will be terminated
+- Use cancel_exam first if there's a running exam you want to stop gracefully`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                machine_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.machine_id,
+                },
+            },
+            required: ['machine_id'],
+        },
+        handler: async (args) => {
+            const validatedArgs = DestroyMachineSchema.parse(args);
+            const client = clientFactory();
+            try {
+                const response = await client.destroyMachine(validatedArgs.machine_id);
+                let content = '## Machine Destroyed\n\n';
+                content += `**Machine ID:** ${validatedArgs.machine_id}\n`;
+                content += `**Success:** ${response.success}\n\n`;
+                content += 'The machine has been permanently deleted.';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: content.trim(),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error destroying machine: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-machines.d.ts

@@ -0,0 +1,25 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function getMachines(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {};
+        required: never[];
+    };
+    handler: () => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-machines.d.ts.map