MarkScribe

Model Context Protocol을 위한 컨벤션 인식 마크다운 MCP 서버입니다. MarkScribe를 사용하면 AI 에이전트가 마크다운 파일을 읽고, 쓰고, 검색하고, 검증할 수 있으며, 사용자가 정의한 YAML 스키마를 통해 컨벤션을 강제할 수 있습니다. Obsidian 볼트, Foam 워크스페이스, 디지털 가든, 문서 저장소 등 모든 마크다운 디렉토리에서 작동합니다.

주요 기능

• 원자적 파일 작업을 통한 노트 읽기, 쓰기, 이동 및 삭제

• 콘텐츠 및 프런트매터 전반에 걸친 전체 텍스트 검색 (BM25 랭킹)

• 위키링크 인식: 백링크, 깨진 링크 탐지, 고아 노트 찾기, 연결되지 않은 언급 발견

• YAML 프런트매터 파싱, 유효성 검사 및 일괄 업데이트

• 태그 관리 (프런트매터 및 인라인)

• 스키마를 통한 컨벤션 강제 — 노트 스키마는 프런트매터/콘텐츠를 검증하고, 폴더 스키마는 구조적 규칙을 강제함

• 컨벤션 캐스케이드: _conventions.md 파일을 통해 디렉토리 하위 트리에 스키마 적용 범위 설정

• 경로 보안: .obsidian/, .git/, node_modules/는 항상 차단됨

Related MCP server: kmd

설치

npm install -g markscribe

사용법

MCP 서버로 사용하기

{
  "mcpServers": {
    "markscribe": {
      "command": "markscribe",
      "args": ["--root", "/path/to/your/notes"]
    }
  }
}

CLI 플래그

디렉토리별 설정

루트 디렉토리에 .markscribe/config.yaml을 배치하세요:

paths:
  blocked:
    - private/
    - drafts/
  allowed_extensions:
    - .md
    - .markdown
    - .txt
search:
  max_results: 50
  excerpt_chars: 40

스키마

스키마는 노트와 폴더에 대한 컨벤션을 정의합니다. 스키마 디렉토리(기본값 ~/.markscribe/schemas/)에 배치하세요.

노트 스키마 — 프런트매터 필드 및 콘텐츠 규칙 검증:

name: blog-post
description: Blog post with required metadata
type: note
frontmatter:
  fields:
    title:
      type: string
      required: true
    tags:
      type: list
      required: true
content:
  rules:
    - name: has-outgoing-link
      check: hasPattern
      pattern: "\\[\\[.+?\\]\\]"

폴더 스키마 — 디렉토리에 대한 구조적 규칙 강제:

name: project-folder
description: Project folder with hub note
type: folder
noteSchemas:
  default: blog-post
  hub: project-hub
classification:
  supplemental: [assets, templates]
  skip: [archive]
hub:
  detection:
    - pattern: "_{{folderName}}"
  required: true

노트는 프런트매터의 note_schema: <name>을 통해 스키마를 선택하거나, 컨벤션 캐스케이드(_conventions.md 파일)를 통해 자동으로 선택합니다.

도구

호환 뷰어

MarkScribe는 마크다운 파일을 읽는 모든 도구와 호환됩니다:

• Obsidian — 그래프 뷰와 커뮤니티 플러그인을 지원하는 PKM 앱

• Foam — 연결된 노트를 위한 VS Code 확장 프로그램

• Logseq — 양방향 링크를 지원하는 아웃라이너

• 모든 텍스트 편집기 또는 정적 사이트 생성기

감사의 말

Claude Code로 제작되었습니다.

라이선스

MIT