pulsemcp-cms-admin-mcp-server 0.0.2

package/README.md

@@ -0,0 +1,169 @@
+# PulseMCP CMS Admin MCP Server
+
+> **Note**: This package is part of the [MCP Servers](https://github.com/pulsemcp/mcp-servers) monorepo. For the latest updates and full source code, visit the [PulseMCP CMS Admin MCP Server directory](https://github.com/pulsemcp/mcp-servers/tree/main/experimental/pulsemcp-cms-admin).
+
+
+Haven't heard about MCP yet? The easiest way to keep up-to-date is to read our [weekly newsletter at PulseMCP](https://www.pulsemcp.com/).
+
+---
+
+This is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) Server for managing PulseMCP's content management system. It provides tools for newsletter management and content operations through direct integration with the [PulseMCP Admin API](https://admin.pulsemcp.com).
+
+**Note**: This is an internal tool for the PulseMCP team. The source code is public for reference purposes, but the server requires API keys that are not publicly available.
+
+# Table of Contents
+
+- [Highlights](#highlights)
+- [Capabilities](#capabilities)
+- [Usage Tips](#usage-tips)
+- [Examples](#examples)
+- [Setup](#setup)
+  - [Cheatsheet](#cheatsheet)
+  - [Claude Desktop](#claude-desktop)
+    - [Manual Setup](#manual-setup)
+
+# Highlights
+
+**Newsletter Management**: Create, update, and retrieve newsletter posts with full content control.
+
+**Image Uploads**: Upload images to cloud storage and attach them to newsletter posts.
+
+**Content Search**: Find newsletter posts with powerful search and pagination capabilities.
+
+**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.                 |
+
+# Usage Tips
+
+- Use `get_newsletter_posts` to browse existing content before creating new posts
+- When uploading images, both `post_slug` and `file_name` are required
+- Draft posts allow you to prepare content without immediately publishing
+- Search functionality supports finding posts by title, content, or metadata
+- 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")
+
+# Examples
+
+## Search for Newsletter Posts
+
+```
+User: Can you find all newsletter posts about MCP servers?
+Assistant: I'll search for newsletter posts about MCP servers.
+
+[Calls get_newsletter_posts with search="MCP servers"]
+
+I found 3 newsletter posts about MCP servers:
+
+1. **"Top 10 MCP Servers This Week"** (2024-01-15)
+   - Weekly roundup of the most popular MCP servers
+
+2. **"Building Your First MCP Server"** (2024-01-08)
+   - Tutorial on creating custom MCP servers
+
+3. **"MCP Server Security Best Practices"** (2023-12-28)
+   - Guide to securing MCP server deployments
+```
+
+## 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.
+
+[Calls draft_newsletter_post with title, body, slug, and author_slug]
+
+I've created a draft newsletter post titled "New Weather MCP Server: Real-time Forecasts in Your LLM" with the slug "weather-mcp-server-launch". The draft has been saved and can be edited or published later.
+```
+
+## 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.
+
+[Calls upload_image with post_slug="weather-mcp-server-launch" and file_name="weather-dashboard.png"]
+
+The screenshot has been successfully uploaded and attached to the "weather-mcp-server-launch" post. The image is now available at: https://storage.pulsemcp.com/images/newsletter/weather-dashboard.png
+```
+
+## 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.
+
+[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.
+```
+
+# Setup
+
+## Cheatsheet
+
+Quick setup:
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Build the server
+npm run build
+
+# Set your API key
+export PULSEMCP_ADMIN_API_KEY="your-api-key-here"
+
+# Run the server
+cd local && npm start
+```
+
+## Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+### macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pulsemcp-cms-admin": {
+      "command": "node",
+      "args": ["/path/to/pulsemcp-cms-admin/local/build/index.js"],
+      "env": {
+        "PULSEMCP_ADMIN_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Manual Setup
+
+If you prefer to run the server manually:
+
+```bash
+cd /path/to/pulsemcp-cms-admin/local
+PULSEMCP_ADMIN_API_KEY="your-api-key-here" node build/index.js
+```
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError } from '../shared/logging.js';
+// Validate required environment variables before starting
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'PULSEMCP_ADMIN_API_KEY',
+            description: 'API key for PulseMCP admin API authentication',
+        },
+    ];
+    const optional = [];
+    const missing = required.filter(({ name }) => !process.env[name]);
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        missing.forEach(({ name, description }) => {
+            console.error(`  - ${name}: ${description}`);
+        });
+        if (optional.length > 0) {
+            console.error('\nOptional environment variables:');
+            optional.forEach(({ name, description }) => {
+                console.error(`  - ${name}: ${description}`);
+            });
+        }
+        console.error('\nPlease set the required environment variables and try again.');
+        console.error('Example:');
+        console.error('  export PULSEMCP_ADMIN_API_KEY="your-api-key"');
+        process.exit(1);
+    }
+}
+async function main() {
+    // Validate environment variables first
+    validateEnvironment();
+    // Create server using factory
+    const { server, registerHandlers } = createMCPServer();
+    // Register all handlers (resources and tools)
+    await registerHandlers(server);
+    // Start server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('pulsemcp-cms-admin');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/build/shared/src/index.js

@@ -0,0 +1,2 @@
+export { registerTools, createRegisterTools } from './tools.js';
+export { createMCPServer, PulseMCPAdminClient, } from './server.js';

package/build/shared/src/logging.js

@@ -0,0 +1,34 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+/**
+ * Log an error with context
+ */
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ERROR] ${context}: ${message}`);
+    if (stack) {
+        console.error(stack);
+    }
+}
+/**
+ * Log a warning
+ */
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+/**
+ * Log debug information (only in development)
+ */
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

package/build/shared/src/pulsemcp-admin-client/lib/create-post.js

@@ -0,0 +1,69 @@
+export async function createPost(apiKey, baseUrl, params) {
+    const url = new URL('/posts', baseUrl);
+    // Build form data for the POST request
+    const formData = new URLSearchParams();
+    // Required fields
+    formData.append('post[title]', params.title);
+    formData.append('post[body]', params.body);
+    formData.append('post[slug]', params.slug);
+    formData.append('post[author_id]', params.author_id.toString());
+    // Optional fields
+    if (params.status)
+        formData.append('post[status]', params.status);
+    if (params.category)
+        formData.append('post[category]', params.category);
+    if (params.image_url)
+        formData.append('post[image_url]', params.image_url);
+    if (params.preview_image_url)
+        formData.append('post[preview_image_url]', params.preview_image_url);
+    if (params.share_image)
+        formData.append('post[share_image]', params.share_image);
+    if (params.title_tag)
+        formData.append('post[title_tag]', params.title_tag);
+    if (params.short_title)
+        formData.append('post[short_title]', params.short_title);
+    if (params.short_description)
+        formData.append('post[short_description]', params.short_description);
+    if (params.description_tag)
+        formData.append('post[description_tag]', params.description_tag);
+    if (params.last_updated)
+        formData.append('post[last_updated]', params.last_updated);
+    if (params.table_of_contents)
+        formData.append('post[table_of_contents]', JSON.stringify(params.table_of_contents));
+    // Handle arrays for featured servers/clients
+    if (params.featured_mcp_server_ids) {
+        params.featured_mcp_server_ids.forEach((id) => {
+            formData.append('post[featured_mcp_server_ids][]', id.toString());
+        });
+    }
+    if (params.featured_mcp_client_ids) {
+        params.featured_mcp_client_ids.forEach((id) => {
+            formData.append('post[featured_mcp_client_ids][]', id.toString());
+        });
+    }
+    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 === 422) {
+            const errorData = (await response.json());
+            const errors = errorData.errors || ['Validation failed'];
+            throw new Error(`Validation failed: ${errors.join(', ')}`);
+        }
+        throw new Error(`Failed to create post: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-author-by-slug.js

@@ -0,0 +1,26 @@
+export async function getAuthorBySlug(apiKey, baseUrl, slug) {
+    // Use the supervisor endpoint which supports JSON
+    const url = new URL(`/supervisor/authors/${slug}`, 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 === 404) {
+            throw new Error(`Author not found: ${slug}`);
+        }
+        throw new Error(`Failed to fetch author: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // The supervisor endpoint returns the author object directly
+    return data;
+}

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

@@ -0,0 +1,38 @@
+export async function getAuthors(apiKey, baseUrl, params) {
+    // Use the supervisor endpoint which supports JSON
+    const url = new URL('/supervisor/authors', baseUrl);
+    // Add query parameters if provided
+    if (params?.search) {
+        url.searchParams.append('search', params.search);
+    }
+    if (params?.page) {
+        url.searchParams.append('page', params.page.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch authors: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return {
+        authors: data.data || [],
+        pagination: data.meta
+            ? {
+                current_page: data.meta.current_page,
+                total_pages: data.meta.total_pages,
+                total_count: data.meta.total_count,
+            }
+            : undefined,
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-mcp-client-by-slug.js

@@ -0,0 +1,26 @@
+export async function getMCPClientBySlug(apiKey, baseUrl, slug) {
+    // Use the supervisor endpoint which supports JSON
+    const url = new URL(`/supervisor/mcp_clients/${slug}`, 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 === 404) {
+            throw new Error(`MCP client not found: ${slug}`);
+        }
+        throw new Error(`Failed to fetch MCP client: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // The supervisor endpoint returns the MCP client object directly
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/get-mcp-server-by-slug.js

@@ -0,0 +1,26 @@
+export async function getMCPServerBySlug(apiKey, baseUrl, slug) {
+    // Use the supervisor endpoint which supports JSON
+    const url = new URL(`/supervisor/mcp_servers/${slug}`, 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 === 404) {
+            throw new Error(`MCP server not found: ${slug}`);
+        }
+        throw new Error(`Failed to fetch MCP server: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // The supervisor endpoint returns the MCP server object directly
+    return data;
+}

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

@@ -0,0 +1,26 @@
+export async function getPost(apiKey, baseUrl, slug) {
+    // Use the supervisor endpoint which supports JSON and returns full post data including body
+    const url = new URL(`/supervisor/posts/${slug}`, 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 === 404) {
+            throw new Error(`Post not found: ${slug}`);
+        }
+        throw new Error(`Failed to fetch post: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // The supervisor endpoint returns the full post object with all fields including body
+    return data;
+}

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

@@ -0,0 +1,62 @@
+export async function getPosts(apiKey, baseUrl, params) {
+    const url = new URL('/posts', baseUrl);
+    // Add query parameters if provided
+    if (params?.search) {
+        url.searchParams.append('search', params.search);
+    }
+    if (params?.sort) {
+        url.searchParams.append('sort', params.sort);
+    }
+    if (params?.direction) {
+        url.searchParams.append('direction', params.direction);
+    }
+    if (params?.page) {
+        url.searchParams.append('page', params.page.toString());
+    }
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error('Invalid API key');
+        }
+        if (response.status === 403) {
+            throw new Error('User lacks admin privileges');
+        }
+        throw new Error(`Failed to fetch posts: ${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 {
+            posts: data.data.map((post) => ({
+                id: post.id,
+                slug: post.slug,
+                title: post.title,
+                short_title: post.short_title,
+                short_description: post.short_description,
+                category: post.category,
+                status: post.status,
+                author_id: post.author_id,
+                created_at: post.created_at,
+                updated_at: post.updated_at,
+                last_updated: post.last_updated,
+            })),
+            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 {
+        posts: [],
+        pagination: undefined,
+    };
+}

package/build/shared/src/pulsemcp-admin-client/lib/update-post.js

@@ -0,0 +1,75 @@
+export async function updatePost(apiKey, baseUrl, slug, params) {
+    const url = new URL(`/posts/${slug}`, baseUrl);
+    // Build form data for the PUT request
+    const formData = new URLSearchParams();
+    // Add all provided fields
+    if (params.title !== undefined)
+        formData.append('post[title]', params.title);
+    if (params.body !== undefined)
+        formData.append('post[body]', params.body);
+    if (params.slug !== undefined)
+        formData.append('post[slug]', params.slug);
+    if (params.author_id !== undefined)
+        formData.append('post[author_id]', params.author_id.toString());
+    if (params.status !== undefined)
+        formData.append('post[status]', params.status);
+    if (params.category !== undefined)
+        formData.append('post[category]', params.category);
+    if (params.image_url !== undefined)
+        formData.append('post[image_url]', params.image_url);
+    if (params.preview_image_url !== undefined)
+        formData.append('post[preview_image_url]', params.preview_image_url);
+    if (params.share_image !== undefined)
+        formData.append('post[share_image]', params.share_image);
+    if (params.title_tag !== undefined)
+        formData.append('post[title_tag]', params.title_tag);
+    if (params.short_title !== undefined)
+        formData.append('post[short_title]', params.short_title);
+    if (params.short_description !== undefined)
+        formData.append('post[short_description]', params.short_description);
+    if (params.description_tag !== undefined)
+        formData.append('post[description_tag]', params.description_tag);
+    if (params.last_updated !== undefined)
+        formData.append('post[last_updated]', params.last_updated);
+    if (params.table_of_contents !== undefined)
+        formData.append('post[table_of_contents]', JSON.stringify(params.table_of_contents));
+    // Handle arrays for featured servers/clients
+    if (params.featured_mcp_server_ids !== undefined) {
+        params.featured_mcp_server_ids.forEach((id) => {
+            formData.append('post[featured_mcp_server_ids][]', id.toString());
+        });
+    }
+    if (params.featured_mcp_client_ids !== undefined) {
+        params.featured_mcp_client_ids.forEach((id) => {
+            formData.append('post[featured_mcp_client_ids][]', 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(`Post not found: ${slug}`);
+        }
+        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 update post: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data;
+}

package/build/shared/src/pulsemcp-admin-client/lib/upload-image.js

@@ -0,0 +1,36 @@
+export async function uploadImage(apiKey, baseUrl, postSlug, fileName, fileData) {
+    const url = new URL('/upload_image', baseUrl);
+    // Create form data for multipart upload
+    const formData = new FormData();
+    // Create a blob from the buffer
+    const blob = new Blob([fileData], { type: 'image/png' }); // Default to PNG, adjust as needed
+    // Add file to form data
+    formData.append('file', blob, fileName);
+    // Add folder path that includes the post slug
+    formData.append('folder', `newsletter/${postSlug}`);
+    // Add the full filepath
+    formData.append('filepath', `newsletter/${postSlug}/${fileName}`);
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            // Don't set Content-Type for FormData - let the browser set it with boundary
+        },
+        body: formData,
+    });
+    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.text();
+            throw new Error(`Validation failed: ${errorData}`);
+        }
+        throw new Error(`Failed to upload image: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data;
+}