damonzucconi-mcp

damonzucconi.com을 GraphQL API를 통해 관리하기 위한 원격 MCP 서버입니다.

프로덕션 엔드포인트: https://damonzucconi-mcp.damonzucconi.workers.dev/mcp

서버는 스토리지 바인딩이 없는 단일 무상태 Cloudflare Worker입니다. 정적 베어러 토큰이 MCP 엔드포인트를 보호합니다. Worker는 기존 관리자 자격 증명으로 GraphQL API에 로그인하고, 결과 JWT를 만료 직전까지 캐시합니다.

작품, 전시, 태그, 중첩 엔티티, 정렬을 위한 도구를 제공합니다. 작품 및 전시 삭제는 의도적으로 제공되지 않으므로 수동으로 수행하세요.

로컬 개발

Node.js 20+ 및 npm이 필요합니다.

npm install
cp .dev.vars.example .dev.vars

.dev.vars에 세 가지 시크릿을 설정하세요:

openssl rand -hex 32

MCP_AUTH_TOKEN=<paste-generated-value>
ADMIN_USERNAME=your-api-admin-username
ADMIN_PASSWORD=your-api-admin-password

MCP_AUTH_TOKEN은 공유 시크릿이지 사용자 이름이나 로그인 토큰이 아닙니다. Worker는 하나의 사본을 저장하고 각 MCP 클라이언트는 동일한 값을 베어러 토큰으로 보냅니다. 이 값을 소유하면 서버에 접근할 수 있습니다.

자동 동기화는 없습니다:

• .dev.vars는 로컬 Worker에 값을 제공하며 npm run secrets:push가 사용하는 원본입니다.

• npm run secrets:push는 해당 값을 프로덕션용 Cloudflare 암호화 Worker 시크릿에 복사합니다.

• Cursor와 ChatGPT는 클라이언트 측 환경 변수 DAMONZUCCONI_MCP_TOKEN에서 동일한 값을 읽습니다.

MCP_AUTH_TOKEN을 변경한 경우 npm run secrets:push를 실행하고 DAMONZUCCONI_MCP_TOKEN을 업데이트한 다음 클라이언트를 다시 시작하세요. 다른 값을 사용하는 클라이언트는 401 Unauthorized를 받게 됩니다.

npm run codegen
npm run typecheck
npm run dev

로컬 MCP 엔드포인트는 http://127.0.0.1:8787/mcp입니다. 다른 터미널에서:

npm run smoke

대신 프로덕션을 테스트하려면:

MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

Cursor에서 연결

이 프로젝트의 .cursor/mcp.json 또는 전역 ~/.cursor/mcp.json에 다음을 추가하세요:

{
  "mcpServers": {
    "damonzucconi": {
      "url": "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DAMONZUCCONI_MCP_TOKEN}"
      }
    }
  }
}

Cursor가 상속하는 환경에 DAMONZUCCONI_MCP_TOKEN을 .dev.vars의 MCP_AUTH_TOKEN과 동일한 값으로 설정한 다음 Cursor를 다시 시작하세요. 원격 서버는 envFile을 지원하지 않습니다.

ChatGPT 데스크톱에서 연결

ChatGPT 데스크톱 앱은 ~/.codex/config.toml에서 Codex와 MCP 구성을 공유합니다. 다음을 추가하세요:

[mcp_servers.damonzucconi]
url = "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp"
bearer_token_env_var = "DAMONZUCCONI_MCP_TOKEN"
default_tools_approval_mode = "writes"

macOS에서 Finder나 Dock에서 실행되는 앱이 토큰을 사용할 수 있게 하려면:

read -s "DAMONZUCCONI_MCP_TOKEN?MCP token: "
echo
launchctl setenv DAMONZUCCONI_MCP_TOKEN "$DAMONZUCCONI_MCP_TOKEN"
unset DAMONZUCCONI_MCP_TOKEN

read가 요청하면 MCP_AUTH_TOKEN과 동일한 값을 붙여넣으세요. 토큰은 config.toml이나 셸 히스토리에 기록되지 않습니다.

ChatGPT를 완전히 종료하고 다시 연 다음 Settings → MCP servers를 열고 Restart를 선택하세요. 컴포저에서 /mcp를 입력하여 damonzucconi가 연결되었는지 확인하세요. 데스크톱 UI가 변경된 경우 OpenAI의 MCP 문서를 참조하세요.

배포

Wrangler 인증은 브라우저를 엽니다:

npx wrangler login

첫 배포의 경우:

npm run deploy
npm run secrets:push

secrets:push는 .dev.vars의 세 항목을 업로드합니다. 이후 배포에서는 시크릿이 변경되지 않았다면 npm run deploy만 실행하세요.

변경 사항을 배포하기 전에:

npm run codegen
npm run typecheck
npm run smoke
npm run deploy
MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

GraphQL 코드 생성

쿼리와 뮤테이션은 src/graphql/에 있습니다. npm run codegen은 라이브 API를 인트로스펙션하고 다음을 새로 고칩니다:

• schema.graphql

• src/generated/

생성된 파일은 편집하지 마세요. API 변경 후 코드 생성이나 타입 검사가 실패하면 배포 전에 .graphql 작업 또는 해당 Zod 도구 스키마를 업데이트하세요.