every-app/open-seo 딥다이브
— Semrush·Ahrefs를 대체하는 오픈소스 SEO 분석 플랫폼

┌─────────────────────────────────────────────────────────────────┐ │ 사용자 / AI 에이전트 │ └───────────────┬──────────────────────────────┬──────────────────┘ │ 브라우저 (React UI) │ MCP 클라이언트 │ │ (Claude Code, Hermes...) ▼ ▼ ┌───────────────────────────────────────────────────────────────┐ │ Cloudflare Workers (엣지 런타임 / workerd) │ │ │ │ ┌──────────────────┐ ┌──────────────────────────────┐ │ │ │ TanStack Start │ │ MCP Server (OAuth 2.0) │ │ │ │ (SSR + API) │ │ ┌────────────────────────┐ │ │ │ │ │ │ │ 18개 MCP 툴: │ │ │ │ │ /routes/_app │ │ │ research_keywords │ │ │ │ │ /routes/_project│ │ │ get_domain_overview │ │ │ │ │ /routes/api │ │ │ get_backlinks_overview │ │ │ │ └─────────┬────────┘ │ │ get_rank_tracker │ │ │ │ │ │ │ get_serp_results │ │ │ │ ┌─────────▼────────┐ │ │ find_serp_competitors │ │ │ │ │ Better Auth │ │ │ search_console_tools... │ │ │ │ │ (인증 미들웨어) │ │ └────────────┬───────────┘ │ │ │ └─────────┬────────┘ └───────────────┼──────────────┘ │ │ │ │ │ │ ┌─────────▼─────────────────────────────▼──────────────┐ │ │ │ Drizzle ORM + D1 바인딩 │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Cloudflare Workflows (장기 비동기 — 사이트 오디트) │ │ │ │ Cloudflare Durable Objects (채팅 에이전트 상태) │ │ │ └─────────────────────────────────────────────────────┘ │ └───────┬─────────────────────────────────────────────────┬────┘ │ D1 (SQLite) │ KV / R2 ▼ ▼ ┌──────────────┐ ┌───────────────────────────────────────────┐ │ Cloudflare │ │ 외부 API │ │ D1 Database │ │ DataForSEO (SERP / Keywords / Backlinks │ │ (26개 테이블) │ │ / Lighthouse) + Google Search Console │ └──────────────┘ └───────────────────────────────────────────┘

AUTH_MODE=local_noauth ← Docker 로컬 사용 (인증 없음, admin@localhost 자동 주입) AUTH_MODE=cloudflare_access ← Cloudflare Access JWT 검증 (팀/인터넷 공개용) AUTH_MODE=hosted ← Better Auth 이메일/비번 + 조직 관리 (SaaS 모드)

AI 에이전트 (Claude Code 등) │ │ 1. MCP 클라이언트 등록 요청 ▼ Cloudflare Workers OAuth Provider (OAUTH_KV에 등록 정보 저장) │ │ 2. 사용자 OAuth 동의 화면 표시 ▼ 사용자 브라우저 → 승인 │ │ 3. Access Token 발급 (KV 저장) ▼ 에이전트 → MCP 툴 호출 (Authorization: Bearer ...) │ │ 4. 프로젝트 권한 검증 (D1 DB 조회) ▼ DataForSEO API 호출 → 결과 반환

사용자 → 오디트 시작 요청 │ ▼ Workers API → Workflow 인스턴스 생성 (workflowInstanceId 저장) │ ▼ Cloudflare Workflows (장기 실행 허용, 재시도·체크포인트 지원) ├── Phase 1: 크롤링 (cheerio + robots-parser + tldts) │ 각 페이지: 상태코드·타이틀·메타·h1~h6·이미지·링크 수집 │ → auditPages 테이블에 저장 │ └── Phase 2: Lighthouse (DataForSEO Lighthouse API) 모바일+데스크탑 각각 측정 → auditLighthouseResults 테이블 + R2 전체 JSON

open-seo/ ├── .agents/skills/ ← AI 에이전트용 스킬 7개 (마크다운) │ ├── keyword-research/SKILL.md 키워드 리서치 워크플로 │ ├── competitor-analysis/ 경쟁사 분석 │ ├── competitive-landscape/ 업계 전체 경쟁 지형 │ ├── keyword-clustering/ 키워드 군집화 │ ├── link-prospecting/ 링크 빌딩 후보 발굴 │ ├── seo-coach/ SEO 전략 코치 │ └── seo-project-setup/ 프로젝트 초기 설정 │ ├── .claude/skills/ ← Claude Code 전용 스킬 │ ├── merge-ready/ PR 머지 전 체크리스트 │ └── openseo-release-notes/ 릴리스 노트 생성 │ ├── src/ │ ├── routes/ ← TanStack Start 파일 기반 라우팅 │ │ ├── __root.tsx 앱 루트 (전역 레이아웃) │ │ ├── _app/ 인증 불필요 앱 페이지 │ │ │ ├── ai.tsx AI & Agents 설정 페이지 │ │ │ ├── billing.tsx 결제 페이지 │ │ │ ├── projects.tsx 프로젝트 목록 │ │ │ └── settings.tsx 계정 설정 │ │ ├── _project/p/$projectId/ 프로젝트별 SEO 기능 페이지 │ │ │ ├── domain.tsx 도메인 오버뷰 │ │ │ ├── keywords.tsx 키워드 리서치 │ │ │ ├── backlinks.tsx 백링크 분석 │ │ │ ├── rank-tracking/ 순위 추적 │ │ │ ├── audit.tsx 사이트 오디트 │ │ │ ├── brand-lookup.tsx 브랜드 검색 (AI Visibility) │ │ │ ├── saved.tsx 저장된 키워드 │ │ │ └── prompt-explorer.tsx AI 프롬프트 탐색기 │ │ └── api/ REST/RPC API 엔드포인트 │ │ │ ├── server/ │ │ ├── mcp/ ← MCP 서버 구현체 │ │ │ ├── server.ts 18개 MCP 툴 등록 │ │ │ ├── transport.ts HTTP SSE 트랜스포트 │ │ │ ├── oauth-provider.ts OAuth 2.0 프로바이더 │ │ │ ├── tools/ 개별 툴 구현 │ │ │ │ ├── research-keywords.ts │ │ │ │ ├── get-domain-overview.ts │ │ │ │ ├── get-backlinks-overview.ts │ │ │ │ ├── dataforseo-research-tools.ts ← 6개 툴 (SERP·로컬 등) │ │ │ │ └── search-console-tools.ts │ │ │ └── formatters.ts MCP 응답 포매터 │ │ └── workflows/ ← Cloudflare Workflows (사이트 오디트) │ │ │ ├── db/ ← 데이터베이스 스키마 │ │ ├── app.schema.ts 핵심 테이블 (projects, keywords, audits...) │ │ ├── better-auth-schema.ts 인증 관련 테이블 │ │ ├── billing.schema.ts 결제 관련 │ │ └── gsc.schema.ts Google Search Console 토큰 │ │ │ ├── client/ ← 클라이언트 전용 코드 │ │ ├── components/ 공통 UI 컴포넌트 │ │ ├── hooks/ 검색 히스토리 등 커스텀 훅 │ │ └── lib/ CSV 내보내기, 클립보드, 에러 메시지 │ │ │ └── lib/ ← 공통 유틸 (auth, 에러 처리) │ ├── drizzle/ ← DB 마이그레이션 파일 (0000~0025.sql) ├── docs/ ← 셀프호스팅·GSC 설정 가이드 ├── Dockerfile.selfhost Docker 셀프호스팅용 ├── compose.yaml Docker Compose └── wrangler.json Cloudflare Workers 설정

# 1. 레포 클론
git clone https://github.com/every-app/open-seo.git
cd open-seo

# 2. 환경 변수 파일 복사
cp .env.example .env

# 3. DataForSEO API 키 설정 (.env 편집)
# DATAFORSEO_API_KEY=your_base64_encoded_login:password

# 4. 컨테이너 시작
docker compose up -d

# 5. 브라우저에서 접속
open http://localhost:3001

# Wrangler 로그인
npx wrangler login

# D1 DB 마이그레이션 (프로덕션)
pnpm run db:migrate:prod

# 빌드 & 배포
pnpm run deploy

# 또는 GitHub 리포지토리의 "Deploy to Cloudflare" 버튼 클릭

# 의존성 설치
pnpm install

# .env.local 파일 생성 후 DataForSEO 키 설정
cp .env.example .env.local

# D1 로컬 마이그레이션 (Wrangler 로컬 SQLite 사용)
pnpm run db:migrate:local

# 개발 서버 시작
pnpm run dev

# 테스트 실행
pnpm test          # 유닛 테스트
pnpm test:e2e      # E2E 테스트 (Playwright)