@nks-hub/nksweb-mcp

MCP server pro NKS-Web CMS — spravujte stránky, články, novinky, soubory, uživatele, analytiku a další přímo z Claude Code nebo jakéhokoliv MCP-kompatibilního klienta.

English version

Proč?

Místo přepínání mezi admin panely nechte AI asistenta spravovat CMS obsah přímo:

• "Vypiš všechny aktivní stránky"
• "Vytvoř nový článek o aktualizaci produktu"
• "Jaké jsou nejnavštěvovanější stránky tento měsíc?"
• "Ukaž rozdělení prohlížečů z analytiky"
• "Přepni na tenant acme a vypiš jejich novinky"

Rychlý start

Instalace

npm install -g @nks-hub/nksweb-mcp

Nebo klonováním a buildem:

git clone https://github.com/nks-hub/nksweb-mcp.git
cd nksweb-mcp
npm install && npm run build

Konfigurace

Přidejte do ~/.claude/.mcp.json nebo projektové MCP konfigurace:

{
  "mcpServers": {
    "nksweb": {
      "command": "node",
      "args": ["/cesta/k/nksweb-mcp/build/index.js"],
      "env": {
        "NKSWEB_URL": "https://vas-web.cz",
        "NKSWEB_API_KEY": "nks_vas_api_klic"
      }
    }
  }
}

Nebo přes Claude Code CLI:

claude mcp add nksweb -e NKSWEB_URL=https://vas-web.cz -e NKSWEB_API_KEY=nks_vas_klic -- npx @nks-hub/nksweb-mcp

Použití

Zeptejte se Claude Code na cokoliv ohledně vašeho CMS obsahu. Všechny nástroje jsou automaticky k dispozici.

Funkce

| Funkce | Popis | |--------|-------| | 49 nástrojů | Kompletní správa CMS — stránky, články, kategorie, novinky, soubory, uživatelé, zprávy, přesměrování, nastavení, analytika, tenanti | | Content bloky | Vytváření, aktualizace a mazání pojmenovaných bloků obsahu na stránkách (kompatibilní s Quill editorem) | | Multi-tenant | Výpis dostupných tenantů a přepínání kontextu pro správu dat libovolného tenanta | | Filtrování stránek | Filtry podle typu, stavu, jazyka nebo fulltextové hledání v názvu/URL/obsahu | | Analytické metriky | 14 analytických dimenzí — země, prohlížeče, zařízení, UTM kampaně a další | | Anotace nástrojů | MCP anotace (readOnly, destructive, idempotent) pro bezpečné použití AI | | Zkracování odpovědí | Automatické zkrácení na 25k znaků pro prevenci zahlcení kontextu | | Aktuální chyby | Chybové zprávy podle HTTP statusu, které navigují LLM ke správnému použití |

Proměnné prostředí

| Proměnná | Povinná | Popis | |----------|---------|-------| | NKSWEB_URL | Ano | Základní URL instance NKS-Web (např. https://vas-web.cz) | | NKSWEB_API_KEY | Ano | API klíč s příslušnými oprávněními (prefix nks_) |

Nástroje (49)

Stránky (8 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_pages | Výpis stránek s volitelnými filtry: type, status, search, lang | | nksweb_get_page | Detail stránky podle ID včetně HTML obsahu a extraData | | nksweb_create_page | Vytvoření nové stránky s obsahem, typem, SEO a nastavením navigace | | nksweb_update_page | Aktualizace stránky (částečná — posílají se jen změněná pole) | | nksweb_delete_page | Smazání stránky (soft-delete) | | nksweb_list_content_blocks | Výpis všech pojmenovaných bloků obsahu stránky | | nksweb_upsert_content_block | Vytvoření nebo aktualizace bloku obsahu podle klíče | | nksweb_delete_content_block | Smazání bloku obsahu stránky |

Články (5 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_articles | Výpis všech článků | | nksweb_get_article | Detail článku podle ID | | nksweb_create_article | Vytvoření článku s obsahem, kategoriemi a SEO | | nksweb_update_article | Aktualizace existujícího článku | | nksweb_delete_article | Smazání článku |

Kategorie (5 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_categories | Výpis všech kategorií článků | | nksweb_get_category | Detail kategorie podle ID | | nksweb_create_category | Vytvoření kategorie (podpora vnořeného stromu) | | nksweb_update_category | Aktualizace kategorie | | nksweb_delete_category | Smazání kategorie |

Novinky (5 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_news | Výpis všech novinek | | nksweb_get_news_item | Detail novinky podle ID | | nksweb_create_news | Vytvoření novinky | | nksweb_update_news | Aktualizace novinky | | nksweb_delete_news | Smazání novinky |

Soubory (3 nástroje)

| Nástroj | Popis | |---------|-------| | nksweb_list_files | Výpis všech nahraných souborů | | nksweb_get_file | Metadata souboru podle ID | | nksweb_delete_file | Smazání souboru |

Uživatelé (5 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_users | Výpis všech admin uživatelů | | nksweb_get_user | Detail uživatele podle ID | | nksweb_create_user | Vytvoření nového admin uživatele | | nksweb_update_user | Aktualizace profilu nebo role uživatele | | nksweb_delete_user | Smazání uživatele |

Zprávy (4 nástroje)

| Nástroj | Popis | |---------|-------| | nksweb_list_messages | Výpis všech zpráv z kontaktního formuláře | | nksweb_get_message | Detail zprávy podle ID | | nksweb_mark_message_read | Označení zprávy jako přečtené/nepřečtené | | nksweb_delete_message | Smazání zprávy |

Přesměrování (5 nástrojů)

| Nástroj | Popis | |---------|-------| | nksweb_list_redirects | Výpis všech URL přesměrování | | nksweb_get_redirect | Detail přesměrování podle ID | | nksweb_create_redirect | Vytvoření pravidla přesměrování (301/302/307) | | nksweb_update_redirect | Aktualizace přesměrování | | nksweb_delete_redirect | Smazání přesměrování |

Nastavení (3 nástroje)

| Nástroj | Popis | |---------|-------| | nksweb_list_settings | Výpis všech nastavení tenanta | | nksweb_get_setting | Získání konkrétního nastavení podle klíče | | nksweb_update_settings | Aktualizace jednoho nebo více nastavení |

Analytika (4 nástroje)

| Nástroj | Popis | |---------|-------| | nksweb_analytics_overview | Přehled návštěvnosti — sessions, pageviews, uživatelé, bounce rate, průměrná doba | | nksweb_analytics_pages | Nejnavštěvovanější stránky s počtem návštěv, pageviews, bounce rate | | nksweb_analytics_referrers | Největší zdroje návštěvnosti s počtem návštěv a procentem | | nksweb_analytics_metric | Rozdělení podle dimenze: country, browser, os, device_type, city, region, language, utm_source, utm_medium, utm_campaign, utm_content, utm_term, pathname, referrer |

Tenanti (2 nástroje)

| Nástroj | Popis | |---------|-------| | nksweb_list_tenants | Výpis dostupných tenantů (multi-tenant klíč: všechny, single-tenant klíč: aktuální) | | nksweb_set_tenant | Přepnutí aktivního tenanta — všechny následující operace cílí na něj |

Oprávnění API klíče

API klíč potřebuje příslušná oprávnění pro nástroje, které chcete používat:

| Oprávnění | Nástroje | |-----------|----------| | pages:read | výpis, detail stránek a content bloků | | pages:write | vytvoření, aktualizace, smazání stránek a content bloků | | articles:read / articles:write | správa článků | | categories:read / categories:write | správa kategorií | | news:read / news:write | správa novinek | | files:read / files:write | správa souborů | | users:read / users:write | správa uživatelů | | messages:read / messages:write | správa zpráv | | redirects:read / redirects:write | správa přesměrování | | settings:read / settings:write | správa nastavení | | analytics:read | přístup k analytice | | tenants:read | výpis tenantů |

Filtrování stránek

Nástroj nksweb_list_pages podporuje tyto filtry:

| Parametr | Typ | Popis | |----------|-----|-------| | type | string | Filtr podle typu: default, homepage, contact, gallery, pricing, team, faq, news, articles, video_gallery, product, features, templates, demo, nks-pricing | | status | number | 0 = neaktivní/koncept, 1 = aktivní/publikovaná | | search | string | Fulltextové hledání v názvu stránky, URL slugu a HTML obsahu | | lang | string | ISO 639-1 kód jazyka (např. cs, en) |

Parametry analytiky

Všechny analytické nástroje přijímají volitelné parametry časového rozsahu:

| Parametr | Typ | Popis | |----------|-----|-------| | startDate | string | Počáteční datum YYYY-MM-DD (výchozí: před 30 dny) | | endDate | string | Koncové datum YYYY-MM-DD (výchozí: dnes) | | limit | number | Max výsledků 1–100 (výchozí: 10) |

Dostupné metriky

Nástroj nksweb_analytics_metric podporuje tyto dimenze:

| Metrika | Popis | |---------|-------| | pathname | Cesty stránek (stejné jako top stránky) | | referrer | Zdroje návštěvnosti | | country | Země návštěvníků | | region | Regiony/kraje návštěvníků | | city | Města návštěvníků | | browser | Názvy prohlížečů (Chrome, Firefox, Safari, …) | | os | Operační systémy (Windows, macOS, iOS, Android, …) | | device_type | Kategorie zařízení (desktop, mobile, tablet) | | language | Nastavení jazyka prohlížeče | | utm_source | UTM source parametr | | utm_medium | UTM medium parametr | | utm_campaign | UTM campaign parametr | | utm_content | UTM content parametr | | utm_term | UTM term parametr |

Struktura projektu

nksweb-mcp/
├── src/
│   ├── index.ts          # Vstupní bod, nastavení MCP serveru
│   ├── client.ts         # HTTP klient s přepínáním tenantů (X-Tenant hlavička)
│   ├── constants.ts      # Timeouty a limity
│   └── tools/
│       ├── pages.ts      # Stránky + content bloky (8 nástrojů)
│       ├── articles.ts   # Články CRUD (5 nástrojů)
│       ├── categories.ts # Kategorie CRUD (5 nástrojů)
│       ├── news.ts       # Novinky CRUD (5 nástrojů)
│       ├── files.ts      # Správa souborů (3 nástroje)
│       ├── users.ts      # Uživatelé CRUD (5 nástrojů)
│       ├── messages.ts   # Správa zpráv (4 nástroje)
│       ├── redirects.ts  # Přesměrování CRUD (5 nástrojů)
│       ├── settings.ts   # Správa nastavení (3 nástroje)
│       ├── analytics.ts  # Analytické dotazy (4 nástroje)
│       └── tenants.ts    # Multi-tenant přepínání (2 nástroje)
├── tests/
│   └── integration.test.ts
├── build/                # Zkompilovaný JS výstup
├── package.json
├── tsconfig.json
└── LICENSE

Příklady

Správa obsahu

Uživatel: "Vypiš všechny aktivní stránky"
→ nksweb_list_pages { status: 1 }

Uživatel: "Najdi stránky obsahující 'pricing'"
→ nksweb_list_pages { search: "pricing" }

Uživatel: "Ukaž mi homepage"
→ nksweb_list_pages { type: "homepage" }

Uživatel: "Vytvoř novou FAQ stránku"
→ nksweb_create_page { name: "FAQ", url: "faq", type: "faq", status: 1,
    content: "<h1>Často kladené otázky</h1>" }

Uživatel: "Aktualizuj hero nadpis na homepage"
→ nksweb_upsert_content_block { pageId: 14, key: "hero_heading",
    content: "Digitální řešení, která fungují", label: "Hero Heading" }

Analytika

Uživatel: "Jak je na tom návštěvnost tento měsíc?"
→ nksweb_analytics_overview { startDate: "2026-03-01" }

Uživatel: "Jaké prohlížeče používají naši návštěvníci?"
→ nksweb_analytics_metric { metric: "browser", limit: 10 }

Uživatel: "Ukaž rozdělení podle zemí za poslední týden"
→ nksweb_analytics_metric { metric: "country",
    startDate: "2026-03-02", endDate: "2026-03-09" }

Uživatel: "Top 5 nejnavštěvovanějších stránek"
→ nksweb_analytics_pages { limit: 5 }

Uživatel: "Odkud nám chodí návštěvnost?"
→ nksweb_analytics_referrers {}

Multi-tenant

Uživatel: "Jací tenanti jsou k dispozici?"
→ nksweb_list_tenants {}

Uživatel: "Přepni na tenant acme"
→ nksweb_set_tenant { slug: "acme" }

Uživatel: "Teď vypiš jejich stránky"
→ nksweb_list_pages {}  (automaticky cílí na acme)

Uživatel: "Vrať se na výchozí"
→ nksweb_set_tenant { slug: "" }

Články a novinky

Uživatel: "Vytvoř článek o naší nové funkci"
→ nksweb_create_article { title: "Představujeme chytré vyhledávání",
    url: "predstavujeme-chytre-vyhledavani", status: 1,
    content: "<p>S radostí oznamujeme...</p>" }

Uživatel: "Vypiš všechny novinky"
→ nksweb_list_news {}

Uživatel: "Smaž novinku #5"
→ nksweb_delete_news { id: 5 }

Nastavení a přesměrování

Uživatel: "Jaká nastavení má tento tenant?"
→ nksweb_list_settings {}

Uživatel: "Přidej přesměrování z /stara-stranka na /nova-stranka"
→ nksweb_create_redirect { source: "/stara-stranka", target: "/nova-stranka",
    statusCode: 301, isActive: true }

Uživatel: "Ukaž všechny zprávy z kontaktního formuláře"
→ nksweb_list_messages {}

Vývoj

# Instalace závislostí
npm install

# Build
npm run build

# Watch mód
npm run dev

# Integrační testy
npm test

# Kontrola typů
npx tsc --noEmit

Požadavky

• Node.js: 18+
• NKS-Web CMS: Instance se zapnutým API a vytvořeným API klíčem

Přispívání

Příspěvky jsou vítány! Pro větší změny prosím nejdříve otevřete issue.

1. Forkujte repozitář
2. Vytvořte feature branch (git checkout -b feature/skvela-funkce)
3. Commitněte změny (git commit -m 'feat: popis')
4. Pushujte branch (git push origin feature/skvela-funkce)
5. Otevřete Pull Request

Podpora

• Email: [email protected]
• Bug reporty: GitHub Issues
• MCP Protokol: modelcontextprotocol.io

Licence

MIT License — viz LICENSE.

Odkazy

• NKS-Web CMS
• npm balíček
• @nks-hub/rybbit-mcp — MCP server pro Rybbit Analytics
• @nks-hub/rybbit-ts — TypeScript tracking SDK