viruagent-mcp

viruagent의 포스팅 기능을 MCP 서버로 노출한 패키지입니다.

CLI 기반 AI Agent가 티스토리 글을 작성·업로드·발행(공개/비공개)까지 한 번에 처리하는 MCP입니다.
OpenAI Function Calling으로 의도를 정하고, MCP/Playwright/Tistory API가 실행을 분리 수행합니다.

• AI Agent: 요청 파라미터 결정

• MCP Tool: publish/save_draft/list_categories 호출 인터페이스

• Playwright: 로그인·2차인증·세션, Tistory API: 발행/임시저장/카테고리/이미지 처리

최근 반영사항

• 2026-02-27: publish에서 403 발생 시 우선 비공개 발행(visibility: 0)으로 fallback 합니다.

• 동일 일시에서 403이 반복되면 비공개 발행도 실패하고, 해당 에러를 반환해 다시 시도/리커버리 제어할 수 있도록 구성했습니다.

Related MCP server: velog-mcp

설치

cd /Users/tk/Desktop/project/viruagent-mcp
npm install

실행

npm start

또는

node bin/index.js

제공 tool

- viruagent_auth_status
- viruagent_login
- viruagent_publish
- viruagent_save_draft
- viruagent_list_categories
- viruagent_list_posts
- viruagent_logout
- viruagent_list_providers

기본 사용 예시 (MCP 클라이언트 설정)

{
  "mcpServers": {
    "viruagent-mcp": {
      "command": "node",
      "args": ["/Users/tk/Desktop/project/viruagent-mcp/bin/index.js"]
    }
  }
}

동작 포인트

• session 파일은 사용자 홈(~/.viruagent-mcp/sessions)에 provider별로 분리 저장됩니다.

• viruagent_login은 기본적으로 브라우저를 띄워 티스토리 로그인 -> 카카오 로그인 페이지 이동 -> 로그인/2차 인증 흐름을 처리합니다.

• viruagent_login은 아이디/비밀번호 자동 로그인을 지원합니다.

• 카카오톡 푸시 2차 인증이 감지되면, 사용자 승인 대기(status: "pending_2fa") 상태를 반환하고 승인 완료 후 재시도할 수 있습니다.

• remember browser(이 브라우저에서 2차 인증 사용 안 함)에 해당하는 체크박스가 보이면 자동 체크를 시도합니다.

• viruagent_publish는 category가 없으면 카테고리 목록을 돌려주고 사용자가 category를 지정해 다시 요청하게 합니다. (카테고리가 하나뿐이면 자동 선택)

• viruagent_publish는 발행 요청 시 403(발행 제한) 오류가 발생하면 visibility: 0(비공개) 발행으로 먼저 fallback를 시도합니다.

• viruagent_publish는 본문 placeholder(<!-- IMAGE: keyword -->)를 발견하면 imageUrls를 받아 원격 URL이면 로컬로 다운로드하고, 로컬 파일 경로면 바로 업로드합니다. 업로드는 Tistory 이미지 업로드 API를 통해 진행됩니다. 성공 시 본문에는 업로드된 이미지 URL이 <img src="..."> 형태로 삽입됩니다. 썸네일은 업로드된 이미지 키(kage@...) 기준으로 자동 후보를 생성합니다.

• viruagent_save_draft도 동일한 이미지 치환 파이프라인을 사용합니다.

• 업로드된 첫 번째 이미지는 썸네일 자동 후보가 됩니다. (thumbnail 직접 지정이 우선)

• thumbnail은 kage@... 형식이 가장 안전합니다. (thumbnail이 비어 있으면 업로드된 첫 이미지의 kage@ 키를 자동 사용)

• relatedImageKeywords는 이미지 수집용 힌트이며, 실제 업로드는 imageUrls가 있을 때만 수행됩니다.

• autoUploadImages와 imageUploadLimit은 placeholder+URL 처리 동작을 제어합니다.

자동 로그인 사용법

1. 환경변수 설정

export TISTORY_USERNAME="your-id"
export TISTORY_PASSWORD="your-password"

2. MCP 도구 호출 예시

{
  "name": "viruagent_login",
  "arguments": {
    "provider": "tistory",
    "headless": true,
    "username": "your-id",
    "password": "your-password"
  }
}

발행 요청 시 카테고리를 생략하면 아래처럼 status: "need_category" 응답이 올 수 있습니다.

{
  "provider": "tistory",
  "mode": "publish",
  "status": "need_category",
  "loggedIn": true,
  "title": "자동 테스트 글",
  "visibility": 0,
  "tags": "테스트",
  "message": "category가 없어서 중단했습니다. 카테고리 ID를 지정해 publish를 재요청해 주세요.",
  "categories": [
    { "name": "기본", "id": 0 }
 ]
}

이미지 업로드 단계에서 실패가 발생하면 아래 상태가 반환됩니다.

• status: "image_upload_failed": 플레이스홀더가 있지만 업로드된 이미지가 0개

• status: "image_upload_partial": 일부 업로드 실패

실패 응답에는 uploadErrors에 실패 URL/에러 메시지가 들어오므로, 동일 title/content로 imageUrls만 보완해서 재요청하세요.

발행이 403으로 막혀 비공개로 fallback된 경우:

{
  "provider": "tistory",
  "mode": "publish",
  "status": "publish_fallback_to_private",
  "visibility": 0,
  "message": "발행 제한(403)으로 인해 비공개로 발행했습니다."
}

발행 403이 비공개 fallback에서도 반복되어 실패한 경우:

{
  "provider": "tistory",
  "mode": "publish",
  "status": "publish_fallback_to_private_failed",
  "visibility": 0,
  "message": "발행 제한(403)으로 인해 공개/비공개 모두 실패했습니다."
}

2차 인증이 있으면 twoFactorCode를 추가로 전달합니다.

• 카카오톡 푸시 방식에서는 twoFactorCode가 없어도 자동으로 2차 인증 승인 대기 후 실패 시 pending_2fa 결과가 반환될 수 있습니다.

viruagent_publish 이미지 자동 업로드 예시:

{
  "name": "viruagent_publish",
  "arguments": {
    "provider": "tistory",
    "title": "최신 IT 뉴스 요약",
    "content": "<blockquote data-ke-style=\"style1\">...</blockquote><!-- IMAGE: galaxy s26 --><p>...</p>",
    "visibility": "public",
    "category": 1284210,
    "tags": "IT,뉴스",
    "relatedImageKeywords": ["galaxy s26", "AI phone"],
    "imageUrls": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
    "autoUploadImages": true,
    "imageUploadLimit": 3
  }
}

pending_2fa 응답 예시:

{
  "provider": "tistory",
  "status": "pending_2fa",
  "loggedIn": false,
  "message": "카카오 2차 인증이 필요합니다. 앱에서 인증 후 다시 실행하면 됩니다."
}

• 현재 Naver provider는 스텁이며, 요청 시 ready:false 형태로 사용 가능 여부를 반환합니다.