proctor-mcp-server 0.1.4 → 0.1.6

package/build/index.integration-with-mock.js

@@ -3,8 +3,16 @@
  * Integration test entry point with mock client
  * This file is used for testing the MCP server with mocked external API calls
  */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer, logServerStart, logError } from '../shared/index.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 /**
  * Integration mock implementation of IProctorClient
  */
@@ -87,7 +95,7 @@ class IntegrationMockProctorClient {
 }
 async function main() {
     // Create server using factory
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     // Create mock client for testing
     const mockClient = new IntegrationMockProctorClient();
     // Register all handlers with mock client

package/build/index.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 // Validate required environment variables before starting
 function validateEnvironment() {
     const required = [
@@ -42,7 +50,7 @@ async function main() {
     // Validate environment variables first
     validateEnvironment();
     // Create server using factory
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     // Register all handlers (resources and tools)
     await registerHandlers(server);
     // Start server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proctor-mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Local implementation of Proctor MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/index.d.ts

@@ -1,7 +1,8 @@
 export { createMCPServer, ProctorClient } from './server.js';
-export type { IProctorClient, ClientFactory } from './server.js';
+export type { IProctorClient, ClientFactory, CreateMCPServerOptions } from './server.js';
 export { createRegisterTools, parseEnabledToolGroups } from './tools.js';
 export type { ToolGroup } from './tools.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export { truncateStrings, deepClone } from './utils/truncation.js';
 export type { ProctorRuntime, ProctorExam, ProctorMetadataResponse, ExamLogEntry, ExamStreamLog, ExamStreamResult, ExamStreamError, ExamStreamEntry, ExamResult, RunExamParams, FlyMachine, MachinesResponse, CancelExamParams, CancelExamResponse, ApiError, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -2,3 +2,4 @@
 export { createMCPServer, ProctorClient } from './server.js';
 export { createRegisterTools, parseEnabledToolGroups } from './tools.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export { truncateStrings, deepClone } from './utils/truncation.js';

package/shared/server.d.ts

@@ -22,7 +22,10 @@ export declare class ProctorClient implements IProctorClient {
     cancelExam(params: CancelExamParams): Promise<CancelExamResponse>;
 }
 export type ClientFactory = () => IProctorClient;
-export declare function createMCPServer(): {
+export interface CreateMCPServerOptions {
+    version: string;
+}
+export declare function createMCPServer(options: CreateMCPServerOptions): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -29,10 +29,10 @@ export class ProctorClient {
         return cancelExam(this.apiKey, this.baseUrl, params);
     }
 }
-export function createMCPServer() {
+export function createMCPServer(options) {
     const server = new Server({
         name: 'proctor-mcp-server',
-        version: '0.1.2',
+        version: options.version,
     }, {
         capabilities: {
             tools: {},

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

@@ -58,6 +58,13 @@ export declare function runExam(_server: Server, clientFactory: ClientFactory):
                 };
                 required: string[];
             };
+            expand_fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: "Array of dot-notation paths to show in full (not truncated). By default, long strings (>200 chars) and deep objects in exam results are auto-truncated to reduce response size. Use this to expand specific fields. Examples: [\"tools[].inputSchema\", \"input\"].";
+            };
         };
         required: string[];
     };

package/shared/tools/run-exam.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { truncateStrings, deepClone } from '../utils/truncation.js';
 // Parameter descriptions - single source of truth
 const PARAM_DESCRIPTIONS = {
     runtime_id: 'Runtime ID from get_proctor_metadata, or "__custom__" for a custom Docker image. Example: "v0.0.37"',
@@ -100,6 +101,7 @@ When provided, these credentials are passed to proctor-mcp-client which loads th
 - client_id: OAuth client ID
 - client_secret: OAuth client secret
 - expires_at: ISO 8601 timestamp when the access token expires`,
+    expand_fields: 'Array of dot-notation paths to show in full (not truncated). By default, long strings (>200 chars) and deep objects in exam results are auto-truncated to reduce response size. Use this to expand specific fields. Examples: ["tools[].inputSchema", "input"].',
 };
 const PreloadedCredentialsSchema = z.object({
     server_key: z.string().min(1),
@@ -110,6 +112,28 @@ const PreloadedCredentialsSchema = z.object({
     client_secret: z.string().optional(),
     expires_at: z.string().optional(),
 });
+// Preprocess to transform empty/incomplete objects to undefined before validation
+// This handles cases where MCP clients send {}, null, or partial objects for optional parameters
+const preprocessPreloadedCredentials = (val) => {
+    // If undefined, null, or not an object, let it pass through (or become undefined)
+    if (val === undefined || val === null) {
+        return undefined;
+    }
+    if (typeof val !== 'object') {
+        return undefined;
+    }
+    // Check if it's an empty object or missing required fields
+    const obj = val;
+    if (Object.keys(obj).length === 0) {
+        return undefined;
+    }
+    if (!('server_key' in obj) || !('access_token' in obj)) {
+        return undefined;
+    }
+    // Has required fields, validate it properly
+    return val;
+};
+const OptionalPreloadedCredentialsSchema = z.preprocess(preprocessPreloadedCredentials, PreloadedCredentialsSchema.optional());
 const RunExamSchema = z.object({
     runtime_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.runtime_id),
     exam_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.exam_id),
@@ -117,7 +141,8 @@ const RunExamSchema = z.object({
     server_json: z.string().optional().describe(PARAM_DESCRIPTIONS.server_json),
     custom_runtime_image: z.string().optional().describe(PARAM_DESCRIPTIONS.custom_runtime_image),
     max_retries: z.number().min(0).max(10).optional().describe(PARAM_DESCRIPTIONS.max_retries),
-    preloaded_credentials: PreloadedCredentialsSchema.optional().describe(PARAM_DESCRIPTIONS.preloaded_credentials),
+    preloaded_credentials: OptionalPreloadedCredentialsSchema.optional().describe(PARAM_DESCRIPTIONS.preloaded_credentials),
+    expand_fields: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.expand_fields),
 });
 export function runExam(_server, clientFactory) {
     return {
@@ -149,7 +174,8 @@ The mcp_json parameter accepts a JSON object with server configurations. Each se
 - Use get_proctor_metadata first to discover available runtimes and exams
 - The mcp_json must be a valid JSON string representing the mcp.json format
 - Custom runtime images require the "__custom__" runtime_id and custom_runtime_image parameter
-- Underscore-prefixed fields in mcp_json are used for exam setup only and stripped before server execution`,
+- Underscore-prefixed fields in mcp_json are used for exam setup only and stripped before server execution
+- Results are auto-truncated to reduce response size. Long strings (>200 chars) and deep nested objects are replaced with truncation messages. Use the expand_fields parameter to retrieve full content for specific fields`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -191,6 +217,11 @@ The mcp_json parameter accepts a JSON object with server configurations. Each se
                     },
                     required: ['server_key', 'access_token'],
                 },
+                expand_fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.expand_fields,
+                },
             },
             required: ['runtime_id', 'exam_id', 'mcp_json'],
         },
@@ -271,8 +302,9 @@ The mcp_json parameter accepts a JSON object with server configurations. Each se
                     };
                 }
                 if (finalResult) {
+                    const truncatedResult = truncateStrings(deepClone(finalResult), validatedArgs.expand_fields || []);
                     content += '### Result\n\n```json\n';
-                    content += JSON.stringify(finalResult, null, 2);
+                    content += JSON.stringify(truncatedResult, null, 2);
                     content += '\n```\n';
                 }
                 return {

package/shared/utils/truncation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for string truncation and field expansion
+ */
+/**
+ * Recursively truncates values in an object:
+ * 1. Strings longer than 200 chars are replaced with truncation message
+ * 2. At depth >= 6, any value serializing to > 500 chars is replaced with truncation message
+ *
+ * @param obj - The object to process
+ * @param expandFields - Array of dot-notation paths to exclude from truncation
+ * @param currentPath - Current path in the object (for internal recursion)
+ * @returns Object with truncated values
+ */
+export declare function truncateStrings(obj: unknown, expandFields?: string[], currentPath?: string): unknown;
+/**
+ * Deep clones an object using JSON serialization.
+ */
+export declare function deepClone<T>(obj: T): T;
+//# sourceMappingURL=truncation.d.ts.map

package/shared/utils/truncation.js

@@ -0,0 +1,170 @@
+/**
+ * Utility functions for string truncation and field expansion
+ */
+const DEFAULT_STRING_MAX_LENGTH = 200;
+const DEEP_VALUE_MAX_LENGTH = 500;
+const DEPTH_THRESHOLD = 6; // Start truncating complex values at depth 6 (so depth 5 keys are visible)
+/**
+ * Creates truncation message with specific path for expansion.
+ * Returns a complete message (not a suffix) to ensure JSON validity.
+ */
+function getTruncationMessage(path, type) {
+    const wildcardPath = path.replace(/\[\d+\]/g, '[]');
+    if (type === 'string') {
+        return `[TRUNCATED - use expand_fields: ["${wildcardPath}"] to see full content]`;
+    }
+    return `[DEEP OBJECT TRUNCATED - use expand_fields: ["${wildcardPath}"] to see full content]`;
+}
+/**
+ * Calculates the depth of a path.
+ * Depth is counted as: each key access and each array index access.
+ * Examples:
+ *   - "results" = depth 1
+ *   - "results[0]" = depth 2
+ *   - "results[0].tools" = depth 3
+ *   - "results[0].tools[0]" = depth 4
+ *   - "results[0].tools[0].inputSchema" = depth 5
+ *   - "results[0].tools[0].inputSchema.properties" = depth 6 (truncation starts here)
+ */
+function getDepth(path) {
+    if (!path)
+        return 0;
+    let depth = 0;
+    let i = 0;
+    while (i < path.length) {
+        // Skip to the next segment
+        if (path[i] === '.') {
+            i++;
+            continue;
+        }
+        if (path[i] === '[') {
+            // Array index or bracket notation - count as one depth level
+            depth++;
+            // Skip past the closing bracket
+            const closeBracket = path.indexOf(']', i);
+            if (closeBracket === -1)
+                break;
+            i = closeBracket + 1;
+        }
+        else {
+            // Key access - count as one depth level
+            depth++;
+            // Skip to the next delimiter
+            while (i < path.length && path[i] !== '.' && path[i] !== '[') {
+                i++;
+            }
+        }
+    }
+    return depth;
+}
+/**
+ * Recursively truncates values in an object:
+ * 1. Strings longer than 200 chars are replaced with truncation message
+ * 2. At depth >= 6, any value serializing to > 500 chars is replaced with truncation message
+ *
+ * @param obj - The object to process
+ * @param expandFields - Array of dot-notation paths to exclude from truncation
+ * @param currentPath - Current path in the object (for internal recursion)
+ * @returns Object with truncated values
+ */
+export function truncateStrings(obj, expandFields = [], currentPath = '') {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    const currentDepth = getDepth(currentPath);
+    // Check if this path should be expanded (skip all truncation)
+    if (shouldExpand(currentPath, expandFields)) {
+        // Still need to recurse for nested paths that might not be expanded
+        if (Array.isArray(obj)) {
+            return obj.map((item, index) => {
+                const arrayPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+                return truncateStrings(item, expandFields, arrayPath);
+            });
+        }
+        if (typeof obj === 'object') {
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                const newPath = currentPath ? `${currentPath}.${key}` : key;
+                result[key] = truncateStrings(value, expandFields, newPath);
+            }
+            return result;
+        }
+        return obj;
+    }
+    // At depth >= DEPTH_THRESHOLD, check if the serialized value is too large
+    if (currentDepth >= DEPTH_THRESHOLD && (typeof obj === 'object' || Array.isArray(obj))) {
+        const serialized = JSON.stringify(obj);
+        if (serialized.length > DEEP_VALUE_MAX_LENGTH) {
+            // Replace the entire value with a truncation message (keeps JSON valid)
+            return getTruncationMessage(currentPath, 'deep');
+        }
+    }
+    // Handle strings - truncate if too long
+    if (typeof obj === 'string') {
+        if (obj.length > DEFAULT_STRING_MAX_LENGTH) {
+            // Replace with truncation message (keeps JSON valid)
+            return getTruncationMessage(currentPath, 'string');
+        }
+        return obj;
+    }
+    // Handle arrays
+    if (Array.isArray(obj)) {
+        return obj.map((item, index) => {
+            const arrayPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+            return truncateStrings(item, expandFields, arrayPath);
+        });
+    }
+    // Handle objects
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const newPath = currentPath ? `${currentPath}.${key}` : key;
+            result[key] = truncateStrings(value, expandFields, newPath);
+        }
+        return result;
+    }
+    // For other types (numbers, booleans, etc.), return as-is
+    return obj;
+}
+/**
+ * Checks if a path should be expanded (not truncated).
+ * Supports exact matches, prefix matches, and array wildcard notation.
+ *
+ * Examples:
+ *   - "results[0].tools[0].inputSchema" matches "results[].tools[].inputSchema"
+ *   - "results.tests" matches "results.tests"
+ *   - "results[0].tools[0].description" matches "results[].tools[].description"
+ */
+function shouldExpand(currentPath, expandFields) {
+    if (!currentPath || expandFields.length === 0) {
+        return false;
+    }
+    for (const expandPath of expandFields) {
+        // Exact match
+        if (currentPath === expandPath) {
+            return true;
+        }
+        // Check if expand path is a prefix (for nested expansion)
+        if (currentPath.startsWith(expandPath + '.') || currentPath.startsWith(expandPath + '[')) {
+            return true;
+        }
+        // Convert array indices to wildcards for comparison
+        // e.g., "results[0].tools[1].inputSchema" becomes "results[].tools[].inputSchema"
+        const normalizedCurrent = currentPath.replace(/\[\d+\]/g, '[]');
+        if (normalizedCurrent === expandPath) {
+            return true;
+        }
+        // Check prefix match with normalized path
+        if (normalizedCurrent.startsWith(expandPath + '.') ||
+            normalizedCurrent.startsWith(expandPath + '[')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Deep clones an object using JSON serialization.
+ */
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}