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

package/README.md

@@ -218,7 +218,7 @@ TOOL_GROUPS=newsletter,server_directory_readonly
 - Enable or disable specific tool groups by setting `TOOL_GROUPS` environment variable
 - Use `_readonly` suffixes to restrict groups to read-only operations (e.g., `server_directory_readonly`)
 - Use the `remote` array parameter in `save_mcp_implementation` to configure remote endpoints for MCP servers (transport, host_platform, authentication_method, etc.)
-- Use the `canonical` array parameter in `save_mcp_implementation` to set canonical URLs with scope (domain, subdomain, subfolder, or url)
+- Use the `canonical` array parameter in `save_mcp_implementation` to set canonical URLs with scope (domain, subdomain, or url)
 - Remote endpoints allow specifying how MCP servers can be accessed (direct URL, setup URL, authentication method, cost, etc.)
 - When updating existing remotes, include the remote `id` (number from `get_draft_mcp_implementations`) in the remote object
 - Use `list_mcp_servers` to browse MCP servers with filtering by status (draft/live/archived) and classification (official/community)

package/build/shared/src/pulsemcp-admin-client/lib/get-proctor-runs.js

@@ -0,0 +1,68 @@
+export async function getProctorRuns(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor_runs', baseUrl);
+    if (params?.q) {
+        url.searchParams.append('q', params.q);
+    }
+    if (params?.recommended) {
+        url.searchParams.append('recommended', '1');
+    }
+    if (params?.tenant_ids) {
+        url.searchParams.append('tenant_ids', params.tenant_ids);
+    }
+    if (params?.sort) {
+        url.searchParams.append('sort', params.sort);
+    }
+    if (params?.direction) {
+        url.searchParams.append('direction', params.direction);
+    }
+    if (params?.limit) {
+        url.searchParams.append('limit', params.limit.toString());
+    }
+    if (params?.offset !== undefined && params.offset > 0) {
+        url.searchParams.append('offset', params.offset.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch proctor runs: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        runs: data.data.map((run) => ({
+            id: run.id,
+            slug: run.slug,
+            name: run.name,
+            recommended: run.recommended,
+            mirrors_count: run.mirrors_count,
+            tenant_count: run.tenant_count,
+            latest_version: run.latest_version,
+            latest_mirror_id: run.latest_mirror_id,
+            latest_mirror_name: run.latest_mirror_name,
+            latest_tested: run.latest_tested,
+            last_auth_check_days: run.last_auth_check_days,
+            last_tools_list_days: run.last_tools_list_days,
+            auth_types: run.auth_types,
+            num_tools: run.num_tools,
+            packages: run.packages,
+            remotes: run.remotes,
+        })),
+        pagination: {
+            current_page: data.meta.current_page,
+            total_pages: data.meta.total_pages,
+            total_count: data.meta.total_count,
+            has_next: data.meta.has_next,
+            limit: data.meta.limit,
+        },
+    };
+}

package/build/shared/src/pulsemcp-admin-client/pulsemcp-admin-client.integration-mock.js

@@ -958,6 +958,12 @@ export function createMockPulseMCPAdminClient(mockData) {
                 errors: [],
             };
         },
+        async getProctorRuns() {
+            return {
+                runs: [],
+                pagination: { current_page: 1, total_pages: 1, total_count: 0, has_next: false, limit: 30 },
+            };
+        },
         // Discovered URL methods
         async getDiscoveredUrls() {
             return {

package/build/shared/src/server.js

@@ -261,6 +261,10 @@ export class PulseMCPAdminClient {
         const { saveResultsForMirror } = await import('./pulsemcp-admin-client/lib/save-results-for-mirror.js');
         return saveResultsForMirror(this.apiKey, this.baseUrl, params);
     }
+    async getProctorRuns(params) {
+        const { getProctorRuns } = await import('./pulsemcp-admin-client/lib/get-proctor-runs.js');
+        return getProctorRuns(this.apiKey, this.baseUrl, params);
+    }
     // Discovered URL REST API methods
     async getDiscoveredUrls(params) {
         const { getDiscoveredUrls } = await import('./pulsemcp-admin-client/lib/get-discovered-urls.js');

package/build/shared/src/tools/get-mcp-server.js

@@ -14,7 +14,7 @@ The response includes:
 - **Basic info**: name, descriptions, status, classification, implementation language
 - **Provider**: organization/person details
 - **Source code location**: GitHub repository info with stars and last update
-- **Canonical URLs**: authoritative URLs with scope (domain, subdomain, subfolder, url)
+- **Canonical URLs**: authoritative URLs with scope (domain, subdomain, url)
 - **Remote endpoints**: all deployment endpoints with transport, platform, auth, and cost info
 - **Tags**: categorization tags
 - **Download statistics**: npm download estimates
@@ -48,7 +48,7 @@ Example response:
     "github_stars": 5000
   },
   "canonical_urls": [
-    { "url": "https://github.com/modelcontextprotocol/servers", "scope": "subfolder" }
+    { "url": "https://github.com/modelcontextprotocol/servers", "scope": "domain" }
   ],
   "remotes": [
     {

package/build/shared/src/tools/list-proctor-runs.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    q: 'Search by server slug, implementation name, or mirror name',
+    recommended: 'When true, filter to recommended servers only. When false or omitted, shows all servers',
+    tenant_ids: 'Comma-separated tenant IDs to filter by (OR logic)',
+    sort: 'Column to sort by: slug, name, mirrors, recommended, tenants, latest_tested, last_auth_check, last_tools_list',
+    direction: 'Sort direction: asc or desc. Default: asc',
+    limit: 'Results per page, range 1-100. Default: 30',
+    offset: 'Pagination offset. Default: 0',
+};
+const ListProctorRunsSchema = z.object({
+    q: z.string().optional().describe(PARAM_DESCRIPTIONS.q),
+    recommended: z.boolean().optional().describe(PARAM_DESCRIPTIONS.recommended),
+    tenant_ids: z.string().optional().describe(PARAM_DESCRIPTIONS.tenant_ids),
+    sort: z
+        .enum([
+        'slug',
+        'name',
+        'mirrors',
+        'recommended',
+        'tenants',
+        'latest_tested',
+        'last_auth_check',
+        'last_tools_list',
+    ])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.sort),
+    direction: z.enum(['asc', 'desc']).optional().describe(PARAM_DESCRIPTIONS.direction),
+    limit: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.limit),
+    offset: z.number().min(0).optional().describe(PARAM_DESCRIPTIONS.offset),
+});
+export function listProctorRuns(_server, clientFactory) {
+    return {
+        name: 'list_proctor_runs',
+        description: `List proctor run summaries for MCP servers. Shows testing status across all servers including auth-check and tools-list exam results. Useful for identifying untested servers or servers that need re-testing.
+
+Default sort order: untested servers first, then stalest auth check, then stalest tools list, then alphabetical by slug.
+
+Example response:
+{
+  "runs": [
+    {
+      "id": 123,
+      "slug": "some-server",
+      "name": "Some Server",
+      "recommended": true,
+      "mirrors_count": 2,
+      "latest_tested": true,
+      "last_auth_check_days": 2,
+      "last_tools_list_days": 3,
+      "auth_types": ["oauth2"],
+      "num_tools": 5,
+      "packages": ["npm"],
+      "remotes": ["streamable-http"]
+    }
+  ],
+  "pagination": { "current_page": 1, "total_pages": 2, "total_count": 45, "has_next": true }
+}
+
+Use cases:
+- Find servers that haven't been tested yet (untested appear first by default)
+- Check which servers have stale proctor results
+- Filter to recommended servers to prioritize testing
+- Search for a specific server's testing status`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: PARAM_DESCRIPTIONS.q },
+                recommended: { type: 'boolean', description: PARAM_DESCRIPTIONS.recommended },
+                tenant_ids: { type: 'string', description: PARAM_DESCRIPTIONS.tenant_ids },
+                sort: {
+                    type: 'string',
+                    enum: [
+                        'slug',
+                        'name',
+                        'mirrors',
+                        'recommended',
+                        'tenants',
+                        'latest_tested',
+                        'last_auth_check',
+                        'last_tools_list',
+                    ],
+                    description: PARAM_DESCRIPTIONS.sort,
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['asc', 'desc'],
+                    description: PARAM_DESCRIPTIONS.direction,
+                },
+                limit: { type: 'number', minimum: 1, maximum: 100, description: PARAM_DESCRIPTIONS.limit },
+                offset: { type: 'number', minimum: 0, description: PARAM_DESCRIPTIONS.offset },
+            },
+        },
+        handler: async (args) => {
+            const validatedArgs = ListProctorRunsSchema.parse(args);
+            const client = clientFactory();
+            try {
+                const response = await client.getProctorRuns({
+                    q: validatedArgs.q,
+                    recommended: validatedArgs.recommended,
+                    tenant_ids: validatedArgs.tenant_ids,
+                    sort: validatedArgs.sort,
+                    direction: validatedArgs.direction,
+                    limit: validatedArgs.limit,
+                    offset: validatedArgs.offset,
+                });
+                let content = `Found ${response.runs.length} proctor run summaries`;
+                if (response.pagination) {
+                    content += ` (page ${response.pagination.current_page} of ${response.pagination.total_pages}, total: ${response.pagination.total_count})`;
+                }
+                content += ':\n\n';
+                for (const [index, run] of response.runs.entries()) {
+                    content += `${index + 1}. **${run.slug}**`;
+                    if (run.name) {
+                        content += ` — ${run.name}`;
+                    }
+                    content += ` (ID: ${run.id})\n`;
+                    if (run.recommended) {
+                        content += `   Recommended: yes\n`;
+                    }
+                    content += `   Mirrors: ${run.mirrors_count}, Tenants: ${run.tenant_count}\n`;
+                    if (run.latest_version) {
+                        content += `   Latest Version: ${run.latest_version}`;
+                        if (run.latest_mirror_name) {
+                            content += ` (mirror: ${run.latest_mirror_name}, ID: ${run.latest_mirror_id})`;
+                        }
+                        content += '\n';
+                    }
+                    content += `   Latest Tested: ${run.latest_tested ? 'yes' : 'no'}\n`;
+                    if (run.last_auth_check_days !== null) {
+                        content += `   Last Auth Check: ${run.last_auth_check_days} day(s) ago\n`;
+                    }
+                    else {
+                        content += `   Last Auth Check: never\n`;
+                    }
+                    if (run.last_tools_list_days !== null) {
+                        content += `   Last Tools List: ${run.last_tools_list_days} day(s) ago\n`;
+                    }
+                    else {
+                        content += `   Last Tools List: never\n`;
+                    }
+                    if (run.auth_types.length > 0) {
+                        content += `   Auth Types: ${run.auth_types.join(', ')}\n`;
+                    }
+                    if (run.num_tools !== null) {
+                        content += `   Num Tools: ${run.num_tools}\n`;
+                    }
+                    if (run.packages.length > 0) {
+                        content += `   Packages: ${run.packages.join(', ')}\n`;
+                    }
+                    if (run.remotes.length > 0) {
+                        content += `   Remotes: ${run.remotes.join(', ')}\n`;
+                    }
+                    content += '\n';
+                }
+                return { content: [{ type: 'text', text: content.trim() }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching proctor runs: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/build/shared/src/tools/save-mcp-implementation.js

@@ -26,7 +26,7 @@ const PARAM_DESCRIPTIONS = {
     // Remote endpoints
     remote: 'Array of remote endpoint configurations for MCP servers. Each remote can have: id (existing remote ID or blank for new), url_direct, url_setup, transport (e.g., "sse"), host_platform (e.g., "smithery"), host_infrastructure (e.g., "cloudflare"), authentication_method (e.g., "open"), cost (e.g., "free"), status (defaults to "live"), display_name, and internal_notes.',
     // Canonical URLs
-    canonical: 'Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", "subfolder", or "url"), and optional note for additional context.',
+    canonical: 'Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", or "url"), and optional note for additional context.',
     // Other fields
     internal_notes: 'Admin-only notes. Not displayed publicly. Used for tracking submission sources, reviewer comments, etc.',
 };
@@ -83,7 +83,7 @@ const SaveMCPImplementationSchema = z.object({
     canonical: z
         .array(z.object({
         url: z.string(),
-        scope: z.enum(['domain', 'subdomain', 'subfolder', 'url']),
+        scope: z.enum(['domain', 'subdomain', 'url']),
         note: z.string().optional(),
     }))
         .optional()
@@ -294,7 +294,7 @@ Use cases:
                         type: 'object',
                         properties: {
                             url: { type: 'string' },
-                            scope: { type: 'string', enum: ['domain', 'subdomain', 'subfolder', 'url'] },
+                            scope: { type: 'string', enum: ['domain', 'subdomain', 'url'] },
                             note: { type: 'string' },
                         },
                         required: ['url', 'scope'],

package/build/shared/src/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/build/shared/src/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulsemcp-cms-admin-mcp-server",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Local implementation of PulseMCP CMS Admin MCP server",
   "mcpName": "com.pulsemcp.servers/pulsemcp-cms-admin",
   "main": "build/index.js",

package/shared/pulsemcp-admin-client/lib/get-proctor-runs.d.ts

@@ -0,0 +1,11 @@
+import type { ProctorRunsResponse } from '../../types.js';
+export declare function getProctorRuns(apiKey: string, baseUrl: string, params?: {
+    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;
+}): Promise<ProctorRunsResponse>;
+//# sourceMappingURL=get-proctor-runs.d.ts.map

package/shared/pulsemcp-admin-client/lib/get-proctor-runs.js

@@ -0,0 +1,68 @@
+export async function getProctorRuns(apiKey, baseUrl, params) {
+    const url = new URL('/api/proctor_runs', baseUrl);
+    if (params?.q) {
+        url.searchParams.append('q', params.q);
+    }
+    if (params?.recommended) {
+        url.searchParams.append('recommended', '1');
+    }
+    if (params?.tenant_ids) {
+        url.searchParams.append('tenant_ids', params.tenant_ids);
+    }
+    if (params?.sort) {
+        url.searchParams.append('sort', params.sort);
+    }
+    if (params?.direction) {
+        url.searchParams.append('direction', params.direction);
+    }
+    if (params?.limit) {
+        url.searchParams.append('limit', params.limit.toString());
+    }
+    if (params?.offset !== undefined && params.offset > 0) {
+        url.searchParams.append('offset', params.offset.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch proctor runs: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        runs: data.data.map((run) => ({
+            id: run.id,
+            slug: run.slug,
+            name: run.name,
+            recommended: run.recommended,
+            mirrors_count: run.mirrors_count,
+            tenant_count: run.tenant_count,
+            latest_version: run.latest_version,
+            latest_mirror_id: run.latest_mirror_id,
+            latest_mirror_name: run.latest_mirror_name,
+            latest_tested: run.latest_tested,
+            last_auth_check_days: run.last_auth_check_days,
+            last_tools_list_days: run.last_tools_list_days,
+            auth_types: run.auth_types,
+            num_tools: run.num_tools,
+            packages: run.packages,
+            remotes: run.remotes,
+        })),
+        pagination: {
+            current_page: data.meta.current_page,
+            total_pages: data.meta.total_pages,
+            total_count: data.meta.total_count,
+            has_next: data.meta.has_next,
+            limit: data.meta.limit,
+        },
+    };
+}

package/shared/pulsemcp-admin-client/pulsemcp-admin-client.integration-mock.js

@@ -958,6 +958,12 @@ export function createMockPulseMCPAdminClient(mockData) {
                 errors: [],
             };
         },
+        async getProctorRuns() {
+            return {
+                runs: [],
+                pagination: { current_page: 1, total_pages: 1, total_count: 0, has_next: false, limit: 30 },
+            };
+        },
         // Discovered URL methods
         async getDiscoveredUrls() {
             return {

package/shared/server.d.ts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Post, PostsResponse, CreatePostParams, UpdatePostParams, ImageUploadResponse, Author, AuthorsResponse, MCPServer, MCPClient, MCPImplementation, MCPImplementationsResponse, SaveMCPImplementationParams, CreateMCPImplementationParams, Provider, ProvidersResponse, OfficialMirrorQueueStatus, OfficialMirrorQueueResponse, OfficialMirrorQueueItemDetail, OfficialMirrorQueueActionResponse, UnofficialMirror, UnofficialMirrorsResponse, CreateUnofficialMirrorParams, UpdateUnofficialMirrorParams, OfficialMirrorRest, OfficialMirrorsResponse, Tenant, TenantsResponse, McpJson, McpJsonsResponse, CreateMcpJsonParams, UpdateMcpJsonParams, UnifiedMCPServer, UnifiedMCPServersResponse, UpdateUnifiedMCPServerParams, Redirect, RedirectsResponse, RedirectStatus, CreateRedirectParams, UpdateRedirectParams, GoodJob, GoodJobsResponse, GoodJobStatus, GoodJobCronSchedule, GoodJobProcess, GoodJobStatistics, GoodJobActionResponse, GoodJobCleanupResponse, ProctorRunExamParams, ProctorRunExamResponse, ProctorSaveResultsParams, ProctorSaveResultsResponse, DiscoveredUrlsResponse, MarkDiscoveredUrlProcessedParams, MarkDiscoveredUrlProcessedResponse, DiscoveredUrlStats } from './types.js';
+import type { Post, PostsResponse, CreatePostParams, UpdatePostParams, ImageUploadResponse, Author, AuthorsResponse, MCPServer, MCPClient, MCPImplementation, MCPImplementationsResponse, SaveMCPImplementationParams, CreateMCPImplementationParams, Provider, ProvidersResponse, OfficialMirrorQueueStatus, OfficialMirrorQueueResponse, OfficialMirrorQueueItemDetail, OfficialMirrorQueueActionResponse, UnofficialMirror, UnofficialMirrorsResponse, CreateUnofficialMirrorParams, UpdateUnofficialMirrorParams, OfficialMirrorRest, OfficialMirrorsResponse, Tenant, TenantsResponse, McpJson, McpJsonsResponse, CreateMcpJsonParams, UpdateMcpJsonParams, UnifiedMCPServer, UnifiedMCPServersResponse, UpdateUnifiedMCPServerParams, Redirect, RedirectsResponse, RedirectStatus, CreateRedirectParams, UpdateRedirectParams, GoodJob, GoodJobsResponse, GoodJobStatus, GoodJobCronSchedule, GoodJobProcess, GoodJobStatistics, GoodJobActionResponse, GoodJobCleanupResponse, ProctorRunExamParams, ProctorRunExamResponse, ProctorSaveResultsParams, ProctorSaveResultsResponse, ProctorRunsResponse, GetProctorRunsParams, DiscoveredUrlsResponse, MarkDiscoveredUrlProcessedParams, MarkDiscoveredUrlProcessedResponse, DiscoveredUrlStats } from './types.js';
 export interface IPulseMCPAdminClient {
     getPosts(params?: {
         search?: string;
@@ -160,6 +160,7 @@ export interface IPulseMCPAdminClient {
     }): Promise<GoodJobCleanupResponse>;
     runExamForMirror(params: ProctorRunExamParams): Promise<ProctorRunExamResponse>;
     saveResultsForMirror(params: ProctorSaveResultsParams): Promise<ProctorSaveResultsResponse>;
+    getProctorRuns(params?: GetProctorRunsParams): Promise<ProctorRunsResponse>;
     getDiscoveredUrls(params?: {
         status?: 'pending' | 'processed' | 'all';
         page?: number;
@@ -331,6 +332,7 @@ export declare class PulseMCPAdminClient implements IPulseMCPAdminClient {
     }): Promise<GoodJobCleanupResponse>;
     runExamForMirror(params: ProctorRunExamParams): Promise<ProctorRunExamResponse>;
     saveResultsForMirror(params: ProctorSaveResultsParams): Promise<ProctorSaveResultsResponse>;
+    getProctorRuns(params?: GetProctorRunsParams): Promise<ProctorRunsResponse>;
     getDiscoveredUrls(params?: {
         status?: 'pending' | 'processed' | 'all';
         page?: number;

package/shared/server.js

@@ -261,6 +261,10 @@ export class PulseMCPAdminClient {
         const { saveResultsForMirror } = await import('./pulsemcp-admin-client/lib/save-results-for-mirror.js');
         return saveResultsForMirror(this.apiKey, this.baseUrl, params);
     }
+    async getProctorRuns(params) {
+        const { getProctorRuns } = await import('./pulsemcp-admin-client/lib/get-proctor-runs.js');
+        return getProctorRuns(this.apiKey, this.baseUrl, params);
+    }
     // Discovered URL REST API methods
     async getDiscoveredUrls(params) {
         const { getDiscoveredUrls } = await import('./pulsemcp-admin-client/lib/get-discovered-urls.js');

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

@@ -14,7 +14,7 @@ The response includes:
 - **Basic info**: name, descriptions, status, classification, implementation language
 - **Provider**: organization/person details
 - **Source code location**: GitHub repository info with stars and last update
-- **Canonical URLs**: authoritative URLs with scope (domain, subdomain, subfolder, url)
+- **Canonical URLs**: authoritative URLs with scope (domain, subdomain, url)
 - **Remote endpoints**: all deployment endpoints with transport, platform, auth, and cost info
 - **Tags**: categorization tags
 - **Download statistics**: npm download estimates
@@ -48,7 +48,7 @@ Example response:
     "github_stars": 5000
   },
   "canonical_urls": [
-    { "url": "https://github.com/modelcontextprotocol/servers", "scope": "subfolder" }
+    { "url": "https://github.com/modelcontextprotocol/servers", "scope": "domain" }
   ],
   "remotes": [
     {

package/shared/tools/list-proctor-runs.d.ts

@@ -0,0 +1,58 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function listProctorRuns(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            q: {
+                type: string;
+                description: "Search by server slug, implementation name, or mirror name";
+            };
+            recommended: {
+                type: string;
+                description: "When true, filter to recommended servers only. When false or omitted, shows all servers";
+            };
+            tenant_ids: {
+                type: string;
+                description: "Comma-separated tenant IDs to filter by (OR logic)";
+            };
+            sort: {
+                type: string;
+                enum: string[];
+                description: "Column to sort by: slug, name, mirrors, recommended, tenants, latest_tested, last_auth_check, last_tools_list";
+            };
+            direction: {
+                type: string;
+                enum: string[];
+                description: "Sort direction: asc or desc. Default: asc";
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: "Results per page, range 1-100. Default: 30";
+            };
+            offset: {
+                type: string;
+                minimum: number;
+                description: "Pagination offset. Default: 0";
+            };
+        };
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=list-proctor-runs.d.ts.map

package/shared/tools/list-proctor-runs.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    q: 'Search by server slug, implementation name, or mirror name',
+    recommended: 'When true, filter to recommended servers only. When false or omitted, shows all servers',
+    tenant_ids: 'Comma-separated tenant IDs to filter by (OR logic)',
+    sort: 'Column to sort by: slug, name, mirrors, recommended, tenants, latest_tested, last_auth_check, last_tools_list',
+    direction: 'Sort direction: asc or desc. Default: asc',
+    limit: 'Results per page, range 1-100. Default: 30',
+    offset: 'Pagination offset. Default: 0',
+};
+const ListProctorRunsSchema = z.object({
+    q: z.string().optional().describe(PARAM_DESCRIPTIONS.q),
+    recommended: z.boolean().optional().describe(PARAM_DESCRIPTIONS.recommended),
+    tenant_ids: z.string().optional().describe(PARAM_DESCRIPTIONS.tenant_ids),
+    sort: z
+        .enum([
+        'slug',
+        'name',
+        'mirrors',
+        'recommended',
+        'tenants',
+        'latest_tested',
+        'last_auth_check',
+        'last_tools_list',
+    ])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.sort),
+    direction: z.enum(['asc', 'desc']).optional().describe(PARAM_DESCRIPTIONS.direction),
+    limit: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.limit),
+    offset: z.number().min(0).optional().describe(PARAM_DESCRIPTIONS.offset),
+});
+export function listProctorRuns(_server, clientFactory) {
+    return {
+        name: 'list_proctor_runs',
+        description: `List proctor run summaries for MCP servers. Shows testing status across all servers including auth-check and tools-list exam results. Useful for identifying untested servers or servers that need re-testing.
+
+Default sort order: untested servers first, then stalest auth check, then stalest tools list, then alphabetical by slug.
+
+Example response:
+{
+  "runs": [
+    {
+      "id": 123,
+      "slug": "some-server",
+      "name": "Some Server",
+      "recommended": true,
+      "mirrors_count": 2,
+      "latest_tested": true,
+      "last_auth_check_days": 2,
+      "last_tools_list_days": 3,
+      "auth_types": ["oauth2"],
+      "num_tools": 5,
+      "packages": ["npm"],
+      "remotes": ["streamable-http"]
+    }
+  ],
+  "pagination": { "current_page": 1, "total_pages": 2, "total_count": 45, "has_next": true }
+}
+
+Use cases:
+- Find servers that haven't been tested yet (untested appear first by default)
+- Check which servers have stale proctor results
+- Filter to recommended servers to prioritize testing
+- Search for a specific server's testing status`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: PARAM_DESCRIPTIONS.q },
+                recommended: { type: 'boolean', description: PARAM_DESCRIPTIONS.recommended },
+                tenant_ids: { type: 'string', description: PARAM_DESCRIPTIONS.tenant_ids },
+                sort: {
+                    type: 'string',
+                    enum: [
+                        'slug',
+                        'name',
+                        'mirrors',
+                        'recommended',
+                        'tenants',
+                        'latest_tested',
+                        'last_auth_check',
+                        'last_tools_list',
+                    ],
+                    description: PARAM_DESCRIPTIONS.sort,
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['asc', 'desc'],
+                    description: PARAM_DESCRIPTIONS.direction,
+                },
+                limit: { type: 'number', minimum: 1, maximum: 100, description: PARAM_DESCRIPTIONS.limit },
+                offset: { type: 'number', minimum: 0, description: PARAM_DESCRIPTIONS.offset },
+            },
+        },
+        handler: async (args) => {
+            const validatedArgs = ListProctorRunsSchema.parse(args);
+            const client = clientFactory();
+            try {
+                const response = await client.getProctorRuns({
+                    q: validatedArgs.q,
+                    recommended: validatedArgs.recommended,
+                    tenant_ids: validatedArgs.tenant_ids,
+                    sort: validatedArgs.sort,
+                    direction: validatedArgs.direction,
+                    limit: validatedArgs.limit,
+                    offset: validatedArgs.offset,
+                });
+                let content = `Found ${response.runs.length} proctor run summaries`;
+                if (response.pagination) {
+                    content += ` (page ${response.pagination.current_page} of ${response.pagination.total_pages}, total: ${response.pagination.total_count})`;
+                }
+                content += ':\n\n';
+                for (const [index, run] of response.runs.entries()) {
+                    content += `${index + 1}. **${run.slug}**`;
+                    if (run.name) {
+                        content += ` — ${run.name}`;
+                    }
+                    content += ` (ID: ${run.id})\n`;
+                    if (run.recommended) {
+                        content += `   Recommended: yes\n`;
+                    }
+                    content += `   Mirrors: ${run.mirrors_count}, Tenants: ${run.tenant_count}\n`;
+                    if (run.latest_version) {
+                        content += `   Latest Version: ${run.latest_version}`;
+                        if (run.latest_mirror_name) {
+                            content += ` (mirror: ${run.latest_mirror_name}, ID: ${run.latest_mirror_id})`;
+                        }
+                        content += '\n';
+                    }
+                    content += `   Latest Tested: ${run.latest_tested ? 'yes' : 'no'}\n`;
+                    if (run.last_auth_check_days !== null) {
+                        content += `   Last Auth Check: ${run.last_auth_check_days} day(s) ago\n`;
+                    }
+                    else {
+                        content += `   Last Auth Check: never\n`;
+                    }
+                    if (run.last_tools_list_days !== null) {
+                        content += `   Last Tools List: ${run.last_tools_list_days} day(s) ago\n`;
+                    }
+                    else {
+                        content += `   Last Tools List: never\n`;
+                    }
+                    if (run.auth_types.length > 0) {
+                        content += `   Auth Types: ${run.auth_types.join(', ')}\n`;
+                    }
+                    if (run.num_tools !== null) {
+                        content += `   Num Tools: ${run.num_tools}\n`;
+                    }
+                    if (run.packages.length > 0) {
+                        content += `   Packages: ${run.packages.join(', ')}\n`;
+                    }
+                    if (run.remotes.length > 0) {
+                        content += `   Remotes: ${run.remotes.join(', ')}\n`;
+                    }
+                    content += '\n';
+                }
+                return { content: [{ type: 'text', text: content.trim() }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching proctor runs: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/save-mcp-implementation.d.ts

@@ -149,7 +149,7 @@ export declare function saveMCPImplementation(_server: Server, clientFactory: Cl
                     };
                     required: string[];
                 };
-                description: "Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of \"domain\", \"subdomain\", \"subfolder\", or \"url\"), and optional note for additional context.";
+                description: "Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of \"domain\", \"subdomain\", or \"url\"), and optional note for additional context.";
             };
             internal_notes: {
                 type: string;

package/shared/tools/save-mcp-implementation.js

@@ -26,7 +26,7 @@ const PARAM_DESCRIPTIONS = {
     // Remote endpoints
     remote: 'Array of remote endpoint configurations for MCP servers. Each remote can have: id (existing remote ID or blank for new), url_direct, url_setup, transport (e.g., "sse"), host_platform (e.g., "smithery"), host_infrastructure (e.g., "cloudflare"), authentication_method (e.g., "open"), cost (e.g., "free"), status (defaults to "live"), display_name, and internal_notes.',
     // Canonical URLs
-    canonical: 'Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", "subfolder", or "url"), and optional note for additional context.',
+    canonical: 'Array of canonical URL configurations. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", or "url"), and optional note for additional context.',
     // Other fields
     internal_notes: 'Admin-only notes. Not displayed publicly. Used for tracking submission sources, reviewer comments, etc.',
 };
@@ -83,7 +83,7 @@ const SaveMCPImplementationSchema = z.object({
     canonical: z
         .array(z.object({
         url: z.string(),
-        scope: z.enum(['domain', 'subdomain', 'subfolder', 'url']),
+        scope: z.enum(['domain', 'subdomain', 'url']),
         note: z.string().optional(),
     }))
         .optional()
@@ -294,7 +294,7 @@ Use cases:
                         type: 'object',
                         properties: {
                             url: { type: 'string' },
-                            scope: { type: 'string', enum: ['domain', 'subdomain', 'subfolder', 'url'] },
+                            scope: { type: 'string', enum: ['domain', 'subdomain', 'url'] },
                             note: { type: 'string' },
                         },
                         required: ['url', 'scope'],

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;