panda-mcp 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3f0f46edbc22c1c994ba3c6327b58dc5e7689d5a2367292a57b5116d5acc487
+  data.tar.gz: 0ef7c056456594d90d4563632c1ae5c333009a01ad22741c255f5fa57033f5da
+SHA512:
+  metadata.gz: da193e6069352b733ef7226cad5c2e93129d5fdd7f744e906901e05629725e8411b53ce25942197a5f1d5243cad9d72030bf14fb2a92044759849ec4ca93b634
+  data.tar.gz: e8844bf0e478b216b83753388d8eb93f0f1a31b9781629f7d4953c895117f58fbb388604f616eb8ce93feffdad8ebf313ae56ddaf1473133dc108e944fc66c72

data/README.md

@@ -0,0 +1,65 @@
+# Panda CMS MCP Server
+
+Ruby MCP server for Panda CMS. Provides tools for creating and updating draft pages, posts, and collection items, plus read-only access to templates, page hierarchy, and content listings.
+
+## Installation
+
+```bash
+gem install panda-mcp
+```
+
+## Quick Start
+
+1. Install the gem:
+
+```bash
+gem install panda-mcp
+```
+
+2. Get your API token from Panda CMS admin at `/manage/my_profile/api_tokens`
+
+3. Configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "panda-cms": {
+      "command": "panda-mcp",
+      "env": {
+        "PANDA_CMS_API_URL": "https://your-site.com",
+        "PANDA_CMS_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+4. Restart Claude Desktop
+
+## Available Tools
+
+- `list_templates`
+- `list_page_tree`
+- `list_pages`
+- `get_page`
+- `create_draft_page`
+- `update_page`
+- `submit_page_for_review`
+- `list_posts`
+- `get_post`
+- `create_draft_post`
+- `update_draft_post`
+- `submit_post_for_review`
+- `list_collections`
+- `list_collection_items`
+- `get_collection_item`
+- `create_collection_item_draft`
+- `update_collection_item_draft`
+- `search_content`
+
+## Notes
+
+- Markdown content is converted to EditorJS via the Panda CMS API.
+- Collection items default to `visible=false` when created via the MCP server.
+
+See `../docs/api.md` for the full API reference.

data/exe/panda-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "panda_mcp"
+
+PandaMCP::Server.start!

data/lib/panda_mcp/client.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module PandaMCP
+  class ApiError < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status, body)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class Client
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 120
+    WRITE_TIMEOUT = 120
+
+    def initialize(base_url, token)
+      @base_url = base_url.to_s.sub(%r{/+$}, "")
+      @token = token
+      @debug = ENV["PANDA_MCP_DEBUG"] == "1"
+    end
+
+    def list_templates
+      request(:get, "/api/v1/templates")
+    end
+
+    def list_pages(params = {})
+      request(:get, "/api/v1/pages", query: compact_params(params))
+    end
+
+    def get_page(id)
+      request(:get, "/api/v1/pages/#{id}")
+    end
+
+    def list_page_tree
+      request(:get, "/api/v1/pages/tree")
+    end
+
+    def create_page(payload)
+      request(:post, "/api/v1/pages", body: {page: payload})
+    end
+
+    def update_page(id, payload)
+      request(:patch, "/api/v1/pages/#{id}", body: {page: payload})
+    end
+
+    def submit_page_for_review(id)
+      request(:post, "/api/v1/pages/#{id}/submit_for_review", body: {})
+    end
+
+    def approve_page(id)
+      request(:post, "/api/v1/pages/#{id}/approve", body: {})
+    end
+
+    def publish_page(id)
+      request(:post, "/api/v1/pages/#{id}/publish", body: {})
+    end
+
+    def list_posts(params = {})
+      request(:get, "/api/v1/posts", query: compact_params(params))
+    end
+
+    def get_post(id)
+      request(:get, "/api/v1/posts/#{id}")
+    end
+
+    def create_post(payload)
+      request(:post, "/api/v1/posts", body: {post: payload})
+    end
+
+    def update_post(id, payload)
+      request(:patch, "/api/v1/posts/#{id}", body: {post: payload})
+    end
+
+    def submit_post_for_review(id)
+      request(:post, "/api/v1/posts/#{id}/submit_for_review", body: {})
+    end
+
+    def approve_post(id)
+      request(:post, "/api/v1/posts/#{id}/approve", body: {})
+    end
+
+    def publish_post(id)
+      request(:post, "/api/v1/posts/#{id}/publish", body: {})
+    end
+
+    # Version history
+
+    def list_page_versions(page_id)
+      request(:get, "/api/v1/pages/#{page_id}/versions")
+    end
+
+    def get_page_version(page_id, version_number)
+      request(:get, "/api/v1/pages/#{page_id}/versions/#{version_number}")
+    end
+
+    def diff_page_version(page_id, version_number)
+      request(:get, "/api/v1/pages/#{page_id}/versions/#{version_number}/diff")
+    end
+
+    def restore_page_version(page_id, version_number)
+      request(:post, "/api/v1/pages/#{page_id}/versions/#{version_number}/restore", body: {})
+    end
+
+    def list_post_versions(post_id)
+      request(:get, "/api/v1/posts/#{post_id}/versions")
+    end
+
+    def get_post_version(post_id, version_number)
+      request(:get, "/api/v1/posts/#{post_id}/versions/#{version_number}")
+    end
+
+    def diff_post_version(post_id, version_number)
+      request(:get, "/api/v1/posts/#{post_id}/versions/#{version_number}/diff")
+    end
+
+    def restore_post_version(post_id, version_number)
+      request(:post, "/api/v1/posts/#{post_id}/versions/#{version_number}/restore", body: {})
+    end
+
+    # Content suggestions
+
+    def list_content_suggestions(params = {})
+      request(:get, "/api/v1/content_suggestions", query: compact_params(params))
+    end
+
+    def get_content_suggestion(id)
+      request(:get, "/api/v1/content_suggestions/#{id}")
+    end
+
+    def approve_content_suggestion(id, notes: nil)
+      request(:post, "/api/v1/content_suggestions/#{id}/approve", body: compact_params({notes: notes}))
+    end
+
+    def reject_content_suggestion(id, notes:)
+      request(:post, "/api/v1/content_suggestions/#{id}/reject", body: {notes: notes})
+    end
+
+    def list_collections
+      request(:get, "/api/v1/collections")
+    end
+
+    def get_collection(id)
+      request(:get, "/api/v1/collections/#{id}")
+    end
+
+    def create_collection(payload)
+      request(:post, "/api/v1/collections", body: {collection: payload})
+    end
+
+    def update_collection(id, payload)
+      request(:patch, "/api/v1/collections/#{id}", body: {collection: payload})
+    end
+
+    def delete_collection(id)
+      request(:delete, "/api/v1/collections/#{id}")
+    end
+
+    def list_collection_items(collection_id, params = {})
+      request(:get, "/api/v1/collections/#{collection_id}/items", query: compact_params(params))
+    end
+
+    def get_collection_item(collection_id, id)
+      request(:get, "/api/v1/collections/#{collection_id}/items/#{id}")
+    end
+
+    def create_collection_item(collection_id, payload)
+      request(:post, "/api/v1/collections/#{collection_id}/items", body: {collection_item: payload})
+    end
+
+    def update_collection_item(collection_id, id, payload)
+      request(:patch, "/api/v1/collections/#{collection_id}/items/#{id}", body: {collection_item: payload})
+    end
+
+    def delete_collection_item(collection_id, id)
+      request(:delete, "/api/v1/collections/#{collection_id}/items/#{id}")
+    end
+
+    def convert_markdown(markdown)
+      request(:post, "/api/v1/markdown/convert", body: {markdown: markdown})
+    end
+
+    # File management
+
+    def list_files(params = {})
+      request(:get, "/api/v1/files", query: compact_params(params))
+    end
+
+    def get_file(id)
+      request(:get, "/api/v1/files/#{id}")
+    end
+
+    def upload_file(data:, filename:, content_type:, category_slug: nil, description: nil)
+      payload = {
+        data: data,
+        filename: filename,
+        content_type: content_type
+      }
+      payload[:category_slug] = category_slug if category_slug
+      payload[:description] = description if description
+
+      request(:post, "/api/v1/files", body: {file: payload})
+    end
+
+    def update_file(id, payload)
+      request(:patch, "/api/v1/files/#{id}", body: {file: payload})
+    end
+
+    def delete_file(id)
+      request(:delete, "/api/v1/files/#{id}")
+    end
+
+    def list_file_categories
+      request(:get, "/api/v1/file_categories")
+    end
+
+    private
+
+    def request(method, path, body: nil, query: nil)
+      uri = URI.join(@base_url + "/", path.delete_prefix("/"))
+      if query&.any?
+        uri.query = URI.encode_www_form(query)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http.write_timeout = WRITE_TIMEOUT
+
+      request = build_request(method, uri)
+      request["Authorization"] = "Token #{@token}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.dump(body) if body
+
+      body_size = request.body&.bytesize || 0
+      log("#{method.upcase} #{uri} (#{body_size} bytes)")
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = http.request(request)
+      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+      log("#{response.code} (#{response.body&.bytesize || 0} bytes, #{elapsed_ms}ms)")
+
+      parsed_body = parse_json(response.body)
+
+      if response.code.to_i >= 200 && response.code.to_i < 300
+        parsed_body
+      else
+        message = parsed_body["error"] || parsed_body["message"] || "HTTP #{response.code}"
+        if parsed_body["messages"].is_a?(Array) && parsed_body["messages"].any?
+          message = "#{message}: #{parsed_body["messages"].join("; ")}"
+        end
+        raise ApiError.new(message, response.code.to_i, parsed_body)
+      end
+    rescue Net::OpenTimeout
+      raise ApiError.new("Connection timed out after #{OPEN_TIMEOUT}s connecting to #{uri.host}", 0, {})
+    rescue Net::ReadTimeout
+      raise ApiError.new("Request timed out after #{READ_TIMEOUT}s waiting for response (body was #{body_size} bytes)", 0, {})
+    rescue Net::WriteTimeout
+      raise ApiError.new("Write timed out after #{WRITE_TIMEOUT}s sending request (body was #{body_size} bytes)", 0, {})
+    rescue Errno::ECONNREFUSED
+      raise ApiError.new("Connection refused to #{uri.host}:#{uri.port} — is the server running?", 0, {})
+    rescue Errno::ECONNRESET
+      raise ApiError.new("Connection reset by #{uri.host} — the server may have dropped the connection", 0, {})
+    rescue SocketError => e
+      raise ApiError.new("DNS/socket error for #{uri.host}: #{e.message}", 0, {})
+    rescue OpenSSL::SSL::SSLError => e
+      raise ApiError.new("SSL error connecting to #{uri.host}: #{e.message}", 0, {})
+    end
+
+    def build_request(method, uri)
+      case method
+      when :get
+        Net::HTTP::Get.new(uri)
+      when :post
+        Net::HTTP::Post.new(uri)
+      when :patch
+        Net::HTTP::Patch.new(uri)
+      when :put
+        Net::HTTP::Put.new(uri)
+      when :delete
+        Net::HTTP::Delete.new(uri)
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    def parse_json(body)
+      return {} if body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {"raw" => body}
+    end
+
+    def compact_params(params)
+      params.each_with_object({}) do |(key, value), acc|
+        next if value.nil?
+
+        acc[key] = value
+      end
+    end
+
+    def log(message)
+      warn "[PandaMCP] #{message}" if @debug
+    end
+  end
+end

data/lib/panda_mcp/server.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+require_relative "client"
+require_relative "tools"
+
+module PandaMCP
+  # Some MCP clients (e.g. Cowork) wrap tool arguments inside a "data" key
+  # instead of passing them as top-level properties. This module unwraps
+  # that before the mcp gem's schema validation runs.
+  module DataUnwrapper
+    private
+
+    def call_tool(request)
+      arguments = request[:arguments]
+
+      if arguments.is_a?(Hash)
+        data_key = if arguments.key?(:data)
+          :data
+        elsif arguments.key?("data")
+          "data"
+        end
+
+        if data_key && arguments.keys == [data_key]
+          tool = tools[request[:name]]
+          if tool && !tool.input_schema_value.to_h.dig(:properties, :data)
+            request = request.merge(arguments: arguments[data_key])
+          end
+        end
+      end
+
+      super
+    end
+  end
+
+  class Server
+    def self.start!
+      api_url = ENV.fetch("PANDA_CMS_API_URL", "http://localhost:3000")
+      api_token = ENV["PANDA_CMS_API_TOKEN"]
+
+      if api_token.to_s.strip.empty?
+        warn "Error: PANDA_CMS_API_TOKEN environment variable is required"
+        exit(1)
+      end
+
+      client = PandaMCP::Client.new(api_url, api_token)
+
+      # Pin to 2025-06-18 protocol version as Claude Desktop doesn't yet support
+      # the mcp gem's default (2025-11-25), causing an immediate disconnect after
+      # the initialize handshake. Override via PANDA_MCP_PROTOCOL_VERSION if needed.
+      configuration = MCP::Configuration.new(
+        protocol_version: ENV.fetch("PANDA_MCP_PROTOCOL_VERSION", "2025-06-18")
+      )
+
+      MCP::Server.prepend(DataUnwrapper)
+
+      server = MCP::Server.new(
+        name: "panda-cms",
+        version: PandaMCP::VERSION,
+        tools: PandaMCP::Tools.all,
+        server_context: {client: client},
+        configuration: configuration
+      )
+
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      transport.open
+    end
+  end
+end