pulsemcp-cms-admin-mcp-server 0.3.0 → 0.3.2

package/build/shared/src/pulsemcp-admin-client/lib/get-provider-by-id.js

@@ -0,0 +1,24 @@
+export async function getProviderById(apiKey, baseUrl, id) {
+    const url = new URL(`/api/providers/${id}`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (response.status === 404) {
+        return null;
+    }
+    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 provider: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/save-mcp-implementation.js

@@ -67,50 +67,52 @@ export async function saveMCPImplementation(apiKey, baseUrl, id, params) {
         formData.append('mcp_implementation[internal_notes]', params.internal_notes);
     }
     // Remote endpoints
+    // Rails expects nested attributes to use the _attributes suffix for has_many associations
     if (params.remote !== undefined && params.remote.length > 0) {
         params.remote.forEach((remote, index) => {
             if (remote.id !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][id]`, remote.id.toString());
+                formData.append(`mcp_implementation[remote_attributes][${index}][id]`, remote.id.toString());
             }
             if (remote.url_direct !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][url_direct]`, remote.url_direct);
+                formData.append(`mcp_implementation[remote_attributes][${index}][url_direct]`, remote.url_direct);
             }
             if (remote.url_setup !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][url_setup]`, remote.url_setup);
+                formData.append(`mcp_implementation[remote_attributes][${index}][url_setup]`, remote.url_setup);
             }
             if (remote.transport !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][transport]`, remote.transport);
+                formData.append(`mcp_implementation[remote_attributes][${index}][transport]`, remote.transport);
             }
             if (remote.host_platform !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][host_platform]`, remote.host_platform);
+                formData.append(`mcp_implementation[remote_attributes][${index}][host_platform]`, remote.host_platform);
             }
             if (remote.host_infrastructure !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][host_infrastructure]`, remote.host_infrastructure);
+                formData.append(`mcp_implementation[remote_attributes][${index}][host_infrastructure]`, remote.host_infrastructure);
             }
             if (remote.authentication_method !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][authentication_method]`, remote.authentication_method);
+                formData.append(`mcp_implementation[remote_attributes][${index}][authentication_method]`, remote.authentication_method);
             }
             if (remote.cost !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][cost]`, remote.cost);
+                formData.append(`mcp_implementation[remote_attributes][${index}][cost]`, remote.cost);
             }
             if (remote.status !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][status]`, remote.status);
+                formData.append(`mcp_implementation[remote_attributes][${index}][status]`, remote.status);
             }
             if (remote.display_name !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][display_name]`, remote.display_name);
+                formData.append(`mcp_implementation[remote_attributes][${index}][display_name]`, remote.display_name);
             }
             if (remote.internal_notes !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][internal_notes]`, remote.internal_notes);
+                formData.append(`mcp_implementation[remote_attributes][${index}][internal_notes]`, remote.internal_notes);
             }
         });
     }
     // Canonical URLs
+    // Rails expects nested attributes to use the _attributes suffix for has_many associations
     if (params.canonical !== undefined && params.canonical.length > 0) {
         params.canonical.forEach((canonicalUrl, index) => {
-            formData.append(`mcp_implementation[canonical][${index}][url]`, canonicalUrl.url);
-            formData.append(`mcp_implementation[canonical][${index}][scope]`, canonicalUrl.scope);
+            formData.append(`mcp_implementation[canonical_attributes][${index}][url]`, canonicalUrl.url);
+            formData.append(`mcp_implementation[canonical_attributes][${index}][scope]`, canonicalUrl.scope);
             if (canonicalUrl.note !== undefined) {
-                formData.append(`mcp_implementation[canonical][${index}][note]`, canonicalUrl.note);
+                formData.append(`mcp_implementation[canonical_attributes][${index}][note]`, canonicalUrl.note);
             }
         });
     }

package/build/shared/src/pulsemcp-admin-client/lib/search-providers.js

@@ -0,0 +1,45 @@
+export async function searchProviders(apiKey, baseUrl, params) {
+    // Endpoint implemented at: /api/providers/search
+    // Requires admin authentication via X-API-Key header
+    const url = new URL('/api/providers/search', baseUrl);
+    // Add query parameters
+    url.searchParams.append('q', params.query);
+    if (params.limit) {
+        url.searchParams.append('limit', params.limit.toString());
+    }
+    if (params.offset) {
+        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');
+        }
+        if (response.status === 404) {
+            throw new Error('Providers search endpoint not found');
+        }
+        throw new Error(`Failed to search providers: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        providers: data.data || [],
+        pagination: data.meta
+            ? {
+                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,
+            }
+            : undefined,
+    };
+}

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

@@ -334,5 +334,68 @@ export function createMockPulseMCPAdminClient(mockData) {
                 updated_at: new Date().toISOString(),
             };
         },
+        async searchProviders(params) {
+            if (mockData.errors?.searchProviders) {
+                throw mockData.errors.searchProviders;
+            }
+            if (mockData.providersResponse) {
+                return mockData.providersResponse;
+            }
+            let providers = mockData.providers || [
+                {
+                    id: 1,
+                    name: 'Test Provider',
+                    slug: 'test-provider',
+                    url: 'https://testprovider.com',
+                    implementations_count: 5,
+                    created_at: '2024-01-01T00:00:00Z',
+                    updated_at: '2024-01-01T00:00:00Z',
+                },
+            ];
+            // Apply search filter
+            if (params.query) {
+                const query = params.query.toLowerCase();
+                providers = providers.filter((provider) => provider.name.toLowerCase().includes(query) ||
+                    provider.slug.toLowerCase().includes(query) ||
+                    (provider.url && provider.url.toLowerCase().includes(query)));
+            }
+            // Apply pagination
+            const offset = params.offset || 0;
+            const limit = params.limit || 30;
+            const totalCount = providers.length;
+            const paginatedProviders = providers.slice(offset, offset + limit);
+            return {
+                providers: paginatedProviders,
+                pagination: {
+                    current_page: Math.floor(offset / limit) + 1,
+                    total_pages: Math.ceil(totalCount / limit),
+                    total_count: totalCount,
+                    has_next: offset + limit < totalCount,
+                    limit: limit,
+                },
+            };
+        },
+        async getProviderById(id) {
+            if (mockData.errors?.getProviderById) {
+                throw mockData.errors.getProviderById;
+            }
+            // Find provider in mock data by ID
+            const providers = mockData.providers || [
+                {
+                    id: 1,
+                    name: 'Test Provider',
+                    slug: 'test-provider',
+                    url: 'https://testprovider.com',
+                    implementations_count: 5,
+                    created_at: '2024-01-01T00:00:00Z',
+                    updated_at: '2024-01-01T00:00:00Z',
+                },
+            ];
+            const found = providers.find((p) => p.id === id);
+            if (found)
+                return found;
+            // Return null if not found
+            return null;
+        },
     };
 }

package/build/shared/src/server.js

@@ -75,6 +75,14 @@ export class PulseMCPAdminClient {
         const { sendEmail } = await import('./pulsemcp-admin-client/lib/send-email.js');
         return sendEmail(this.apiKey, this.baseUrl, params);
     }
+    async searchProviders(params) {
+        const { searchProviders } = await import('./pulsemcp-admin-client/lib/search-providers.js');
+        return searchProviders(this.apiKey, this.baseUrl, params);
+    }
+    async getProviderById(id) {
+        const { getProviderById } = await import('./pulsemcp-admin-client/lib/get-provider-by-id.js');
+        return getProviderById(this.apiKey, this.baseUrl, id);
+    }
 }
 export function createMCPServer() {
     const server = new Server({

package/build/shared/src/tools/find-providers.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+// Parameter descriptions - single source of truth
+const PARAM_DESCRIPTIONS = {
+    id: 'Provider ID to retrieve a specific provider',
+    query: 'Search query to find providers by name, URL, or slug',
+    limit: 'Maximum number of results to return (1-100, default: 30)',
+    offset: 'Number of results to skip for pagination (default: 0)',
+};
+const FindProvidersSchema = z
+    .object({
+    id: z.number().int().positive().optional().describe(PARAM_DESCRIPTIONS.id),
+    query: z.string().min(1).optional().describe(PARAM_DESCRIPTIONS.query),
+    limit: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.limit),
+    offset: z.number().min(0).optional().describe(PARAM_DESCRIPTIONS.offset),
+})
+    .refine((data) => data.id !== undefined || data.query !== undefined, {
+    message: 'Either id or query must be provided',
+});
+export function findProviders(_server, clientFactory) {
+    return {
+        name: 'find_providers',
+        description: `Find providers (organizations/individuals) in the PulseMCP registry.
+
+This tool can operate in two modes:
+
+1. **Find by ID**: Retrieve a specific provider by its numeric ID
+   - Returns a single provider with detailed information
+   - Returns null if not found
+
+2. **Search by query**: Search for providers by name, URL, or slug
+   - Searches across provider name, URL, and slug fields (case-insensitive)
+   - Returns a list of matching providers with pagination support
+   - Each result includes implementation counts
+
+Provider information includes:
+- ID and slug
+- Name and URL
+- Number of associated implementations
+- Creation and update timestamps
+
+Use cases:
+- Look up a specific provider by ID
+- Search for providers by name (e.g., "anthropic", "modelcontextprotocol")
+- Find providers by partial name matches
+- Discover all providers for an organization
+- Check how many implementations a provider has published
+
+Note: This tool queries the PulseMCP registry API. Results depend on what has been published to the registry.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.id,
+                },
+                query: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.query,
+                },
+                limit: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.limit,
+                },
+                offset: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.offset,
+                },
+            },
+        },
+        handler: async (args) => {
+            const validatedArgs = FindProvidersSchema.parse(args);
+            const client = clientFactory();
+            try {
+                // Mode 1: Find by ID
+                if (validatedArgs.id !== undefined) {
+                    const provider = await client.getProviderById(validatedArgs.id);
+                    if (!provider) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Provider with ID ${validatedArgs.id} not found.`,
+                                },
+                            ],
+                        };
+                    }
+                    let content = `**${provider.name}**\n`;
+                    content += `ID: ${provider.id}\n`;
+                    content += `Slug: ${provider.slug}\n`;
+                    if (provider.url) {
+                        content += `URL: ${provider.url}\n`;
+                    }
+                    if (provider.implementations_count !== undefined) {
+                        content += `Implementations: ${provider.implementations_count}\n`;
+                    }
+                    if (provider.created_at) {
+                        content += `Created: ${provider.created_at}\n`;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: content.trim(),
+                            },
+                        ],
+                    };
+                }
+                // Mode 2: Search by query
+                if (validatedArgs.query !== undefined) {
+                    const response = await client.searchProviders({
+                        query: validatedArgs.query,
+                        limit: validatedArgs.limit,
+                        offset: validatedArgs.offset,
+                    });
+                    let content = `Found ${response.providers.length} provider(s) matching "${validatedArgs.query}"`;
+                    if (response.pagination) {
+                        content += ` (showing ${response.providers.length} of ${response.pagination.total_count} total)`;
+                    }
+                    content += ':\n\n';
+                    for (const [index, provider] of response.providers.entries()) {
+                        content += `${index + 1}. **${provider.name}**\n`;
+                        content += `   ID: ${provider.id} | Slug: ${provider.slug}\n`;
+                        if (provider.url) {
+                            content += `   URL: ${provider.url}\n`;
+                        }
+                        if (provider.implementations_count !== undefined) {
+                            content += `   Implementations: ${provider.implementations_count}\n`;
+                        }
+                        content += '\n';
+                    }
+                    if (response.pagination?.has_next) {
+                        const nextOffset = (validatedArgs.offset || 0) + (validatedArgs.limit || 30);
+                        content += `\n---\nMore results available. Use offset=${nextOffset} to see the next page.`;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: content.trim(),
+                            },
+                        ],
+                    };
+                }
+                // This should never happen due to zod refinement, but TypeScript needs it
+                throw new Error('Either id or query must be provided');
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error finding providers: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/build/shared/src/tools/search-mcp-implementations.js

@@ -38,6 +38,8 @@ Returns a list of matching implementations with their metadata, including:
 - GitHub stars and popularity metrics
 - Associated MCP server/client IDs
 - PulseMCP web URL
+- Remote endpoints (for servers) - hosting platforms, transport methods, authentication
+- Canonical URLs - authoritative sources for the implementation
 
 Use cases:
 - Find existing MCP servers before creating a new one
@@ -96,6 +98,7 @@ Note: This tool queries the PulseMCP registry API. Results depend on what has be
                 content += ':\n\n';
                 for (const [index, impl] of response.implementations.entries()) {
                     content += `${index + 1}. **${impl.name}** (${impl.type})\n`;
+                    content += `   ID: ${impl.id}\n`;
                     content += `   Slug: ${impl.slug}\n`;
                     content += `   Status: ${impl.status}`;
                     if (impl.classification) {
@@ -124,6 +127,40 @@ Note: This tool queries the PulseMCP registry API. Results depend on what has be
                     if (impl.mcp_client_id) {
                         content += `   MCP Client ID: ${impl.mcp_client_id}\n`;
                     }
+                    // Display remote endpoints if available
+                    if (impl.mcp_server?.remotes && impl.mcp_server.remotes.length > 0) {
+                        content += `   Remotes (${impl.mcp_server.remotes.length}):\n`;
+                        for (const remote of impl.mcp_server.remotes) {
+                            let remoteLine = `     - ${remote.display_name || remote.url_direct || remote.url_setup || 'Unnamed'}`;
+                            const attrs = [];
+                            if (remote.transport)
+                                attrs.push(remote.transport);
+                            if (remote.host_platform)
+                                attrs.push(remote.host_platform);
+                            if (remote.authentication_method)
+                                attrs.push(`auth: ${remote.authentication_method}`);
+                            if (remote.cost)
+                                attrs.push(remote.cost);
+                            if (attrs.length > 0) {
+                                remoteLine += ` [${attrs.join(', ')}]`;
+                            }
+                            content += remoteLine + '\n';
+                        }
+                    }
+                    else if (impl.mcp_server?.mcp_server_remotes_count) {
+                        content += `   Remotes Count: ${impl.mcp_server.mcp_server_remotes_count}\n`;
+                    }
+                    // Display canonical URLs if available
+                    if (impl.canonical && impl.canonical.length > 0) {
+                        content += `   Canonical URLs (${impl.canonical.length}):\n`;
+                        for (const canonical of impl.canonical) {
+                            let canonicalLine = `     - ${canonical.url} [scope: ${canonical.scope}]`;
+                            if (canonical.note) {
+                                canonicalLine += ` - ${canonical.note}`;
+                            }
+                            content += canonicalLine + '\n';
+                        }
+                    }
                     content += '\n';
                 }
                 if (response.pagination?.has_next) {

package/build/shared/src/tools.js

@@ -9,6 +9,7 @@ import { searchMCPImplementations } from './tools/search-mcp-implementations.js'
 import { getDraftMCPImplementations } from './tools/get-draft-mcp-implementations.js';
 import { saveMCPImplementation } from './tools/save-mcp-implementation.js';
 import { sendMCPImplementationPostingNotification } from './tools/send-mcp-implementation-posting-notification.js';
+import { findProviders } from './tools/find-providers.js';
 const ALL_TOOLS = [
     { factory: getNewsletterPosts, groups: ['newsletter'] },
     { factory: getNewsletterPost, groups: ['newsletter'] },
@@ -20,6 +21,7 @@ const ALL_TOOLS = [
     { factory: getDraftMCPImplementations, groups: ['server_queue_readonly', 'server_queue_all'] },
     { factory: saveMCPImplementation, groups: ['server_queue_all'] },
     { factory: sendMCPImplementationPostingNotification, groups: ['server_queue_all'] },
+    { factory: findProviders, groups: ['server_queue_readonly', 'server_queue_all'] },
 ];
 /**
  * Parse enabled tool groups from environment variable or parameter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulsemcp-cms-admin-mcp-server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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-provider-by-id.d.ts

@@ -0,0 +1,3 @@
+import type { Provider } from '../../types.js';
+export declare function getProviderById(apiKey: string, baseUrl: string, id: number): Promise<Provider | null>;
+//# sourceMappingURL=get-provider-by-id.d.ts.map

package/shared/pulsemcp-admin-client/lib/get-provider-by-id.js

@@ -0,0 +1,24 @@
+export async function getProviderById(apiKey, baseUrl, id) {
+    const url = new URL(`/api/providers/${id}`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (response.status === 404) {
+        return null;
+    }
+    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 provider: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}

package/shared/pulsemcp-admin-client/lib/save-mcp-implementation.js

@@ -67,50 +67,52 @@ export async function saveMCPImplementation(apiKey, baseUrl, id, params) {
         formData.append('mcp_implementation[internal_notes]', params.internal_notes);
     }
     // Remote endpoints
+    // Rails expects nested attributes to use the _attributes suffix for has_many associations
     if (params.remote !== undefined && params.remote.length > 0) {
         params.remote.forEach((remote, index) => {
             if (remote.id !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][id]`, remote.id.toString());
+                formData.append(`mcp_implementation[remote_attributes][${index}][id]`, remote.id.toString());
             }
             if (remote.url_direct !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][url_direct]`, remote.url_direct);
+                formData.append(`mcp_implementation[remote_attributes][${index}][url_direct]`, remote.url_direct);
             }
             if (remote.url_setup !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][url_setup]`, remote.url_setup);
+                formData.append(`mcp_implementation[remote_attributes][${index}][url_setup]`, remote.url_setup);
             }
             if (remote.transport !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][transport]`, remote.transport);
+                formData.append(`mcp_implementation[remote_attributes][${index}][transport]`, remote.transport);
             }
             if (remote.host_platform !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][host_platform]`, remote.host_platform);
+                formData.append(`mcp_implementation[remote_attributes][${index}][host_platform]`, remote.host_platform);
             }
             if (remote.host_infrastructure !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][host_infrastructure]`, remote.host_infrastructure);
+                formData.append(`mcp_implementation[remote_attributes][${index}][host_infrastructure]`, remote.host_infrastructure);
             }
             if (remote.authentication_method !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][authentication_method]`, remote.authentication_method);
+                formData.append(`mcp_implementation[remote_attributes][${index}][authentication_method]`, remote.authentication_method);
             }
             if (remote.cost !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][cost]`, remote.cost);
+                formData.append(`mcp_implementation[remote_attributes][${index}][cost]`, remote.cost);
             }
             if (remote.status !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][status]`, remote.status);
+                formData.append(`mcp_implementation[remote_attributes][${index}][status]`, remote.status);
             }
             if (remote.display_name !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][display_name]`, remote.display_name);
+                formData.append(`mcp_implementation[remote_attributes][${index}][display_name]`, remote.display_name);
             }
             if (remote.internal_notes !== undefined) {
-                formData.append(`mcp_implementation[remote][${index}][internal_notes]`, remote.internal_notes);
+                formData.append(`mcp_implementation[remote_attributes][${index}][internal_notes]`, remote.internal_notes);
             }
         });
     }
     // Canonical URLs
+    // Rails expects nested attributes to use the _attributes suffix for has_many associations
     if (params.canonical !== undefined && params.canonical.length > 0) {
         params.canonical.forEach((canonicalUrl, index) => {
-            formData.append(`mcp_implementation[canonical][${index}][url]`, canonicalUrl.url);
-            formData.append(`mcp_implementation[canonical][${index}][scope]`, canonicalUrl.scope);
+            formData.append(`mcp_implementation[canonical_attributes][${index}][url]`, canonicalUrl.url);
+            formData.append(`mcp_implementation[canonical_attributes][${index}][scope]`, canonicalUrl.scope);
             if (canonicalUrl.note !== undefined) {
-                formData.append(`mcp_implementation[canonical][${index}][note]`, canonicalUrl.note);
+                formData.append(`mcp_implementation[canonical_attributes][${index}][note]`, canonicalUrl.note);
             }
         });
     }

package/shared/pulsemcp-admin-client/lib/search-providers.d.ts

@@ -0,0 +1,7 @@
+import type { ProvidersResponse } from '../../types.js';
+export declare function searchProviders(apiKey: string, baseUrl: string, params: {
+    query: string;
+    limit?: number;
+    offset?: number;
+}): Promise<ProvidersResponse>;
+//# sourceMappingURL=search-providers.d.ts.map

package/shared/pulsemcp-admin-client/lib/search-providers.js

@@ -0,0 +1,45 @@
+export async function searchProviders(apiKey, baseUrl, params) {
+    // Endpoint implemented at: /api/providers/search
+    // Requires admin authentication via X-API-Key header
+    const url = new URL('/api/providers/search', baseUrl);
+    // Add query parameters
+    url.searchParams.append('q', params.query);
+    if (params.limit) {
+        url.searchParams.append('limit', params.limit.toString());
+    }
+    if (params.offset) {
+        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');
+        }
+        if (response.status === 404) {
+            throw new Error('Providers search endpoint not found');
+        }
+        throw new Error(`Failed to search providers: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        providers: data.data || [],
+        pagination: data.meta
+            ? {
+                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,
+            }
+            : undefined,
+    };
+}

package/shared/pulsemcp-admin-client/pulsemcp-admin-client.integration-mock.d.ts

@@ -1,5 +1,5 @@
 import type { IPulseMCPAdminClient } from '../server.js';
-import type { Post, ImageUploadResponse, Author, MCPServer, MCPClient, MCPImplementation, MCPImplementationsResponse } from '../types.js';
+import type { Post, ImageUploadResponse, Author, MCPServer, MCPClient, MCPImplementation, MCPImplementationsResponse, Provider, ProvidersResponse } from '../types.js';
 interface MockData {
     posts?: Post[];
     postsBySlug?: Record<string, Post>;
@@ -13,6 +13,8 @@ interface MockData {
     implementations?: MCPImplementation[];
     implementationsResponse?: MCPImplementationsResponse;
     draftImplementationsResponse?: MCPImplementationsResponse;
+    providers?: Provider[];
+    providersResponse?: ProvidersResponse;
     errors?: {
         getPosts?: Error;
         getPost?: Error;
@@ -27,6 +29,8 @@ interface MockData {
         getDraftMCPImplementations?: Error;
         saveMCPImplementation?: Error;
         sendEmail?: Error;
+        searchProviders?: Error;
+        getProviderById?: Error;
     };
 }
 export declare function createMockPulseMCPAdminClient(mockData: MockData): IPulseMCPAdminClient;

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

@@ -334,5 +334,68 @@ export function createMockPulseMCPAdminClient(mockData) {
                 updated_at: new Date().toISOString(),
             };
         },
+        async searchProviders(params) {
+            if (mockData.errors?.searchProviders) {
+                throw mockData.errors.searchProviders;
+            }
+            if (mockData.providersResponse) {
+                return mockData.providersResponse;
+            }
+            let providers = mockData.providers || [
+                {
+                    id: 1,
+                    name: 'Test Provider',
+                    slug: 'test-provider',
+                    url: 'https://testprovider.com',
+                    implementations_count: 5,
+                    created_at: '2024-01-01T00:00:00Z',
+                    updated_at: '2024-01-01T00:00:00Z',
+                },
+            ];
+            // Apply search filter
+            if (params.query) {
+                const query = params.query.toLowerCase();
+                providers = providers.filter((provider) => provider.name.toLowerCase().includes(query) ||
+                    provider.slug.toLowerCase().includes(query) ||
+                    (provider.url && provider.url.toLowerCase().includes(query)));
+            }
+            // Apply pagination
+            const offset = params.offset || 0;
+            const limit = params.limit || 30;
+            const totalCount = providers.length;
+            const paginatedProviders = providers.slice(offset, offset + limit);
+            return {
+                providers: paginatedProviders,
+                pagination: {
+                    current_page: Math.floor(offset / limit) + 1,
+                    total_pages: Math.ceil(totalCount / limit),
+                    total_count: totalCount,
+                    has_next: offset + limit < totalCount,
+                    limit: limit,
+                },
+            };
+        },
+        async getProviderById(id) {
+            if (mockData.errors?.getProviderById) {
+                throw mockData.errors.getProviderById;
+            }
+            // Find provider in mock data by ID
+            const providers = mockData.providers || [
+                {
+                    id: 1,
+                    name: 'Test Provider',
+                    slug: 'test-provider',
+                    url: 'https://testprovider.com',
+                    implementations_count: 5,
+                    created_at: '2024-01-01T00:00:00Z',
+                    updated_at: '2024-01-01T00:00:00Z',
+                },
+            ];
+            const found = providers.find((p) => p.id === id);
+            if (found)
+                return found;
+            // Return null if not found
+            return null;
+        },
     };
 }

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 } from './types.js';
+import type { Post, PostsResponse, CreatePostParams, UpdatePostParams, ImageUploadResponse, Author, AuthorsResponse, MCPServer, MCPClient, MCPImplementation, MCPImplementationsResponse, SaveMCPImplementationParams, Provider, ProvidersResponse } from './types.js';
 export interface IPulseMCPAdminClient {
     getPosts(params?: {
         search?: string;
@@ -54,6 +54,12 @@ export interface IPulseMCPAdminClient {
         created_at: string;
         updated_at: string;
     }>;
+    searchProviders(params: {
+        query: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ProvidersResponse>;
+    getProviderById(id: number): Promise<Provider | null>;
 }
 export declare class PulseMCPAdminClient implements IPulseMCPAdminClient {
     private apiKey;
@@ -112,6 +118,12 @@ export declare class PulseMCPAdminClient implements IPulseMCPAdminClient {
         created_at: string;
         updated_at: string;
     }>;
+    searchProviders(params: {
+        query: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ProvidersResponse>;
+    getProviderById(id: number): Promise<Provider | null>;
 }
 export type ClientFactory = () => IPulseMCPAdminClient;
 export declare function createMCPServer(): {

package/shared/server.js

@@ -75,6 +75,14 @@ export class PulseMCPAdminClient {
         const { sendEmail } = await import('./pulsemcp-admin-client/lib/send-email.js');
         return sendEmail(this.apiKey, this.baseUrl, params);
     }
+    async searchProviders(params) {
+        const { searchProviders } = await import('./pulsemcp-admin-client/lib/search-providers.js');
+        return searchProviders(this.apiKey, this.baseUrl, params);
+    }
+    async getProviderById(id) {
+        const { getProviderById } = await import('./pulsemcp-admin-client/lib/get-provider-by-id.js');
+        return getProviderById(this.apiKey, this.baseUrl, id);
+    }
 }
 export function createMCPServer() {
     const server = new Server({

package/shared/tools/find-providers.d.ts

@@ -0,0 +1,41 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function findProviders(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id: {
+                type: string;
+                description: "Provider ID to retrieve a specific provider";
+            };
+            query: {
+                type: string;
+                description: "Search query to find providers by name, URL, or slug";
+            };
+            limit: {
+                type: string;
+                description: "Maximum number of results to return (1-100, default: 30)";
+            };
+            offset: {
+                type: string;
+                description: "Number of results to skip for pagination (default: 0)";
+            };
+        };
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=find-providers.d.ts.map

package/shared/tools/find-providers.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+// Parameter descriptions - single source of truth
+const PARAM_DESCRIPTIONS = {
+    id: 'Provider ID to retrieve a specific provider',
+    query: 'Search query to find providers by name, URL, or slug',
+    limit: 'Maximum number of results to return (1-100, default: 30)',
+    offset: 'Number of results to skip for pagination (default: 0)',
+};
+const FindProvidersSchema = z
+    .object({
+    id: z.number().int().positive().optional().describe(PARAM_DESCRIPTIONS.id),
+    query: z.string().min(1).optional().describe(PARAM_DESCRIPTIONS.query),
+    limit: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.limit),
+    offset: z.number().min(0).optional().describe(PARAM_DESCRIPTIONS.offset),
+})
+    .refine((data) => data.id !== undefined || data.query !== undefined, {
+    message: 'Either id or query must be provided',
+});
+export function findProviders(_server, clientFactory) {
+    return {
+        name: 'find_providers',
+        description: `Find providers (organizations/individuals) in the PulseMCP registry.
+
+This tool can operate in two modes:
+
+1. **Find by ID**: Retrieve a specific provider by its numeric ID
+   - Returns a single provider with detailed information
+   - Returns null if not found
+
+2. **Search by query**: Search for providers by name, URL, or slug
+   - Searches across provider name, URL, and slug fields (case-insensitive)
+   - Returns a list of matching providers with pagination support
+   - Each result includes implementation counts
+
+Provider information includes:
+- ID and slug
+- Name and URL
+- Number of associated implementations
+- Creation and update timestamps
+
+Use cases:
+- Look up a specific provider by ID
+- Search for providers by name (e.g., "anthropic", "modelcontextprotocol")
+- Find providers by partial name matches
+- Discover all providers for an organization
+- Check how many implementations a provider has published
+
+Note: This tool queries the PulseMCP registry API. Results depend on what has been published to the registry.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.id,
+                },
+                query: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.query,
+                },
+                limit: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.limit,
+                },
+                offset: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.offset,
+                },
+            },
+        },
+        handler: async (args) => {
+            const validatedArgs = FindProvidersSchema.parse(args);
+            const client = clientFactory();
+            try {
+                // Mode 1: Find by ID
+                if (validatedArgs.id !== undefined) {
+                    const provider = await client.getProviderById(validatedArgs.id);
+                    if (!provider) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Provider with ID ${validatedArgs.id} not found.`,
+                                },
+                            ],
+                        };
+                    }
+                    let content = `**${provider.name}**\n`;
+                    content += `ID: ${provider.id}\n`;
+                    content += `Slug: ${provider.slug}\n`;
+                    if (provider.url) {
+                        content += `URL: ${provider.url}\n`;
+                    }
+                    if (provider.implementations_count !== undefined) {
+                        content += `Implementations: ${provider.implementations_count}\n`;
+                    }
+                    if (provider.created_at) {
+                        content += `Created: ${provider.created_at}\n`;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: content.trim(),
+                            },
+                        ],
+                    };
+                }
+                // Mode 2: Search by query
+                if (validatedArgs.query !== undefined) {
+                    const response = await client.searchProviders({
+                        query: validatedArgs.query,
+                        limit: validatedArgs.limit,
+                        offset: validatedArgs.offset,
+                    });
+                    let content = `Found ${response.providers.length} provider(s) matching "${validatedArgs.query}"`;
+                    if (response.pagination) {
+                        content += ` (showing ${response.providers.length} of ${response.pagination.total_count} total)`;
+                    }
+                    content += ':\n\n';
+                    for (const [index, provider] of response.providers.entries()) {
+                        content += `${index + 1}. **${provider.name}**\n`;
+                        content += `   ID: ${provider.id} | Slug: ${provider.slug}\n`;
+                        if (provider.url) {
+                            content += `   URL: ${provider.url}\n`;
+                        }
+                        if (provider.implementations_count !== undefined) {
+                            content += `   Implementations: ${provider.implementations_count}\n`;
+                        }
+                        content += '\n';
+                    }
+                    if (response.pagination?.has_next) {
+                        const nextOffset = (validatedArgs.offset || 0) + (validatedArgs.limit || 30);
+                        content += `\n---\nMore results available. Use offset=${nextOffset} to see the next page.`;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: content.trim(),
+                            },
+                        ],
+                    };
+                }
+                // This should never happen due to zod refinement, but TypeScript needs it
+                throw new Error('Either id or query must be provided');
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error finding providers: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/search-mcp-implementations.js

@@ -38,6 +38,8 @@ Returns a list of matching implementations with their metadata, including:
 - GitHub stars and popularity metrics
 - Associated MCP server/client IDs
 - PulseMCP web URL
+- Remote endpoints (for servers) - hosting platforms, transport methods, authentication
+- Canonical URLs - authoritative sources for the implementation
 
 Use cases:
 - Find existing MCP servers before creating a new one
@@ -96,6 +98,7 @@ Note: This tool queries the PulseMCP registry API. Results depend on what has be
                 content += ':\n\n';
                 for (const [index, impl] of response.implementations.entries()) {
                     content += `${index + 1}. **${impl.name}** (${impl.type})\n`;
+                    content += `   ID: ${impl.id}\n`;
                     content += `   Slug: ${impl.slug}\n`;
                     content += `   Status: ${impl.status}`;
                     if (impl.classification) {
@@ -124,6 +127,40 @@ Note: This tool queries the PulseMCP registry API. Results depend on what has be
                     if (impl.mcp_client_id) {
                         content += `   MCP Client ID: ${impl.mcp_client_id}\n`;
                     }
+                    // Display remote endpoints if available
+                    if (impl.mcp_server?.remotes && impl.mcp_server.remotes.length > 0) {
+                        content += `   Remotes (${impl.mcp_server.remotes.length}):\n`;
+                        for (const remote of impl.mcp_server.remotes) {
+                            let remoteLine = `     - ${remote.display_name || remote.url_direct || remote.url_setup || 'Unnamed'}`;
+                            const attrs = [];
+                            if (remote.transport)
+                                attrs.push(remote.transport);
+                            if (remote.host_platform)
+                                attrs.push(remote.host_platform);
+                            if (remote.authentication_method)
+                                attrs.push(`auth: ${remote.authentication_method}`);
+                            if (remote.cost)
+                                attrs.push(remote.cost);
+                            if (attrs.length > 0) {
+                                remoteLine += ` [${attrs.join(', ')}]`;
+                            }
+                            content += remoteLine + '\n';
+                        }
+                    }
+                    else if (impl.mcp_server?.mcp_server_remotes_count) {
+                        content += `   Remotes Count: ${impl.mcp_server.mcp_server_remotes_count}\n`;
+                    }
+                    // Display canonical URLs if available
+                    if (impl.canonical && impl.canonical.length > 0) {
+                        content += `   Canonical URLs (${impl.canonical.length}):\n`;
+                        for (const canonical of impl.canonical) {
+                            let canonicalLine = `     - ${canonical.url} [scope: ${canonical.scope}]`;
+                            if (canonical.note) {
+                                canonicalLine += ` - ${canonical.note}`;
+                            }
+                            content += canonicalLine + '\n';
+                        }
+                    }
                     content += '\n';
                 }
                 if (response.pagination?.has_next) {

package/shared/tools.js

@@ -9,6 +9,7 @@ import { searchMCPImplementations } from './tools/search-mcp-implementations.js'
 import { getDraftMCPImplementations } from './tools/get-draft-mcp-implementations.js';
 import { saveMCPImplementation } from './tools/save-mcp-implementation.js';
 import { sendMCPImplementationPostingNotification } from './tools/send-mcp-implementation-posting-notification.js';
+import { findProviders } from './tools/find-providers.js';
 const ALL_TOOLS = [
     { factory: getNewsletterPosts, groups: ['newsletter'] },
     { factory: getNewsletterPost, groups: ['newsletter'] },
@@ -20,6 +21,7 @@ const ALL_TOOLS = [
     { factory: getDraftMCPImplementations, groups: ['server_queue_readonly', 'server_queue_all'] },
     { factory: saveMCPImplementation, groups: ['server_queue_all'] },
     { factory: sendMCPImplementationPostingNotification, groups: ['server_queue_all'] },
+    { factory: findProviders, groups: ['server_queue_readonly', 'server_queue_all'] },
 ];
 /**
  * Parse enabled tool groups from environment variable or parameter

package/shared/types.d.ts

@@ -164,6 +164,7 @@ export interface MCPImplementation {
     updated_at?: string;
     mcp_server?: MCPServer | null;
     mcp_client?: MCPClient | null;
+    canonical?: CanonicalUrlParams[];
 }
 export interface MCPImplementationsResponse {
     implementations: MCPImplementation[];
@@ -199,4 +200,23 @@ export interface SaveMCPImplementationParams {
     canonical?: CanonicalUrlParams[];
     internal_notes?: string;
 }
+export interface Provider {
+    id: number;
+    name: string;
+    slug: string;
+    url?: string;
+    implementations_count?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface ProvidersResponse {
+    providers: Provider[];
+    pagination?: {
+        current_page: number;
+        total_pages: number;
+        total_count: number;
+        has_next?: boolean;
+        limit?: number;
+    };
+}
 //# sourceMappingURL=types.d.ts.map