Jak zprovoznit MCP server ve Folio a Cursor

Model Context Protocol (MCP) je otevřený standard od Anthropicu, který umožňuje AI agentům přímo pracovat s externími systémy. Do Folio CMS jsme integrovali MCP server - teď můžete z Cursor IDE vytvářet stránky, upravovat články nebo nahrávat soubory jedním promptem.

Co budete potřebovat

Rails aplikaci s Folio CMS (verze s MCP podporou)
Cursor IDE (nebo jiný MCP-kompatibilní klient)
Admin účet ve Folio Console

Celé nastavení zabere asi 10 minut.

Krok 1: Instalace MCP do Folio

Spusťte generátor, který přidá potřebné migrace a konfigurační soubory:

Bash

rails generate folio:mcp:install
rails db:migrate

Krok 2: Konfigurace resources

Upravte soubor config/initializers/folio_mcp.rb a definujte, jaké modely bude MCP spravovat:

config/initializers/folio_mcp.rb

Ruby

12345678910111213141516171819202122232425

Folio::Mcp.configure do |config|
  config.enabled = true

  config.resources = {
    pages: {
      model: "Folio::Page",
      fields: %i[title slug perex meta_title meta_description published locale],
      tiptap_fields: %i[tiptap_content],
      cover_field: :cover,
      versioned: true
    },
    articles: {
      model: "SinfinDigital::FlashArticle",
      fields: %i[title subtitle slug published featured],
      tiptap_fields: %i[tiptap_content]
    },
    files: {
      model: "Folio::File::Image",
      searchable: true,
      uploadable: true
    }
  }

  config.locales = %i[cs en]
end

Každý resource může mít fields (jednoduché atributy), tiptap_fields (rich text), cover_field (hlavní obrázek) a versioned (historie změn).

Krok 3: Vygenerování API tokenu

Token je vázán na konkrétního uživatele a dědí jeho oprávnění. Zobrazí se pouze jednou - uložte si ho.

Bash

# Generování nového tokenu
rails folio:mcp:generate_token[vas@email.cz]

# Seznam uživatelů s povoleným MCP
rails folio:mcp:list_enabled

# Deaktivace MCP pro uživatele
rails folio:mcp:disable[vas@email.cz]

Krok 4: Konfigurace Cursor IDE

Vytvořte soubor .cursor/mcp.json v kořeni projektu. Pro produkční prostředí změňte URL na vaši doménu.

.cursor/mcp.json

JSON

{
  "mcpServers": {
    "folio-local": {
      "type": "http",
      "url": "http://localhost:3000/folio/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_live_vas_token_zde"
      }
    }
  }
}

Po uložení restartujte Cursor. MCP server by se měl objevit v seznamu dostupných nástrojů.

Krok 5: Ověření spojení

Otestujte spojení přímo z terminálu. Pokud vše funguje, dostanete odpověď s pong.

Bash

curl -X POST http://localhost:3000/folio/api/mcp \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Dostupné nástroje

Pro každý nakonfigurovaný resource MCP automaticky vytvoří sadu CRUD nástrojů plus specializované nástroje pro soubory, verze a překlady.

Ruby

# CRUD operace (pro každý resource)
get_page(id)                              # Získání záznamu
list_pages(limit, offset, locale)         # Výpis záznamů
create_page(title, slug, tiptap_content)  # Vytvoření
update_page(id, title, ...)               # Úprava

# Práce se soubory
upload_file(url, alt, tags)               # Nahrání z URL
list_files(query)                         # Vyhledání

# Historie verzí (pokud versioned: true)
list_page_versions(id)                    # Seznam verzí
get_page_version(id, version)             # Konkrétní verze
restore_page_version(id, version)         # Obnovení

# Překlady
extract_translatable_texts(tiptap)        # Extrakce textů
apply_translations(original, translations) # Aplikace překladů

Práce s Tiptap obsahem

Tiptap je rich text editor používaný ve Folio. Obsah se ukládá jako JSON. Seznam dostupných node typů získáte přes MCP resource folio://tiptap/schema.

JSON

1234567891011121314151617181920

// Základní struktura Tiptap dokumentu
{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Obyčejný odstavec" }
      ]
    },
    {
      "type": "folioTiptapNode",
      "attrs": {
        "type": "SinfinDigital::Tiptap::Node::Contents::Title",
        "version": 1,
        "data": { "title": "Nadpis", "tag": "H2" }
      }
    }
  ]
}

Připojování obrázků

Pozor na konvenci pojmenování - název atributu závisí na tom, jestli jde o jeden obrázek nebo kolekci:

JSON

// Jeden obrázek (cover: :image)
"cover_placement_attributes": { "file_id": 123 }

// Více obrázků (images: :images)
"image_placements_attributes": [
  { "file_id": 123 },
  { "file_id": 124 }
]

Zabezpečení a konfigurace

MCP server používá stejná pravidla jako Folio Console - autentizaci Bearer tokeny, autorizaci přes Folio::Ability, a respektuje site boundaries. Můžete nastavit rate limiting a audit logging.

Ruby

# config/initializers/folio_mcp.rb
config.rate_limit = 100 # požadavků/minutu

config.audit_logger = ->(event) {
  Rails.logger.tagged("MCP") { Rails.logger.info(event.to_json) }
}

Troubleshooting

404 Not Found - Zkontrolujte, že Folio::Mcp.enabled? vrací true. Restartujte Rails server po změně konfigurace.

401 Unauthorized - Ověřte správnost tokenu. Uživatel musí mít mcp_enabled: true.

Validation Errors - MCP používá stejné validace jako Console. Zkontrolujte povinná pole modelu.

MCP server je součástí Folio CMS. Kompletní dokumentaci najdete v repozitáři. Máte dotazy? Ozvěte se nám.