pulsemcp-cms-admin-mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -30,20 +30,38 @@ This is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) Serv
 
 **Content Search**: Find newsletter posts with powerful search and pagination capabilities.
 
+**MCP Implementation Search**: Search for MCP servers and clients in the PulseMCP registry.
+
+**Toolgroups**: Enable/disable tool groups (newsletter, server_queue_readonly, server_queue_all) via environment variable.
+
 **Draft Control**: Manage draft posts before publishing to the newsletter.
 
 # Capabilities
 
 This server is built and tested on macOS with Claude Desktop. It should work with other MCP clients as well.
 
-| Tool Name                | Description                                                                |
-| ------------------------ | -------------------------------------------------------------------------- |
-| `get_newsletter_posts`   | List newsletter posts with search, sorting, and pagination options.        |
-| `get_newsletter_post`    | Retrieve a specific newsletter post by its unique slug.                    |
-| `draft_newsletter_post`  | Create a new draft newsletter post with title, body, and metadata.         |
-| `update_newsletter_post` | Update an existing newsletter post's content and metadata (except status). |
-| `upload_image`           | Upload an image and attach it to a specific newsletter post.               |
-| `get_authors`            | Get a list of authors with optional search and pagination.                 |
+| Tool Name                                      | Tool Group            | Description                                                                  |
+| ---------------------------------------------- | --------------------- | ---------------------------------------------------------------------------- |
+| `get_newsletter_posts`                         | newsletter            | List newsletter posts with search, sorting, and pagination options.          |
+| `get_newsletter_post`                          | newsletter            | Retrieve a specific newsletter post by its unique slug.                      |
+| `draft_newsletter_post`                        | newsletter            | Create a new draft newsletter post with title, body, and metadata.           |
+| `update_newsletter_post`                       | newsletter            | Update an existing newsletter post's content and metadata (except status).   |
+| `upload_image`                                 | newsletter            | Upload an image and attach it to a specific newsletter post.                 |
+| `get_authors`                                  | newsletter            | Get a list of authors with optional search and pagination.                   |
+| `search_mcp_implementations`                   | server_queue_readonly | Search for MCP servers and clients in the PulseMCP registry.                 |
+| `get_draft_mcp_implementations`                | server_queue_readonly | Retrieve paginated list of draft MCP implementations needing review.         |
+| `save_mcp_implementation`                      | server_queue_all      | Update an MCP implementation (replicates Admin panel "Save Changes" button). |
+| `send_mcp_implementation_posting_notification` | server_queue_all      | Send email notification when MCP implementation goes live.                   |
+
+# Tool Groups
+
+This server organizes tools into groups that can be selectively enabled or disabled:
+
+- **newsletter** (6 tools): Newsletter management, image uploads, and author retrieval
+- **server_queue_readonly** (2 tools): Read-only MCP implementation tools (search, draft retrieval)
+- **server_queue_all** (4 tools): All MCP implementation tools including write operations (search, draft retrieval, update, and email notification)
+
+You can control which tool groups are available by setting the `PULSEMCP_ADMIN_ENABLED_TOOLGROUPS` environment variable as a comma-separated list (e.g., `newsletter,server_queue_readonly`). If not set, all tool groups are enabled by default.
 
 # Usage Tips
 
@@ -54,6 +72,8 @@ This server is built and tested on macOS with Claude Desktop. It should work wit
 - The update tool allows modifying all post metadata except status
 - Use author slugs when creating posts (e.g., "sarah-chen", "john-doe")
 - Use MCP server/client slugs for featured content (e.g., "github-mcp", "claude-desktop")
+- Use `search_mcp_implementations` to discover MCP servers and clients in the PulseMCP registry
+- Enable or disable specific toolgroups by setting `PULSEMCP_ADMIN_ENABLED_TOOLGROUPS` environment variable
 
 # Examples
 
@@ -80,9 +100,7 @@ I found 3 newsletter posts about MCP servers:
 ## Create a Draft Post
 
 ```
-User: Create a draft newsletter post about the new weather MCP server
-
-Assistant: I'll create a draft newsletter post about the new weather MCP server.
+User: Create a draft newsletter post about the new weather MCP serverAssistant: I'll create a draft newsletter post about the new weather MCP server.
 
 [Calls draft_newsletter_post with title, body, slug, and author_slug]
 
@@ -92,9 +110,7 @@ I've created a draft newsletter post titled "New Weather MCP Server: Real-time F
 ## Upload and Attach an Image
 
 ```
-User: Upload this screenshot to the weather server post I just created
-
-Assistant: I'll upload the screenshot and attach it to your weather server post.
+User: Upload this screenshot to the weather server post I just createdAssistant: I'll upload the screenshot and attach it to your weather server post.
 
 [Calls upload_image with post_slug="weather-mcp-server-launch" and file_name="weather-dashboard.png"]
 
@@ -104,15 +120,30 @@ The screenshot has been successfully uploaded and attached to the "weather-mcp-s
 ## Update an Existing Post
 
 ```
-User: Update the weather post to include information about the new temperature alerts feature
-
-Assistant: I'll update the weather MCP server post to include information about the temperature alerts feature.
+User: Update the weather post to include information about the new temperature alerts featureAssistant: I'll update the weather MCP server post to include information about the temperature alerts feature.
 
 [Calls update_newsletter_post with slug="weather-mcp-server-launch" and updated content]
 
 I've successfully updated the "New Weather MCP Server" post to include a section about the temperature alerts feature. The post now covers both the real-time forecasts and the new alert system.
 ```
 
+## Search for MCP Implementations
+
+```
+User: Find MCP servers related to weather or climate
+Assistant: I'll search for MCP servers related to weather and climate.
+
+[Calls search_mcp_implementations with search="weather climate"]
+
+I found 2 MCP servers related to weather and climate:
+
+1. **Weather MCP Server** (weather-mcp)
+   - Real-time weather data and forecasting capabilities
+
+2. **Climate Data MCP Client** (climate-data-mcp)
+   - Access climate research and environmental data
+```
+
 # Setup
 
 ## Cheatsheet
@@ -148,7 +179,8 @@ Add to your Claude Desktop configuration:
       "command": "node",
       "args": ["/path/to/pulsemcp-cms-admin/local/build/index.js"],
       "env": {
-        "PULSEMCP_ADMIN_API_KEY": "your-api-key-here"
+        "PULSEMCP_ADMIN_API_KEY": "your-api-key-here",
+        "PULSEMCP_ADMIN_ENABLED_TOOLGROUPS": "newsletter,server_queue_readonly,server_queue_all"
       }
     }
   }

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Integration Test Server Entry Point with Mock Client Factory
+ *
+ * This file is used for integration testing with a mocked PulseMCPAdminClient.
+ * It uses the real MCP server but injects a mock client factory.
+ *
+ * Mock data is passed via the PULSEMCP_MOCK_DATA environment variable.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// IMPORTANT: This uses the package name pattern, not a relative path
+import { createMCPServer } from 'pulsemcp-cms-admin-mcp-server-shared';
+// Import the mock client factory from the shared module
+import { createMockPulseMCPAdminClient } from '../../shared/src/pulsemcp-admin-client/pulsemcp-admin-client.integration-mock.js';
+async function main() {
+    const transport = new StdioServerTransport();
+    // Parse mock data from environment variable
+    let mockData = {};
+    if (process.env.PULSEMCP_MOCK_DATA) {
+        try {
+            mockData = JSON.parse(process.env.PULSEMCP_MOCK_DATA);
+        }
+        catch (e) {
+            console.error('Failed to parse PULSEMCP_MOCK_DATA:', e);
+        }
+    }
+    // Create client factory that returns our mock
+    const clientFactory = () => createMockPulseMCPAdminClient(mockData);
+    const { server, registerHandlers } = createMCPServer();
+    await registerHandlers(server, clientFactory);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/build/shared/src/pulsemcp-admin-client/lib/get-draft-mcp-implementations.js

@@ -0,0 +1,61 @@
+export async function getDraftMCPImplementations(apiKey, baseUrl, params) {
+    const url = new URL('/api/implementations/drafts', baseUrl);
+    // Add query parameters if provided
+    if (params?.page) {
+        url.searchParams.append('page', params.page.toString());
+    }
+    if (params?.search) {
+        url.searchParams.append('search', params.search);
+    }
+    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 draft implementations: ${response.status} ${response.statusText}`);
+    }
+    // Parse the JSON response
+    const data = (await response.json());
+    // Handle the Rails JSON structure with data and meta
+    if (data.data && data.meta) {
+        return {
+            implementations: data.data.map((impl) => ({
+                id: impl.id,
+                name: impl.name,
+                short_description: impl.short_description,
+                description: impl.description,
+                type: impl.type,
+                status: impl.status,
+                slug: impl.slug,
+                url: impl.url,
+                provider_name: impl.provider_name,
+                github_stars: impl.github_stars,
+                classification: impl.classification,
+                implementation_language: impl.implementation_language,
+                mcp_server_id: impl.mcp_server_id,
+                mcp_client_id: impl.mcp_client_id,
+                created_at: impl.created_at,
+                updated_at: impl.updated_at,
+            })),
+            pagination: {
+                current_page: data.meta.current_page,
+                total_pages: data.meta.total_pages,
+                total_count: data.meta.total_count,
+            },
+        };
+    }
+    // Fallback for unexpected response format
+    return {
+        implementations: [],
+        pagination: undefined,
+    };
+}

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

@@ -0,0 +1,73 @@
+export async function saveMCPImplementation(apiKey, baseUrl, id, params) {
+    const url = new URL(`/api/implementations/${id}`, baseUrl);
+    // Build form data for the PUT request
+    const formData = new URLSearchParams();
+    // Add all provided fields using Rails conventions
+    if (params.name !== undefined) {
+        formData.append('mcp_implementation[name]', params.name);
+    }
+    if (params.short_description !== undefined) {
+        formData.append('mcp_implementation[short_description]', params.short_description);
+    }
+    if (params.description !== undefined) {
+        formData.append('mcp_implementation[description]', params.description);
+    }
+    if (params.type !== undefined) {
+        formData.append('mcp_implementation[type]', params.type);
+    }
+    if (params.status !== undefined) {
+        formData.append('mcp_implementation[status]', params.status);
+    }
+    if (params.slug !== undefined) {
+        formData.append('mcp_implementation[slug]', params.slug);
+    }
+    if (params.url !== undefined) {
+        formData.append('mcp_implementation[url]', params.url);
+    }
+    if (params.provider_name !== undefined) {
+        formData.append('mcp_implementation[provider_name]', params.provider_name);
+    }
+    if (params.github_stars !== undefined) {
+        formData.append('mcp_implementation[github_stars]', params.github_stars.toString());
+    }
+    if (params.classification !== undefined) {
+        formData.append('mcp_implementation[classification]', params.classification);
+    }
+    if (params.implementation_language !== undefined) {
+        formData.append('mcp_implementation[implementation_language]', params.implementation_language);
+    }
+    if (params.mcp_server_id !== undefined) {
+        formData.append('mcp_implementation[mcp_server_id]', params.mcp_server_id === null ? '' : params.mcp_server_id.toString());
+    }
+    if (params.mcp_client_id !== undefined) {
+        formData.append('mcp_implementation[mcp_client_id]', params.mcp_client_id === null ? '' : params.mcp_client_id.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'PUT',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        },
+        body: formData.toString(),
+    });
+    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(`MCP implementation not found: ${id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            const errors = errorData.errors || ['Validation failed'];
+            throw new Error(`Validation failed: ${errors.join(', ')}`);
+        }
+        throw new Error(`Failed to save MCP implementation: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data;
+}

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

@@ -0,0 +1,51 @@
+export async function searchMCPImplementations(apiKey, baseUrl, params) {
+    // Endpoint implemented at: /api/implementations/search
+    // Requires admin authentication via X-API-Key header
+    const url = new URL('/api/implementations/search', baseUrl);
+    // Add query parameters
+    url.searchParams.append('q', params.query);
+    if (params.type && params.type !== 'all') {
+        url.searchParams.append('type', params.type);
+    }
+    if (params.status && params.status !== 'all') {
+        url.searchParams.append('status', params.status);
+    }
+    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('MCP implementations search endpoint not found');
+        }
+        throw new Error(`Failed to search MCP implementations: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        implementations: 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/lib/send-email.js

@@ -0,0 +1,46 @@
+/**
+ * Send an email via the PulseMCP Admin API
+ */
+export async function sendEmail(apiKey, baseUrl, params) {
+    const url = new URL('/emails', baseUrl);
+    // Create form data for Rails-style parameters
+    const formData = new URLSearchParams();
+    formData.append('email[from_email_address]', params.from_email_address);
+    formData.append('email[from_name]', params.from_name);
+    formData.append('email[reply_to_email_address]', params.reply_to_email_address);
+    formData.append('email[to_email_address]', params.to_email_address);
+    formData.append('email[subject]', params.subject);
+    formData.append('email[content]', params.content);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        },
+        body: formData.toString(),
+    });
+    if (!response.ok) {
+        const errorBody = await response.text();
+        let errorMessage;
+        try {
+            const errorData = JSON.parse(errorBody);
+            if (errorData.errors) {
+                errorMessage = Array.isArray(errorData.errors)
+                    ? errorData.errors.join(', ')
+                    : JSON.stringify(errorData.errors);
+            }
+            else if (errorData.error) {
+                errorMessage = errorData.error;
+            }
+            else {
+                errorMessage = errorBody;
+            }
+        }
+        catch {
+            errorMessage = errorBody || `HTTP ${response.status}: ${response.statusText}`;
+        }
+        throw new Error(`Failed to send email: ${errorMessage}`);
+    }
+    return response.json();
+}

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

@@ -201,5 +201,125 @@ export function createMockPulseMCPAdminClient(mockData) {
             }
             return null;
         },
+        async searchMCPImplementations(params) {
+            if (mockData.errors?.searchMCPImplementations) {
+                throw mockData.errors.searchMCPImplementations;
+            }
+            if (mockData.implementationsResponse) {
+                return mockData.implementationsResponse;
+            }
+            let implementations = mockData.implementations || [
+                {
+                    id: 1,
+                    name: 'Test MCP Server',
+                    slug: 'test-mcp-server',
+                    type: 'server',
+                    status: 'live',
+                    short_description: 'A test MCP server implementation',
+                    classification: 'community',
+                    implementation_language: 'TypeScript',
+                },
+            ];
+            // Apply search filter
+            if (params.query) {
+                const query = params.query.toLowerCase();
+                implementations = implementations.filter((impl) => impl.name.toLowerCase().includes(query) ||
+                    impl.slug.toLowerCase().includes(query) ||
+                    (impl.short_description && impl.short_description.toLowerCase().includes(query)) ||
+                    (impl.description && impl.description.toLowerCase().includes(query)) ||
+                    (impl.provider_name && impl.provider_name.toLowerCase().includes(query)));
+            }
+            // Apply type filter
+            if (params.type && params.type !== 'all') {
+                implementations = implementations.filter((impl) => impl.type === params.type);
+            }
+            // Apply status filter
+            if (params.status && params.status !== 'all') {
+                implementations = implementations.filter((impl) => impl.status === params.status);
+            }
+            // Apply pagination
+            const offset = params.offset || 0;
+            const limit = params.limit || 30;
+            const totalCount = implementations.length;
+            const paginatedImpls = implementations.slice(offset, offset + limit);
+            return {
+                implementations: paginatedImpls,
+                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 getDraftMCPImplementations(params) {
+            if (mockData.errors?.getDraftMCPImplementations) {
+                throw mockData.errors.getDraftMCPImplementations;
+            }
+            if (mockData.draftImplementationsResponse) {
+                return mockData.draftImplementationsResponse;
+            }
+            // Filter to only draft implementations
+            let implementations = (mockData.implementations || []).filter((impl) => impl.status === 'draft');
+            // Apply search filter if provided
+            if (params?.search) {
+                const searchLower = params.search.toLowerCase();
+                implementations = implementations.filter((impl) => impl.name.toLowerCase().includes(searchLower) ||
+                    impl.short_description?.toLowerCase().includes(searchLower) ||
+                    impl.description?.toLowerCase().includes(searchLower));
+            }
+            // Apply pagination
+            const page = params?.page || 1;
+            const perPage = 20; // Match Rails default
+            const offset = (page - 1) * perPage;
+            const paginatedImpls = implementations.slice(offset, offset + perPage);
+            return {
+                implementations: paginatedImpls,
+                pagination: {
+                    current_page: page,
+                    total_pages: Math.ceil(implementations.length / perPage),
+                    total_count: implementations.length,
+                },
+            };
+        },
+        async saveMCPImplementation(id, params) {
+            if (mockData.errors?.saveMCPImplementation) {
+                throw mockData.errors.saveMCPImplementation;
+            }
+            // Find existing implementation in mock data
+            const implementations = mockData.implementations || [];
+            const existingImpl = implementations.find((impl) => impl.id === id);
+            if (!existingImpl) {
+                throw new Error(`MCP implementation not found: ${id}`);
+            }
+            // Merge params with existing implementation
+            const updatedImpl = {
+                ...existingImpl,
+                ...params,
+                id: id, // Ensure ID doesn't change
+                updated_at: new Date().toISOString(),
+            };
+            return updatedImpl;
+        },
+        async sendEmail(params) {
+            if (mockData.errors?.sendEmail) {
+                throw mockData.errors.sendEmail;
+            }
+            // Mock successful email response
+            return {
+                id: Math.floor(Math.random() * 10000),
+                sender_provider: 'sendgrid',
+                send_timestamp_utc: new Date().toISOString(),
+                from_email_address: params.from_email_address,
+                to_email_address: params.to_email_address,
+                subject: params.subject,
+                content_text: params.content,
+                content_html: `<html><body>${params.content.replace(/\n/g, '<br>')}</body></html>`,
+                campaign_identifier: `admin-api-email-${Date.now()}`,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+            };
+        },
     };
 }

package/build/shared/src/server.js

@@ -55,6 +55,22 @@ export class PulseMCPAdminClient {
         const { getMCPClientById } = await import('./pulsemcp-admin-client/lib/get-mcp-client-by-id.js');
         return getMCPClientById(this.apiKey, this.baseUrl, id);
     }
+    async searchMCPImplementations(params) {
+        const { searchMCPImplementations } = await import('./pulsemcp-admin-client/lib/search-mcp-implementations.js');
+        return searchMCPImplementations(this.apiKey, this.baseUrl, params);
+    }
+    async getDraftMCPImplementations(params) {
+        const { getDraftMCPImplementations } = await import('./pulsemcp-admin-client/lib/get-draft-mcp-implementations.js');
+        return getDraftMCPImplementations(this.apiKey, this.baseUrl, params);
+    }
+    async saveMCPImplementation(id, params) {
+        const { saveMCPImplementation } = await import('./pulsemcp-admin-client/lib/save-mcp-implementation.js');
+        return saveMCPImplementation(this.apiKey, this.baseUrl, id, params);
+    }
+    async sendEmail(params) {
+        const { sendEmail } = await import('./pulsemcp-admin-client/lib/send-email.js');
+        return sendEmail(this.apiKey, this.baseUrl, params);
+    }
 }
 export function createMCPServer() {
     const server = new Server({