flc1125/mote

Mote — Markdown in, URL out

Mote는 Markdown을 불변(immutable), 비열거(non-enumerable), 브라우저에서 읽을 수 있는 온라인 페이지로 게시하고 URL을 반환합니다. 이 스킬은 Mote를 사용해야 하는 시기와 방법만 안내합니다. 게시 프로토콜은 CLI / MCP 구현체에 의해 처리되며, 직접 업로드 로직을 구현하지 마십시오.

사용 시기

다음 의도 중 하나라도 해당되면 Mote를 사용하십시오:

• "이 Markdown / 보고서 / 문서를 공유해 줘" 또는 "웹 페이지 / 링크로 만들어 줘"
• 설계 문서, 조사 자료, 회의록 또는 README를 온라인 링크로 명확히 요청
• 방금 생성한 보고서/분석 결과물을 웹 페이지로 게시해 달라고 요청

Markdown을 읽거나 편집하거나 로컬 브라우저에서 미리보기만 하는 경우에는 Mote에 게시하지 마십시오.

사용하지 마십시오:

• 내용에 비밀번호, API Key, 개인 키 등의 자격 증명 또는 기업 기밀이 포함된 경우 — Mote의 URL이 접근 증명 역할을 하며, 링크를 아는 사람은 누구나 읽을 수 있고 현재 사용자 측 삭제 기능을 제공하지 않습니다.
• 게시된 내용을 수정해야 하는 경우 — Mote 문서는 불변이며, 내용을 변경하려면 새 URL로 다시 게시해야 합니다.

게시 방법

먼저 로컬 이미지 참조 여부를 확인한 후, 설정된 도구에 따라 경로를 선택하십시오. 사용자가 지정한 인스턴스를 존중하며, 이미 자체 호스팅 설정이 있는 경우 공개 인스턴스 https://mote.pub로 강제 전환하지 마십시오.

경로 A: MCP 도구 (mote MCP 서버가 연결된 경우)

• 내용이 대화 중에 있고 로컬 이미지가 없는 경우 → publish_markdown을 호출하고 markdown(선택적으로 name, 예: report.md)을 전달합니다. 로컬 및 원격 이 도구 모두 로컬 이미지를 수집하지 않고 원격 이미지 URL만 유지합니다.
• 로컬 Markdown 파일의 경우 → 로컬 stdio에서만 publish_markdown_file을 제공하며 path를 전달합니다(로컬 이미지는 자동 업로드되고 내용 기준으로 중복 제거됨). 원격에는 publish_markdown만 있으며, 로컬 파일/이미지가 필요한 경우 설정된 CLI를 사용하고 경로를 원격 도구에 전달하지 마십시오.

경로 B: CLI (설치 및 인증이 설정된 경우 사용 가능)

1. 기존 파일이 있으면 그대로 게시합니다. 대화 내용에 로컬 이미지가 없는 경우 임시 파일에 쓸 수 있습니다. 로컬 이미지가 있는 경우, Markdown과 필요한 이미지를 상대 경로 관계를 유지하는 임시 디렉터리에 넣은 후 CLI 또는 로컬 publish_markdown_file을 통해 게시합니다. 이미지는 Markdown 파일이 있는 디렉터리를 기준으로 확인되며, 터미널 작업 디렉터리를 기준으로 하지 않습니다. Markdown만 /tmp로 옮기지 마십시오.
2. 실행:

mote <file.md> --json

3. stdout의 JSON 파싱: { "id": "...", "url": "..." }

CLI는 Markdown 및 지원되는 HTML의 로컬 이미지 참조, 경로 검증, 업로드 및 내용 중복 제거를 자동으로 처리합니다. 원격 이미지는 원래 URL을 유지하며 다운로드되어 패키징되지 않습니다. 이미지만 문서와 함께 업로드되며, 다른 로컬 Markdown 파일을 가리키는 링크는 대상 파일을 자동으로 게시하지 않습니다.

내용 호환성

• 일반 Markdown, 표, 작업 목록, 각주, GitHub 스타일 Alert, 지정된 언어의 코드 하이라이팅을 지원합니다.
• 수식은 TeX 하위 집합을 지원합니다. mermaid 코드 블록은 6가지 정적 차트 하위 집합을 지원하며, 문서당 최대 4개의 다이어그램 렌더링을 시도합니다. 유효하지 않거나 지원되지 않거나 예산을 초과하는 내용은 소스 코드로 표시될 수 있으며, 게시 성공이 모든 확장 구문이 렌더링되었음을 의미하지는 않습니다.
• HTML은 안전한 하위 집합만 허용되며, 스크립트, MDX 또는 대화형 임베드는 실행되지 않습니다. 원시 SVG 업로드 또는 직접 임베드는 지원되지 않습니다. Mote에서 생성된 차트 SVG는 별도로 정리되어 표시될 수 있습니다.
• 복잡한 수식이나 차트를 게시한 후에는 실제 페이지의 수식, 연결선, 레이블 및 이미지를 확인하십시오. 확인하지 않고 렌더링 효과가 검증되었다고 주장하지 마십시오.

자세한 구문이나 제한 사항이 필요하면 호환성 설명 및 온라인 예제를 참조하십시오. 자체 호스팅 인스턴스의 지원 범위는 배포 버전에 따라 다릅니다.

반환된 URL 처리 방법

• URL을 그대로 사용자에게 반환하고, 자르거나 수정하지 마십시오.
• "게시됨: "과 같이 한 문장으로 간단히 설명하십시오.
• 페이지에는 검색 엔진 색인을 금지하는 지시어가 설정되어 있지만, 이는 접근 제어 또는 절대 수집되지 않음을 보장하는 것은 아닙니다. 접근 가능성은 인스턴스와 스토리지가 계속 실행되는지에 따라 달라집니다.
• 사용자가 나중에 "이 페이지 업데이트"를 요청하면: 저장된 Markdown과 업로드된 자산은 불변이며, 다시 게시하면 새 URL이 생성된다고 설명하십시오. Viewer 업데이트로 인해 표시 효과가 변경될 수 있으며, 원격 이미지는 원본 사이트에 의존합니다.

제한 사항 (게시 전 자체 점검)

• Markdown ≤ 2 MiB; 단일 이미지 ≤ 10 MiB; 업로드 자산 ≤ 50개; 전체 패키지 ≤ 20 MiB. 1 MiB = 1,048,576 바이트, CLI는 내용 중복 제거 후 계산하며 원격 이미지는 포함되지 않습니다.
• 이미지 형식: png / jpeg / webp / gif / avif (SVG는 지원하지 않음)
• 제한을 초과하는 경우 어떤 항목이 초과되었는지 사용자에게 정확히 알리고, 자체적으로 내용을 삭제하지 마십시오.

일반적인 오류

• 로그인 만료: 동일한 인스턴스에 대해 대화형 로그인을 완료하도록 사용자 안내, 사용자가 로그인 지원을 명시적으로 요청한 경우 권한 범위 내에서 진행하십시오. 게시 실패로 인해 브라우저 로그인을 임의로 시작하거나, 다른 클라이언트의 자격 증명을 읽거나, 이전 토큰으로 전환하지 마십시오. 자세한 단계는 인증 설명을 참조하십시오.
• no publish token configured: 인스턴스의 인증 모드를 확인하십시오. 정적 모드는 인스턴스 관리자가 제공하는 토큰이 필요합니다. Access 인스턴스는 OAuth 로그인 또는 명시적 머신 모드가 필요하며, Cloudflare 관리 API 토큰을 게시 키로 사용할 수 없습니다. 자격 증명을 직접 생성하지 마십시오.
• 머신 모드: 명시적인 MOTE_AUTH_MODE=service와 대상에 맞는 MOTE_SERVICE_API_URL, MOTE_SERVICE_CLIENT_ID, MOTE_SERVICE_CLIENT_SECRET이 필요합니다. 누락되거나 유효하지 않으면 중단하고 사용자 로그인 상태로 대체하지 마십시오.
• 시간 초과, 5xx 또는 결과 불명: 자동으로 게시를 재시도하지 마십시오. 이미 불변 문서가 생성되었을 수 있습니다. 먼저 결과를 확인한 후 사용자가 다시 게시할지 결정하도록 하십시오.
• asset not found: <path>: Markdown이 참조하는 로컬 이미지가 존재하지 않습니다. 사용자에게 상대 경로를 확인하도록 안내하십시오.
• unsupported image type: SVG 등 지원되지 않는 형식을 참조한 경우, 사용자에게 png/webp로 변환 후 다시 시도하도록 권고하십시오.