tecof-mcp
OfficialManage Tecof theme pages and content via MCP: read, validate, create, update, and delete draft pages, plus get preview URLs.
Get site context: store, languages, active theme, token scope/expiry, page count.
List theme components (sections/elements) from disk with fields, slots, defaultProps, and variants.
List pages and get a page draft as an outline or full JSON.
Validate a page document (sections or full document) without saving.
Create draft pages from sections; Header/Footer auto-copied from a layout source.
Update draft pages via operations (append/insert/replace/remove/move section, set props/slots/root props) or full document; meta updates possible; shared components are read-only.
Soft-delete pages with explicit user confirmation.
Get 1-hour preview URLs for draft pages (storefront + local).
Remote mode adds backend Tools API proxy for CMS, products, themes, domains, orders, customers, marketing, SEO, translation, pricing, inventory, etc.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tecof-mcp show me the component list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@tecof/mcp
stdio MCP server for the Tecof Developer API v1. Runs from inside a Tecof theme repo; reads theme components from disk (AST), converts the agent's simple "section" definitions into editor documents, and creates/updates draft pages via the Developer API. Publishing is always done from the panel (there is no publish in the API).
SDK:
@modelcontextprotocol/server@^2(+zod@^4) —McpServer+serveStdioNode ≥ 20, ESM
Tool annotations (
readOnlyHint,destructiveHint) and_meta["anthropic/requiresUserInteraction"](delete) supported
Installation
At the root of the theme repo:
# 1) Panelden API anahtarı üretin: Ayarlar → Geliştirici / API Anahtarları (scope: pages:read, pages:write)
# 2) .env (gitignore'da) içine yazın
echo 'TECOF_API_TOKEN=tcf_...' >> .envThe server runs via npx; no global install needed:
npx -y @tecof/mcp@latestEnvironment variables
The project directory is resolved in the order TECOF_PROJECT_DIR → CLAUDE_PROJECT_DIR → process.cwd();
.env and .env.local are read from there. process.env is not overwritten — file values only
fill in keys that are empty (.env.local > .env).
Variable | Required | Description |
| yes |
|
| yes* | Backend address; if missing, |
| no | Global theme id; if missing, |
| no | Local preview root (default |
| no | If the theme repo is in a different directory |
If the token/URL is missing, the server still starts; list_components and validate_document
work, page tools return an error with guidance. Logs are written only to stderr;
uncaught errors also go to stderr, the process does not crash.
Security: TECOF_API_URL must be https. If an http:// (non-loopback) address is given,
a stderr warning is printed at startup and the same hint is appended to every tool error; http→https
redirects are not followed (Node fetch drops Authorization on redirect,
producing a misleading 401) — a 3xx response is converted to a "TECOF_API_URL scheme/host is wrong" error.
The request timeout (30 sec) covers the entire header + body read.
Claude Code — .mcp.json
{
"mcpServers": {
"tecof": {
"type": "stdio",
"command": "npx",
"args": ["-y", "${TECOF_MCP_PACKAGE:-@tecof/mcp@latest}"]
}
}
}The TECOF_MCP_PACKAGE env overrides the package spec — before publishing to npm or for local
development, point it at this repo folder (npx -y /path/to/tecof-mcp runs the bin in the folder):
export TECOF_MCP_PACKAGE=/Users/<siz>/Desktop/Tecof/tecof-mcp # claude'u bu shell'den başlatınPublishing (npm)
npm run build && npm test && node scripts/smoke.mjs
npm version patch # ya da minor
npm publish --access public # @tecof kapsamı — tecof-theme-editor/analytics ile aynı hesapCodex — .codex/config.toml
[mcp_servers.tecof]
command = "npx"
args = ["-y", "@tecof/mcp@latest"]Gemini CLI — .gemini/settings.json
{
"mcpServers": {
"tecof": {
"command": "npx",
"args": ["-y", "@tecof/mcp@latest"]
}
}
}The token is never written to any configuration file; it stays in .env. The client process
starts at the root of the theme repo, and the server reads .env from there.
Related MCP server: officeagent-net
Tools
Tool | Input | What it does |
| — | Store, languages, theme (themeId/merchantThemeId/domain), token scope/expiry, page count |
|
| Theme catalog (AST from disk, mtime cache). |
|
| Page list (slug ascending) |
|
| outline: section/slot tree (id, type, short text); full: draftData |
|
| Validates without saving; returns |
|
| Creates a draft; Header/Footer are copied from shared components in the |
|
| GET → apply operations → validate → PUT (optimistic lock with |
|
| Soft delete — user confirmation required |
|
| 1-hour draft preview links (storefront + local) |
Results are returned as content[0].text (JSON) + structuredContent; errors carry
field/path info with isError: true (so the agent can fix them).
update_page operations
append_section{section} (before the Footer), insert_section{section, before?|after?} (if no anchor, appends like before the Footer),
replace_section{id, section}, remove_section{id}, move_section{id, before?|after?},
set_props{id, props} (shallow merge), set_slot{id, slot, children} (replaces the slot entirely; new children are built first, old content is kept on failure),
set_root_props{props}.
Behavior notes:
Shared components are read-only — including their child nodes. A node carrying
sharedComponentId(Header/Footer) and all its descendants under its zones (Logo, NavLink, FooterColumn…) cannot be modified withset_props/set_slot/replace_section/remove_section; a "shared component — edit from the panel editor" error is returned. The shared root itself can be removed from the page withremove_section(with a warning; the master is not affected). These nodes are markedshared: truein theget_pageoutline.Error / warning distinction (operations mode): The document from GET is first normalized (inline slot arrays left in props → zones;
SharedComponentRefnodes whose master was deleted are dropped with a warning — the backend does the same on PUT). Nodes added/changed by the agent in this round are strictly validated (unknown type, allow violation, element-at-root → error); violations in pre-existing, untouched nodes are only warnings — an unrelated update is not blocked just because the theme changed. Indocumentmode and increate_page/validate_document, all nodes are strictly validated.Empty
operations: [](if there is no meta either) → "no operations to apply" error; no PUT is sent. If onlymetais given,draftDatais not sent (status does not go published→changed, no unnecessary revision is opened); thesavedDraftfield in the response indicates this.Backend save warnings (in the envelope root
warnings: [{code,path,message}], e.g. dropping a Header link whose master was deleted) are returned in thecreate_page/update_pageresponse asserver: [code] path: messagelines.
Authoring format
The agent writes a section tree, not document JSON; id generation, defaultProps merging, slot → zone conversion, and multilingual shortcuts are done on the server.
{
"type": "FeaturesSection",
"props": { "columns": "3", "background": "dark" },
"variant": "dark", // bileşenin variants anahtarı (varsa)
"slots": {
"contentSlot": [
{ "type": "Title", "props": { "text": { "tr": "Neden biz?", "en": "Why us?" }, "size": "lg" } }
],
"itemsSlot": [
{ "type": "Card", "props": { "href": "/hakkimizda" },
"slots": { "contentSlot": [ { "type": "Paragraph", "props": { "text": "<p>Hızlı teslimat</p>" } } ] } }
]
}
}Conversion rules:
If
typeis not in the catalog → error;elementcategory at the root → error; slot child outsideallow→ error.props=defaultProps(−id, −inline slot children) ←variants[variant].props(+_variant) ← userprops.If
slots[slot]is given, use it; if not, the sample children from defaultProps; if[]is given, empty. All are written tozones["<id>:<slot>"], andprops[slot] = [].Multilingual shortcuts:
"text"→[{code: defaultLanguage, value}];{tr, en}→[{code,value}]; missing language is a warning.link:"/path"→[{code, value:{url, target:"_self"}}].upload: URL string → external file record.If a
select/radiovalue is outsideoptions→ error. Keys prefixed with_→ error (classNameis free).id: 8 characters
[A-Za-z0-9_-], unique across the document (a valid and uniqueprops.idis accepted if provided).
Development
npm install
npm run build # tsc → dist/ (+ dist/bin.js +x)
npm test # vitest (parser, build, validate, operations, api mock, config, uçtan uca MCP)
node scripts/smoke.mjs # dist/bin.js'i stdio ile ayağa kaldırıp initialize + tools/list doğrularTests do not make requests to a real backend (fetch mock); the theme catalog is read from
the copied components under test/fixtures/theme.
Programmatic use (HTTP transport, etc.):
import { buildServer, ServerContext, loadConfig } from "@tecof/mcp";
const ctx = new ServerContext({ config: loadConfig() });
const server = buildServer({ ctx }); // McpServer — istediğiniz transport'a bağlayınAvailable Tools
9 toolscreate_pageSayfa oluştur (taslak)A
Yazarlık biçimindeki bölümlerden yeni bir TASLAK sayfa oluşturur. Header/Footer, layoutFrom sayfasındaki ortak bileşenlerden otomatik kopyalanır (varsayılan: home) — bunları sections içinde vermeyin. Önce list_components (full) ile alanları doğrulayın; dryRun:true ile kaydetmeden deneyin.
Inputs: slug (required), title (required), sections (required), meta, +2 more.
delete_pageSayfayı silADestructiveIdempotent
Sayfayı siler (soft delete; panelden geri alınabilir). Kullanıcı onayı olmadan ÇAĞIRMAYIN — confirm:true kullanıcının açık onayını temsil eder. Şablon sayfalar silinemez.
Inputs: page (required), confirm (required).
get_pageSayfayı getirARead-onlyIdempotent
Bir sayfanın taslağını döner. mode=outline (varsayılan): bölümler ve slot çocukları id/type/kısa metinle — update_page için id'leri buradan alın. mode=full: tam draftData JSON.
Inputs: page (required), mode.
get_preview_urlÖnizleme URL'si alARead-only
Sayfanın TASLAK hâli için 1 saat geçerli önizleme bağlantıları: yayındaki domain (storefront) ve yerel geliştirme (TECOF_LOCAL_URL). Yayınlama panelden yapılır.
Inputs: page (required), locale.
get_site_contextSite bağlamını getirARead-onlyIdempotent
Mağaza (diller, varsayılan dil), aktif tema (themeId/merchantThemeId/domain), API anahtarının kapsamı ve bitişi, sayfa sayısı. Diğer araçlardan önce çağırın.
Inputs: no named parameters.
list_componentsTema bileşenlerini listeleARead-onlyIdempotent
Tema reposundaki section ve element bileşenlerini diskten okur. summary: ad, label, kategori, slot adları. full: alanlar (tip, seçenekler, slot allow listesi), defaultProps, variants. Bölüm yazmadan önce full ile alan adlarını doğrulayın.
Inputs: detail, category, component.
list_pagesSayfaları listeleARead-onlyIdempotent
Aktif temadaki sayfaları listeler (id, slug, başlık, durum: draft/published/changed, tarihler).
Inputs: includeTemplates.
update_pageSayfayı güncelle (taslak)A
Sayfa taslağını günceller. Ya operations (append/insert/replace/remove/move_section, set_props, set_slot, set_root_props — id'ler get_page outline'dan; append_section ve anchor'sız insert_section yeni bölümü Footer'ın ÖNÜNE koyar) ya da document (tam doküman) verin; meta ile başlık/slug/meta alanları (yalnız meta verilirse draftData'ya dokunulmaz). Ortak bileşenler (Header/Footer) ve onların ALT düğümleri değiştirilemez. dryRun:true kaydetmez.
Inputs: page (required), meta, dryRun, document, +1 more.
validate_documentDokümanı doğrulaARead-onlyIdempotent
Kaydetmeden doğrular. Ya sections (yazarlık biçimi: type/props/variant/slots) ya da document (tam {root,content,zones}) verin. Hatalar yol + açıklama ile döner; ok=true ise normalizedDocument kaydedilebilir haldedir.
Inputs: document, sections.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct resource/action: context, component listing, page listing, page detail, validation, page create/update/delete, and preview. There is no meaningful overlap; validate_document is clearly separate from create/update dryRun as a standalone check.
All tools use a consistent snake_case verb_noun pattern: get_site_context, list_components, list_pages, get_page, validate_document, create_page, update_page, delete_page, get_preview_url. No camelCase or mixed verb styles appear.
Nine tools is well-scoped for a page-management server: context, component introspecton, page CRUD, validation, and preview. Each tool serves a clear purpose without redundancy.
The tool set covers the page draft lifecycle well: create, read, list, update, delete, validate, and preview. It is slightly incomplete for the full page lifecycle because publishing is intentionally left to the panel, so an agent cannot publish or unpublish a page through the server.
Related MCP Connectors
MCP server for managing FormDesigner forms, fields, logic rules, themes, and entries
Read-only MCP server over the developer docs for the portfolio's JSON API, MCP, A2A and NLWeb.
An MCP server that provides access to Agility CMS. See https://mcp.agilitycms.com for more details.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for generating AntiCMS v3 JSON component templates with validation and field type support.11 npmMIT
- AlicenseAqualityBmaintenanceMCP server that lets agents edit real Microsoft Word (.docx) documents - tracked changes, tables, styles, comments, content controls, and document properties - with every edit validated and previewed before saving. Built on the Open XML SDK (no Word automation); reads and writes documents in place through filesystem or SharePoint storage.1628MIT

kiubi-local-mcpofficial
AlicenseNot gradedqualityCmaintenanceLocal MCP server for Kiubi graphic theme integration, exposing tools for documentation, theme introspection, and static file validation to AI agents like Claude and Cursor.16 npm1ISC
user-majico-mcpofficial
AlicenseNot gradedqualityCmaintenanceMCP server for Majico.xyz that enables coding agents to read (and limited write) brand guidelines, design tokens, studio canvas, and export manifests.9 npmMIT