Skip to main content
Glama
tecof-mcp
by tecof

@tecof/mcp

面向 Tecof Developer API v1 的 stdio MCP 服务器。在 Tecof 主题仓库内运行; 从磁盘(AST)读取主题组件,将代理编写的简单"区块"定义转换为编辑器文档, 并通过 Developer API 创建/更新草稿页面。发布始终在面板中完成(API 中没有 publish)。

  • SDK:@modelcontextprotocol/server@^2(+ zod@^4)— McpServer + serveStdio

  • Node ≥ 20,ESM

  • 支持工具注解(readOnlyHint、destructiveHint)和 _meta["anthropic/requiresUserInteraction"](删除)

安装

在主题仓库根目录:

# 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_...' >> .env

服务器通过 npx 运行,无需全局安装:

npx -y @tecof/mcp@latest

环境变量

按 TECOF_PROJECT_DIR → CLAUDE_PROJECT_DIR → process.cwd() 的顺序查找项目目录; .env 和 .env.local 从此处读取。不会覆盖 process.env — 文件中的值仅填充 为空的键(.env.local > .env)。

变量

必填

说明

TECOF_API_TOKEN

是

tcf_… 个人访问令牌

TECOF_API_URL

是*

后端地址;若缺失则使用 NEXT_PUBLIC_BASE_URL

TECOF_THEME_ID

否

全局主题 id;若缺失则使用 NEXT_PUBLIC_THEME_ID,再缺失则用店铺当前主题

TECOF_LOCAL_URL

否

本地预览根地址(默认 http://localhost:3000)

TECOF_PROJECT_DIR

否

主题仓库位于其他目录时使用

缺少 token/URL 时服务器仍会启动;list_components 和 validate_document 可正常工作,页面相关工具会返回带指引的错误。日志仅写入 stderr; 未捕获的错误也落入 stderr,进程不会崩溃。

安全:TECOF_API_URL 必须为 https。若提供 http://(非 loopback)地址, 启动时会在 stderr 打印警告,并在每个工具错误中附加相同提示;http→https 重定向不会被跟随(Node fetch 在重定向时会丢弃 Authorization,导致误导性的 401)— 3xx 响应会被转换为"TECOF_API_URL 协议/主机错误"。请求超时(30 秒)涵盖 header 和 body 读取的整个过程。

Claude Code — .mcp.json

{
  "mcpServers": {
    "tecof": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "${TECOF_MCP_PACKAGE:-@tecof/mcp@latest}"]
    }
  }
}

TECOF_MCP_PACKAGE 环境变量可覆盖包 spec — 在发布到 npm 之前或本地 开发时,可指向本仓库文件夹(npx -y /path/to/tecof-mcp 会运行文件夹中的 bin):

export TECOF_MCP_PACKAGE=/Users/<siz>/Desktop/Tecof/tecof-mcp   # claude'u bu shell'den başlatın

发布(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ı hesap

Codex — .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"]
    }
  }
}

令牌不会写入任何配置文件;保留在 .env 中。客户端进程在主题 仓库根目录启动,服务器从那里读取 .env。

Related MCP server: officeagent-net

工具

工具

输入

功能

get_site_context

—

店铺、语言、主题(themeId/merchantThemeId/domain)、令牌作用域/过期时间、页面数量

list_components

category?、component?、detail?: summary|full

主题目录(从磁盘读取 AST,mtime 缓存)。full:字段、选项、slot allow、defaultProps、variants

list_pages

includeTemplates?

页面列表(slug 升序)

get_page

page(id|slug)、mode?: outline|full

outline:区块/slot 树(id、type、简短文本);full:draftData

validate_document

{ sections } 或 { document }

不保存即验证;返回 ok、errors、warnings、normalizedDocument

create_page

slug、title、sections、meta?、layoutFrom?、dryRun?

创建草稿;Header/Footer 从 layoutFrom 页面(默认 home)的公共组件复制

update_page

page、operations 或 document、meta?、dryRun?

GET → 应用操作 → 验证 → PUT(使用 expectedModifiedDate 乐观锁;409 时返回明确消息)

delete_page

page、confirm: true

软删除 — 必须经用户确认

get_preview_url

page、locale?

1 小时有效的草稿预览链接(storefront + 本地)

结果以 content[0].text(JSON)+ structuredContent 返回;错误以 isError: true 携带字段/路径信息(便于代理修正)。

update_page 操作

append_section{section}(插入到 Footer 之前)、insert_section{section, before?|after?}(无锚点时如同 append 一样插入到 Footer 之前)、 replace_section{id, section}、remove_section{id}、move_section{id, before?|after?}、 set_props{id, props}(浅合并)、set_slot{id, slot, children}(完全替换 slot;先构建新子节点,失败则保留旧内容)、 set_root_props{props}。

行为说明:

  • 公共组件只读 — 包括其子节点。 带有 sharedComponentId 的节点(Header/Footer)及其 zones 下的所有后代(Logo、NavLink、FooterColumn…)不能通过 set_props/set_slot/replace_section/remove_section 修改;会返回"公共组件 — 请在面板编辑器中编辑"错误。公共根节点本身可以通过 remove_section 从页面中移除(带警告;不影响 master)。get_page 的 outline 中这些节点标记为 shared: true。

  • 错误/警告区分(operations 模式): 从 GET 获取的文档先进行规范化(props 中残留的内联 slot 数组 → zones;master 已被删除的 SharedComponentRef 节点带警告丢弃 — 后端 PUT 时执行相同操作)。代理本轮新增/修改的节点进行严格校验(未知 type、allow 违规、element-at-root → 错误);先前已存在、未被触碰的节点上的违规仅为警告 — 不会因为主题已变更而锁死无关的更新。在 document 模式以及 create_page/validate_document 中,所有节点均严格校验。

  • 空 operations: [](且无 meta)→ 返回"没有可应用的操作"错误;不发起 PUT。仅提供 meta 时不发送 draftData(状态不会从 published 变为 changed,不会打开不必要的修订);响应中的 savedDraft 字段会表明这一点。

  • 后端的保存警告(信封根部的 warnings: [{code,path,message}],例如丢弃 master 已被删除的 Header 关联)在 create_page/update_page 响应中以 服务器: [code] path: message 行返回。

编写格式

代理编写的是区块树而非文档 JSON;id 生成、defaultProps 合并、slot → zone 转换以及多语言快捷方式均在服务器端完成。

{
  "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>" } } ] } }
    ]
  }
}

转换规则:

  1. type 不在目录中则报错;根级 element 类别报错;slot 子节点不在 allow 内报错。

  2. props = defaultProps(−id、−内联 slot 子节点)← variants[variant].props(+_variant)← 用户 props。

  3. 若提供了 slots[slot] 则使用;未提供则使用 defaultProps 中的示例子节点;提供 [] 则为空。全部写入 zones["<id>:<slot>"],props[slot] = []。

  4. 多语言快捷方式:"文本" → [{code: 默认语言, value}];{tr, en} → [{code,value}];缺少语言警告。link:"/路径" → [{code, value:{url, target:"_self"}}]。upload:URL 字符串 → 外部文件记录。

  5. select/radio 值不在 options 中则报错。_ 前缀的键报错(className 自由)。

  6. id:8 个字符 [A-Za-z0-9_-],在整个文档中唯一(若提供了有效且唯一的 props.id 则接受)。

开发

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ğrular

测试不会向真实后端发起请求(fetch mock);主题目录从 test/fixtures/theme 下的副本组件读取。

程序化使用(HTTP transport 等):

import { buildServer, ServerContext, loadConfig } from "@tecof/mcp";
const ctx = new ServerContext({ config: loadConfig() });
const server = buildServer({ ctx }); // McpServer — istediğiniz transport'a bağlayın

Available Tools

9 tools
create_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ı silA
DestructiveIdempotent

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ı getirA
Read-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 alA
Read-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ı getirA
Read-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 listeleA
Read-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ı listeleA
Read-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ğrulaA
Read-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

    A4.4/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      16
      28
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local 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 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Majico.xyz that enables coding agents to read (and limited write) brand guidelines, design tokens, studio canvas, and export manifests.
      9 npm
      MIT