Cosmic MCP Server

A robust, production-ready Model Context Protocol (MCP) server for interacting with the Cosmic headless CMS. This server provides a comprehensive set of tools for creating, reading, updating, and deleting objects, types, and media in your Cosmic bucket.

✨ Features

Comprehensive Toolset: Full CRUD operations for Cosmic objects, object types, and media.
Robust Architecture: Built with a clean, three-layer architecture (Server, Services, Repositories).
Strongly Typed: Written in TypeScript with strict validation using Zod for all inputs.
Production-Ready: Includes centralized logging, rate-limiting, and graceful error handling.
Easy to Configure: Simple setup using a .env file for your Cosmic credentials.
Extensible: Designed to be easily extended with new tools and services.

🚀 Getting Started

Prerequisites

Bun (v1.0 or higher)
A Cosmic account and bucket.

1. Installation

Clone the repository and install the dependencies:

git clone https://github.com/patgpt/cosmic-mcp.git
cd cosmic-mcp
bun install

2. Configuration

Copy the example environment file and fill in your Cosmic bucket credentials. You can find these in your Cosmic dashboard under Bucket > Settings > API Keys.

cp .env.example .env

Your .env file should look like this:

# .env
COSMIC_BUCKET_SLUG="your-bucket-slug"
COSMIC_READ_KEY="your-read-key"
COSMIC_WRITE_KEY="your-write-key"
DEBUG="false" # Set to "true" for verbose logging

3. Running the Server

Start the MCP server using the following command:

bun start

The server will connect and be ready to receive requests from any MCP-compatible client.

4. Using with MCP Clients

For VS Code (using Claude Dev extension)

Add this configuration to your VS Code settings or Claude Dev configuration:

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "cosmic-mcp"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "false"
        }
      }
    }
  }
}

For Cursor

Add this configuration to your .cursor/mcp.json file:

{
  "mcpServers": {
    "Cosmic": {
      "command": "npx",
      "args": ["-y", "cosmic-mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "false"
      }
    }
  }
}

Alternative: Local Development

If you're developing locally or prefer to use the local version:

For VS Code:

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "node",
        "args": ["path/to/cosmic-mcp/dist/server.js"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "true"
        }
      }
    }
  }
}

For Cursor:

{
  "mcpServers": {
    "Cosmic": {
      "command": "node",
      "args": ["path/to/cosmic-mcp/dist/server.js"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "true"
      }
    }
  }
}

Note: Replace your-bucket-slug, your-read-key, and your-write-key with your actual Cosmic bucket credentials. You can find these in your Cosmic dashboard under Bucket > Settings > API Keys.

🛠️ Available Tools

This MCP server exposes the following tools. All tools are designed to be called by an AI agent or other MCP client.

Tool Name	Description
`list_objects`	List objects, with optional filtering by type, status, and pagination.
`get_object`	Get a specific object by its ID or by its slug and type.
`create_object`	Create a new object.
`update_object`	Update an existing object.
`delete_object`	Delete an object.
`list_object_types`	List all available object types in the bucket.
`search_objects`	Perform a text-based search across objects.
`upload_media`	Upload a media file.
`list_media`	List all media files, with pagination.
`delete_media`	Delete a media file by its ID.

For detailed input schemas for each tool, please refer to the 📚 Documentation or the src/manifest.ts file.

📚 Documentation

Comprehensive documentation is available at https://patgpt.github.io/cosmic-mcp/

The documentation includes:

Getting Started Guide - Complete setup and installation instructions
Configuration Reference - All configuration options and environment variables
Tools API Documentation - Detailed reference for all available tools
AI Assistant Prompts - Example prompts for effective AI interaction
MCP Client Setup - Configuration for VS Code, Cursor, and other MCP clients

Local Documentation

You can also run the documentation locally:

# Install dependencies
npm install

# Start the documentation server
npm run docs:dev

# Build the documentation
npm run docs:build

🧪 Running Tests

This project is set up with tests to ensure reliability.

# Run all tests
bun test

🤝 Contributing

Contributions are welcome! If you have a suggestion or find a bug, please open an issue to discuss it.

Please see our CONTRIBUTING.md for detailed guidelines on how to contribute to this project, including:

Development setup and workflow
Code style and standards
Testing requirements
Pull request process
Release process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.