SDK

JavaScript SDK

mdfy.app를 위한 TypeScript-first 클라이언트. Node.js, Deno, Bun, 브라우저에서 동작합니다. 의존성 없음.

설치

bash
npm install @mdcore/api

다른 패키지 매니저: yarn add @mdcore/api 또는 pnpm add @mdcore/api

시작하기

typescript
import { publish } from "@mdcore/api";

const result = await publish("# Hello World");
console.log(result.url);  // https://mdfy.app/abc123

MdfyClient

MdfyClient 클래스는 사용자 식별 정보와 Base URL 설정을 포함한 상태 기반 클라이언트를 제공합니다.

typescript
import { MdfyClient } from "@mdcore/api";

const client = new MdfyClient({
  baseUrl: "https://mdfy.app",  // default
  userId: "user-uuid",          // optional
  email: "user@example.com",    // optional
});

생성자 옵션

baseUrlstringAPI Base URL. 기본값: https://mdfy.app
userIdstring소유권 기반 작업을 위한 사용자 UUID.
emailstring사용자 식별용 이메일.

메서드

publish(markdown, options?)PublishResult새 문서를 생성합니다.
pull(id, options?)DocumentID로 문서를 조회합니다.
update(id, markdown, options)void문서 내용을 수정합니다.
delete(id, editToken)void문서를 소프트 삭제합니다.
list()Document[]사용자의 문서 목록을 조회합니다.
versions(id)Version[]버전 이력을 조회합니다.
upload(file)string이미지를 업로드하고 URL을 반환합니다.
setPublished(id, editToken)void문서를 게시 상태로 설정합니다.
setDraft(id, editToken)void문서를 임시 저장 상태로 설정합니다.

client.publish()

typescript
const result = await client.publish("# Hello World", {
  title: "My Document",
  isDraft: false,
  password: "optional-secret",
  expiresIn: "7d",
  editMode: "token",
  folderId: "folder-uuid",
});

console.log(result.id);        // "abc123"
console.log(result.editToken); // "tok_aBcDeFgH..."
console.log(result.url);       // "https://mdfy.app/abc123"

client.pull()

typescript
const doc = await client.pull("abc123");

console.log(doc.markdown);    // "# Hello World"
console.log(doc.title);       // "My Document"
console.log(doc.view_count);  // 42
console.log(doc.is_draft);    // false

// 비밀번호 보호 문서
const doc2 = await client.pull("abc123", {
  password: "secret",
});

client.update()

typescript
await client.update("abc123", "# Updated Content", {
  editToken: "tok_aBcDeFgH",
  title: "New Title",
  changeSummary: "Fixed typos in section 2",
});

client.delete()

typescript
await client.delete("abc123", "tok_aBcDeFgH");
// 문서가 소프트 삭제됩니다 (소유자가 복원 가능)

client.list()

typescript
const docs = await client.list();

docs.forEach(doc => {
  console.log(`${doc.id}: ${doc.title} (${doc.is_draft ? "draft" : "published"})`);
});

client.versions()

typescript
const versions = await client.versions("abc123");

versions.forEach(v => {
  console.log(`${v.version}: ${v.changeSummary} (${v.created_at})`);
});

client.upload()

typescript
// 브라우저
const input = document.querySelector("input[type=file]");
const file = input.files[0];
const imageUrl = await client.upload(file);

// Node.js
import { readFileSync } from "fs";
const buffer = readFileSync("screenshot.png");
const blob = new Blob([buffer], { type: "image/png" });
const imageUrl = await client.upload(blob);

독립 함수

클라이언트 인스턴스 없이 빠르게 단일 작업을 수행할 수 있습니다.

typescript
import {
  publish,
  pull,
  update,
  deleteDocument,
  upload,
} from "@mdcore/api";

// 게시
const { id, editToken, url } = await publish("# Hello World");

// 조회
const doc = await pull(id);

// 수정
await update(id, "# Updated content", editToken);

// 삭제
await deleteDocument(id, editToken);

// 이미지 업로드
const imageUrl = await upload(file);

npm 패키지

독립적인 패키지들입니다. 각각 별도로 설치하여 사용할 수 있으며, 패키지 간 의존성이 없습니다.

@mdcore/api

mdfy.app HTTP 클라이언트. 문서 게시, 조회, 수정, 삭제. 의존성 없음 (native fetch).

npm install @mdcore/api
@mdcore/engine

WASM Markdown 렌더러 (Rust/comrak). GFM, KaTeX 수학, Mermaid 다이어그램, 구문 강조.

npm install @mdcore/engine
@mdcore/styles

CSS 전용 패키지. 다크/라이트 테마, 렌더링 스타일, 인쇄/PDF 스타일. JavaScript 없음.

npm install @mdcore/styles
@mdcore/ai

AI 프로바이더 연동. Gemini, OpenAI, Anthropic. 텍스트-Markdown 변환, ASCII 렌더링.

npm install @mdcore/ai
mdfy-mcp

로컬 stdio MCP (핵심 도구 6개). 전체 25개 도구는 https://mdfy.app/api/mcp 호스팅 MCP에서 사용 가능.

npx mdfy-mcp

@mdcore/engine 예시

typescript
import { mdcore } from "@mdcore/engine";
import { postProcessHtml } from "@mdcore/engine";

await mdcore.init();

const { html, flavor } = mdcore.render("# Hello **World**");
const finalHtml = await postProcessHtml(html);

@mdcore/styles 예시

css
/* 전체 스타일 임포트 */
@import "@mdcore/styles";

/* 개별 모듈 임포트 */
@import "@mdcore/styles/theme-dark.css";
@import "@mdcore/styles/rendered.css";
@import "@mdcore/styles/code.css";
@import "@mdcore/styles/print.css";

@mdcore/ai 예시

typescript
import { mdfyText, callAI, isAiConversation } from "@mdcore/ai";

// 원시 텍스트를 구조화된 Markdown으로 변환
const markdown = await mdfyText("some rough text here...");

// AI 대화 형식 감지
if (isAiConversation(text)) {
  const { turns } = parseConversation(text);
  const formatted = formatConversation(turns);
}