tecof-mcp
Official@tecof/mcp
Tecof Developer API v1 用の stdio MCP サーバー です。Tecof テーマリポジトリ内から動作し、テーマコンポーネントをディスクから (AST として) 読み取り、エージェントが記述したシンプルな「セクション」定義をエディタドキュメントに変換し、Developer API で 下書き ページを作成・更新します。公開は常にパネルから行います (API に publish はありません)。
SDK:
@modelcontextprotocol/server@^2(+zod@^4) —McpServer+serveStdioNode ≥ 20, ESM
Tool アノテーション (
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)。
変数 | 必須 | 説明 |
| はい |
|
| はい* | バックエンドのアドレス。未設定の場合は |
| いいえ | グローバルテーマ ID。未設定の場合は |
| いいえ | ローカルプレビューのルート (デフォルト |
| いいえ | テーマリポジトリが別のディレクトリにある場合 |
トークン/URL が不足していてもサーバーは起動します。list_components と validate_document は動作し、ページツールは案内を示すエラーを返します。ログは stderr にのみ出力されます。捕捉されなかったエラーも stderr に出力され、プロセスはクラッシュしません。
セキュリティ: TECOF_API_URL は https である必要があります。http:// (ループバック以外) のアドレスが指定された場合、起動時に stderr へ警告が出力され、各ツールのエラーにも同じヒントが追加されます。http→https リダイレクトは追跡されません (Node の fetch はリダイレクト時に Authorization を落とすため、誤解を招く 401 が発生しました) — 3xx 応答は「TECOF_API_URL のスキーム/ホストが不正」エラーに変換されます。リクエストのタイムアウト (30 秒) はヘッダーとボディの読み取り全体を対象とします。
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ı 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"]
}
}
}トークンはどの設定ファイルにも書き込まれません。.env 内に残ります。クライアントプロセスがテーマリポジトリのルートで起動し、サーバーはそこから .env を読み取ります。
Related MCP server: officeagent-net
ツール
Tool | 入力 | 動作 |
| — | ストア、言語、テーマ (themeId/merchantThemeId/domain)、トークンのスコープ/期限、ページ数 |
|
| テーマカタログ (ディスクから AST、mtime キャッシュ)。 |
|
| ページ一覧 (slug 昇順) |
|
| outline: セクション/スロットツリー (id、type、短いテキスト)。full: draftData |
|
| 保存せずに検証します。 |
|
| 下書きを作成します。Header/Footer は |
|
| GET → 操作を適用 → 検証 → PUT ( |
|
| ソフト削除 — ユーザー確認必須 |
|
| 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} (スロットを完全に置き換え。先に新しい子を構築し、失敗した場合は古い内容を保持)、set_root_props{props}。
動作メモ:
共通コンポーネントは読み取り専用 — 子ノードも含む。
sharedComponentIdを持つノード (Header/Footer) と、その zones 以下のすべての孫ノード (Logo、NavLink、FooterColumn…) はset_props/set_slot/replace_section/remove_sectionでは変更できません。「共通コンポーネント — パネルエディターで編集してください」というエラーが返ります。共通ルート自体はremove_sectionでページから削除できます (警告付き。マスターには影響しません)。get_pageの outline では、これらのノードはshared: trueでマークされます。エラー / 警告の区別 (operations モード): GET から取得したドキュメントはまず正規化されます (props に残ったインラインスロット配列 → zones。マスターが削除された
SharedComponentRefノードは警告付きで除去 — backend の PUT でも同じ処理を行います)。エージェントがこのターンで追加/変更したノードは厳密に検証されます (不明な type、allow 違反、element-at-root → エラー)。以前から存在し、触っていないノードの違反は警告のみです — テーマが変わったからといって無関係な更新がブロックされることはありません。documentモードとcreate_page/validate_documentでは、すべてのノードが厳密に検証されます。空の
operations: [](meta もない場合) → 「適用する操作がありません」エラー。PUT は実行されません。metaのみが指定された場合はdraftDataが送信されません (status が published→changed にならず、不要なリビジョンも作られません)。レスポンスのsavedDraftフィールドがこれを示します。Backend の保存時警告 (エンベロープルートの
warnings: [{code,path,message}]、例: マスターが削除された Header リンクの除去) は、create_page/update_pageのレスポンスでsunucu: [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>" } } ] } }
]
}
}変換ルール:
typeがカタログにない場合はエラー。ルートでのelementカテゴリはエラー。スロットの子がallow外の場合はエラー。props=defaultProps(−id、−インラインスロットの子) ←variants[variant].props(+_variant) ← ユーザーのprops。slots[slot]が指定されていればそれを使用。指定がなければ defaultProps 内のサンプルの子を使用。[]なら空。すべてzones["<id>:<slot>"]に書き込まれ、props[slot] = []になります。多言語ショートカット:
"metin"→[{code: varsayılanDil, value}];{tr, en}→[{code,value}]。言語が不足している場合は警告。link:"/yol"→[{code, value:{url, target:"_self"}}]。upload: URL 文字列 → 外部ファイルレコード。select/radioの値がoptions以外ならエラー。_プレフィックスのキーはエラー (classNameは自由)。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テストは実際の backend にリクエストを送りません (fetch をモック)。テーマカタログは 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ı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.
Maintenance
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.
Create, edit, preview, publish, and manage web pages from MCP-capable AI clients.
An MCP server that provides access to Agility CMS. See https://mcp.agilitycms.com for more details.
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