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

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/save-results-for-mirror.d.ts

@@ -17,30 +17,7 @@ export declare function saveResultsForMirror(_server: Server, clientFactory: Cli
             result_id: {
                 type: string;
                 format: string;
-                description: "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: {
-                type: string;
-                items: {
-                    type: string;
-                    properties: {
-                        exam_id: {
-                            type: string;
-                            description: "The exam identifier (e.g., \"auth-check\", \"init-tools-list\")";
-                        };
-                        status: {
-                            type: string;
-                            description: "The result status (e.g., \"pass\", \"fail\", \"error\", \"skip\")";
-                        };
-                        data: {
-                            type: string;
-                            additionalProperties: boolean;
-                            description: "Optional detailed result data. Sensitive fields (tokens, secrets, passwords) will be automatically redacted before storage.";
-                        };
-                    };
-                    required: string[];
-                };
-                description: "Array of exam results to save. Each result must include exam_id, status, and optional data. Only needed if result_id is not provided.";
+                description: "The UUID returned by run_exam_for_mirror. The server retrieves the full result from the local file store automatically.";
             };
         };
         required: string[];