pulsemcp-cms-admin-mcp-server 0.0.2

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pulsemcp-cms-admin-mcp-server",
+  "version": "0.0.2",
+  "description": "Local implementation of PulseMCP CMS Admin MCP server",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "pulsemcp-cms-admin-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { registerTools, createRegisterTools } from './tools.js';
+export { createMCPServer, type ClientFactory, type IPulseMCPAdminClient, PulseMCPAdminClient, } from './server.js';
+export type { Post, PostsResponse, CreatePostParams, UpdatePostParams, ImageUploadResponse, Author, AuthorsResponse, MCPServer, MCPClient, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/shared/index.js

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

package/shared/logging.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+/**
+ * Log an error with context
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Log a warning
+ */
+export declare function logWarning(context: string, message: string): void;
+/**
+ * Log debug information (only in development)
+ */
+export declare function logDebug(context: string, message: string): void;
+//# sourceMappingURL=logging.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/create-post.d.ts

@@ -0,0 +1,3 @@
+import type { Post, CreatePostParams } from '../../types.js';
+export declare function createPost(apiKey: string, baseUrl: string, params: CreatePostParams): Promise<Post>;
+//# sourceMappingURL=create-post.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-author-by-slug.d.ts

@@ -0,0 +1,3 @@
+import type { Author } from '../../types.js';
+export declare function getAuthorBySlug(apiKey: string, baseUrl: string, slug: string): Promise<Author>;
+//# sourceMappingURL=get-author-by-slug.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-authors.d.ts

@@ -0,0 +1,6 @@
+import type { AuthorsResponse } from '../../types.js';
+export declare function getAuthors(apiKey: string, baseUrl: string, params?: {
+    search?: string;
+    page?: number;
+}): Promise<AuthorsResponse>;
+//# sourceMappingURL=get-authors.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-mcp-client-by-slug.d.ts

@@ -0,0 +1,3 @@
+import type { MCPClient } from '../../types.js';
+export declare function getMCPClientBySlug(apiKey: string, baseUrl: string, slug: string): Promise<MCPClient>;
+//# sourceMappingURL=get-mcp-client-by-slug.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-mcp-server-by-slug.d.ts

@@ -0,0 +1,3 @@
+import type { MCPServer } from '../../types.js';
+export declare function getMCPServerBySlug(apiKey: string, baseUrl: string, slug: string): Promise<MCPServer>;
+//# sourceMappingURL=get-mcp-server-by-slug.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-post.d.ts

@@ -0,0 +1,3 @@
+import type { Post } from '../../types.js';
+export declare function getPost(apiKey: string, baseUrl: string, slug: string): Promise<Post>;
+//# sourceMappingURL=get-post.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/get-posts.d.ts

@@ -0,0 +1,8 @@
+import type { PostsResponse } from '../../types.js';
+export declare function getPosts(apiKey: string, baseUrl: string, params?: {
+    search?: string;
+    sort?: string;
+    direction?: 'asc' | 'desc';
+    page?: number;
+}): Promise<PostsResponse>;
+//# sourceMappingURL=get-posts.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/update-post.d.ts

@@ -0,0 +1,3 @@
+import type { Post, UpdatePostParams } from '../../types.js';
+export declare function updatePost(apiKey: string, baseUrl: string, slug: string, params: UpdatePostParams): Promise<Post>;
+//# sourceMappingURL=update-post.d.ts.map

package/shared/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/shared/pulsemcp-admin-client/lib/upload-image.d.ts

@@ -0,0 +1,3 @@
+import type { ImageUploadResponse } from '../../types.js';
+export declare function uploadImage(apiKey: string, baseUrl: string, postSlug: string, fileName: string, fileData: Buffer): Promise<ImageUploadResponse>;
+//# sourceMappingURL=upload-image.d.ts.map

package/shared/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;
+}

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

@@ -0,0 +1,3 @@
+export type { IPulseMCPAdminClient } from '../server.js';
+export type { Post, PostsResponse, CreatePostParams, UpdatePostParams, ImageUploadResponse, } from '../types.js';
+//# sourceMappingURL=pulsemcp-admin-client.d.ts.map

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

@@ -0,0 +1,27 @@
+import type { IPulseMCPAdminClient } from '../server.js';
+import type { Post, ImageUploadResponse, Author, MCPServer, MCPClient } from '../types.js';
+interface MockData {
+    posts?: Post[];
+    postsBySlug?: Record<string, Post>;
+    createPostResponse?: Post;
+    updatePostResponse?: Post;
+    uploadImageResponse?: ImageUploadResponse;
+    authors?: Author[];
+    authorsBySlug?: Record<string, Author>;
+    mcpServersBySlug?: Record<string, MCPServer>;
+    mcpClientsBySlug?: Record<string, MCPClient>;
+    errors?: {
+        getPosts?: Error;
+        getPost?: Error;
+        createPost?: Error;
+        updatePost?: Error;
+        uploadImage?: Error;
+        getAuthors?: Error;
+        getAuthorBySlug?: Error;
+        getMCPServerBySlug?: Error;
+        getMCPClientBySlug?: Error;
+    };
+}
+export declare function createMockPulseMCPAdminClient(mockData: MockData): IPulseMCPAdminClient;
+export {};
+//# sourceMappingURL=pulsemcp-admin-client.integration-mock.d.ts.map