@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）。

缺少 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: anticms-mcp

工具

结果以 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