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

  • 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)。

変数

必須

説明

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

いいえ

テーマリポジトリが別のディレクトリにある場合

トークン/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ı 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

ツール

Tool

入力

動作

get_site_context

—

ストア、言語、テーマ (themeId/merchantThemeId/domain)、トークンのスコープ/期限、ページ数

list_components

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

テーマカタログ (ディスクから AST、mtime キャッシュ)。full: フィールド、オプション、スロット allow、defaultProps、variants

list_pages

includeTemplates?

ページ一覧 (slug 昇順)

get_page

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

outline: セクション/スロットツリー (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} (スロットを完全に置き換え。先に新しい子を構築し、失敗した場合は古い内容を保持)、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>" } } ] } }
    ]
  }
}

変換ルール:

  1. type がカタログにない場合はエラー。ルートでの element カテゴリはエラー。スロットの子が allow 外の場合はエラー。

  2. props = defaultProps (−id、−インラインスロットの子) ← variants[variant].props (+_variant) ← ユーザーの props。

  3. slots[slot] が指定されていればそれを使用。指定がなければ defaultProps 内のサンプルの子を使用。[] なら空。すべて zones["<id>:<slot>"] に書き込まれ、props[slot] = [] になります。

  4. 多言語ショートカット: "metin" → [{code: varsayılanDil, value}]; {tr, en} → [{code,value}]。言語が不足している場合は警告。link: "/yol" → [{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

テストは実際の 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ı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