@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 annotations(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).

토큰/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초)는 헤더 + 본문 읽기 전체를 포함합니다.

Claude Code — .mcp.json

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

TECOF_MCP_PACKAGE env는 패키지 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?}(anchor가 없으면 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는 전송되지 않습니다(status 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