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

package/README.md

@@ -32,7 +32,7 @@ This is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) Serv
 
 **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.
+**Toolgroups**: Enable/disable tool groups (newsletter, server_queue_readonly, server_queue_all, official_queue_readonly, official_queue_all) via environment variable.
 
 **Draft Control**: Manage draft posts before publishing to the newsletter.
 
@@ -40,26 +40,36 @@ This is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) Serv
 
 This server is built and tested on macOS with Claude Desktop. It should work with other MCP clients as well.
 
-| 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 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.         |
+| `find_providers`                                       | server_queue_readonly   | Search for providers by ID, name, URL, or slug.                              |
+| `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.                   |
+| `get_official_mirror_queue_items`                      | official_queue_readonly | List and filter official mirror queue entries with pagination and search.    |
+| `get_official_mirror_queue_item`                       | official_queue_readonly | Get detailed information about a single official mirror queue entry.         |
+| `approve_official_mirror_queue_item`                   | official_queue_all      | Approve a queue entry and link it to an existing MCP server (async).         |
+| `approve_official_mirror_queue_item_without_modifying` | official_queue_all      | Approve without updating the linked server.                                  |
+| `reject_official_mirror_queue_item`                    | official_queue_all      | Reject a queue entry (async operation).                                      |
+| `add_official_mirror_to_regular_queue`                 | official_queue_all      | Convert a queue entry to a draft MCP implementation (async).                 |
+| `unlink_official_mirror_queue_item`                    | official_queue_all      | Unlink a queue entry from its linked MCP server.                             |
 
 # 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)
+- **server_queue_readonly** (3 tools): Read-only MCP implementation tools (search, draft retrieval, provider lookup)
+- **server_queue_all** (5 tools): All MCP implementation tools including write operations (search, draft retrieval, provider lookup, update, and email notification)
+- **official_queue_readonly** (2 tools): Read-only official mirror queue tools (list, get details)
+- **official_queue_all** (7 tools): All official mirror queue tools including approve, reject, unlink, and add to regular queue
 
 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.
 
@@ -184,7 +194,7 @@ Add to your Claude Desktop configuration:
       "args": ["/path/to/pulsemcp-cms-admin/local/build/index.js"],
       "env": {
         "PULSEMCP_ADMIN_API_KEY": "your-api-key-here",
-        "PULSEMCP_ADMIN_ENABLED_TOOLGROUPS": "newsletter,server_queue_readonly,server_queue_all"
+        "PULSEMCP_ADMIN_ENABLED_TOOLGROUPS": "newsletter,server_queue_readonly,server_queue_all,official_queue_readonly,official_queue_all"
       }
     }
   }

package/build/shared/src/pulsemcp-admin-client/lib/add-official-mirror-to-regular-queue.js

@@ -0,0 +1,58 @@
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: item.latest_mirror
+            ? {
+                id: item.latest_mirror.id,
+                name: item.latest_mirror.name,
+                version: item.latest_mirror.version,
+                description: item.latest_mirror.description,
+                github_url: item.latest_mirror.github_url,
+                website_url: item.latest_mirror.website_url,
+                published_at: item.latest_mirror.published_at,
+            }
+            : null,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function addOfficialMirrorToRegularQueue(apiKey, baseUrl, id) {
+    const url = new URL(`/api/official_mirror_queues/${id}/add_to_regular_queue`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        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 === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Validation failed');
+        }
+        throw new Error(`Failed to add official mirror to regular queue: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        success: data.success,
+        message: data.message,
+        queue_item: mapQueueItem(data.queue_item),
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/approve-official-mirror-queue-item-without-modifying.js

@@ -0,0 +1,58 @@
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: item.latest_mirror
+            ? {
+                id: item.latest_mirror.id,
+                name: item.latest_mirror.name,
+                version: item.latest_mirror.version,
+                description: item.latest_mirror.description,
+                github_url: item.latest_mirror.github_url,
+                website_url: item.latest_mirror.website_url,
+                published_at: item.latest_mirror.published_at,
+            }
+            : null,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function approveOfficialMirrorQueueItemWithoutModifying(apiKey, baseUrl, id) {
+    const url = new URL(`/api/official_mirror_queues/${id}/approve_without_modifying`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        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 === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Validation failed');
+        }
+        throw new Error(`Failed to approve official mirror queue item: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        success: data.success,
+        message: data.message,
+        queue_item: mapQueueItem(data.queue_item),
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/approve-official-mirror-queue-item.js

@@ -0,0 +1,62 @@
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: item.latest_mirror
+            ? {
+                id: item.latest_mirror.id,
+                name: item.latest_mirror.name,
+                version: item.latest_mirror.version,
+                description: item.latest_mirror.description,
+                github_url: item.latest_mirror.github_url,
+                website_url: item.latest_mirror.website_url,
+                published_at: item.latest_mirror.published_at,
+            }
+            : null,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function approveOfficialMirrorQueueItem(apiKey, baseUrl, id, mcpServerSlug) {
+    const url = new URL(`/api/official_mirror_queues/${id}/approve`, baseUrl);
+    const formData = new URLSearchParams();
+    formData.append('mcp_server_slug', mcpServerSlug);
+    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) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        if (response.status === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Validation failed');
+        }
+        throw new Error(`Failed to approve official mirror queue item: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        success: data.success,
+        message: data.message,
+        queue_item: mapQueueItem(data.queue_item),
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-official-mirror-queue-item.js

@@ -0,0 +1,71 @@
+function mapMirror(mirror) {
+    return {
+        id: mirror.id,
+        name: mirror.name,
+        version: mirror.version,
+        official_version_id: mirror.official_version_id,
+        description: mirror.description,
+        github_url: mirror.github_url,
+        website_url: mirror.website_url,
+        categories: mirror.categories,
+        license: mirror.license,
+        remotes: mirror.remotes,
+        packages: mirror.packages,
+        published_at: mirror.published_at,
+        schema_version: mirror.schema_version,
+        datetime_ingested: mirror.datetime_ingested,
+        created_at: mirror.created_at,
+        updated_at: mirror.updated_at,
+    };
+}
+function mapLinkedServer(server) {
+    if (!server)
+        return null;
+    return {
+        id: server.id,
+        slug: server.slug,
+        classification: server.classification,
+        implementation_language: server.implementation_language,
+        provider_name: server.provider_name,
+        provider_slug: server.provider_slug,
+        implementation_name: server.implementation_name,
+        implementation_status: server.implementation_status,
+    };
+}
+export async function getOfficialMirrorQueueItem(apiKey, baseUrl, id) {
+    const url = new URL(`/api/official_mirror_queues/${id}`, baseUrl);
+    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 === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        throw new Error(`Failed to fetch official mirror queue item: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        id: data.id,
+        name: data.name,
+        status: data.status,
+        mirrors_count: data.mirrors_count,
+        linked_server: mapLinkedServer(data.linked_server),
+        server_linkage_consistent: data.server_linkage_consistent,
+        mirrors: data.mirrors.map(mapMirror),
+        created_at: data.created_at,
+        updated_at: data.updated_at,
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-official-mirror-queue-items.js

@@ -0,0 +1,73 @@
+function mapMirrorSummary(mirror) {
+    if (!mirror)
+        return null;
+    return {
+        id: mirror.id,
+        name: mirror.name,
+        version: mirror.version,
+        description: mirror.description,
+        github_url: mirror.github_url,
+        website_url: mirror.website_url,
+        published_at: mirror.published_at,
+    };
+}
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: mapMirrorSummary(item.latest_mirror),
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function getOfficialMirrorQueueItems(apiKey, baseUrl, params) {
+    const url = new URL('/api/official_mirror_queues', baseUrl);
+    // Add query parameters if provided
+    if (params?.status) {
+        url.searchParams.append('status', params.status);
+    }
+    if (params?.q) {
+        url.searchParams.append('q', params.q);
+    }
+    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 === 422) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Validation failed');
+        }
+        throw new Error(`Failed to fetch official mirror queue items: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        items: data.data.map(mapQueueItem),
+        pagination: {
+            current_page: data.meta.current_page,
+            total_pages: data.meta.total_pages,
+            total_count: data.meta.total_count,
+            has_next: data.meta.has_next,
+            limit: data.meta.limit,
+        },
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/reject-official-mirror-queue-item.js

@@ -0,0 +1,54 @@
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: item.latest_mirror
+            ? {
+                id: item.latest_mirror.id,
+                name: item.latest_mirror.name,
+                version: item.latest_mirror.version,
+                description: item.latest_mirror.description,
+                github_url: item.latest_mirror.github_url,
+                website_url: item.latest_mirror.website_url,
+                published_at: item.latest_mirror.published_at,
+            }
+            : null,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function rejectOfficialMirrorQueueItem(apiKey, baseUrl, id) {
+    const url = new URL(`/api/official_mirror_queues/${id}/reject`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        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 === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        throw new Error(`Failed to reject official mirror queue item: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        success: data.success,
+        message: data.message,
+        queue_item: mapQueueItem(data.queue_item),
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/unlink-official-mirror-queue-item.js

@@ -0,0 +1,62 @@
+function mapQueueItem(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        status: item.status,
+        mirrors_count: item.mirrors_count,
+        linked_server_slug: item.linked_server_slug,
+        linked_server_id: item.linked_server_id,
+        latest_mirror: item.latest_mirror
+            ? {
+                id: item.latest_mirror.id,
+                name: item.latest_mirror.name,
+                version: item.latest_mirror.version,
+                description: item.latest_mirror.description,
+                github_url: item.latest_mirror.github_url,
+                website_url: item.latest_mirror.website_url,
+                published_at: item.latest_mirror.published_at,
+            }
+            : null,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    };
+}
+export async function unlinkOfficialMirrorQueueItem(apiKey, baseUrl, id) {
+    const url = new URL(`/api/official_mirror_queues/${id}/unlink`, baseUrl);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        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 === 400) {
+            throw new Error('Invalid queue entry ID');
+        }
+        if (response.status === 404) {
+            throw new Error(`Queue entry not found: ${id}`);
+        }
+        if (response.status === 422) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Validation failed');
+        }
+        if (response.status === 500) {
+            const errorData = (await response.json());
+            throw new Error(errorData.error || 'Failed to unlink');
+        }
+        throw new Error(`Failed to unlink official mirror queue item: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        success: data.success,
+        message: data.message,
+        queue_item: mapQueueItem(data.queue_item),
+    };
+}