Technical Writing Helper (twh)

테크니컬 라이팅의 가장 어려운 순간 — 빈 화면 앞에서 구조 잡기 — 를 도와주는 MCP 서버입니다. 인터뷰로 문서 타입을 판정하고, 섹션마다 "답해야 할 질문"이 달린 목차를 제안하며, 기존 문서(.hwp/.hwpx/PDF/DOCX/MD)를 참조로 등록해 근거 있는 초안 작성을 돕습니다.

📖 처음이라면 설명과 사용법 가이드부터 보세요 — 포털/Claude/CLI 세 가지 사용법과 문제 해결 FAQ가 있습니다. 전체 구상과 아키텍처 결정은 DESIGN.md를 보세요.

설치

git clone https://github.com/annayoon/Technical-Writing-Helper
cd Technical-Writing-Helper
uv venv && uv pip install -e .        # PDF/DOCX 참조가 필요하면: -e ".[docs]"
# uv가 없으면: python3 -m venv .venv && .venv/bin/pip install -e .

다른 프로젝트에서 라이브러리로 쓸 때는:

twh @ git+https://github.com/annayoon/Technical-Writing-Helper@main

Claude Desktop / Claude Code에 연결

claude_desktop_config.json (또는 .mcp.json):

{
  "mcpServers": {
    "technical-writing-helper": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Technical-Writing-Helper", "twh-mcp"],
      "env": { "TWH_PROJECT_ROOT": "/path/to/your/writing-project" }
    }
  }
}

TWH_PROJECT_ROOT는 문서 작업 프로젝트의 루트입니다. 참조 문서 인덱스와 팀 템플릿이 그 아래 .twmcp/에 저장됩니다 (개인/회사 데이터이므로 git에 커밋하지 마세요 — .gitignore에 .twmcp/ 추가 권장).

사용 흐름

Claude에서 프롬프트 start_document를 고르거나, 그냥 이렇게 말하면 됩니다:

"결제 모듈 연동 가이드를 쓰려고 해"

Claude가 (1) 독자와 목적을 인터뷰 → (2) classify_document로 타입 판정 → (3) suggest_outline으로 질문이 달린 목차 제안 → (4) 참조 문서가 있으면 add_reference 등록 후 draft_section으로 근거 발췌를 받아 출처가 표기된 초안을 작성합니다.

전사 문서 포털(DocPortal) 통합

MCP 없이도 코어 라이브러리를 직접 import해 쓸 수 있습니다. 실제 사례: DocPortal의 위키 에디터에는 이 코어를 사용한 "구조 잡기" 패널이 있어, 문서 타입·주제·독자·목표를 입력하면 작성 가이드가 달린 목차 뼈대가 본문에 채워집니다 (GET /wiki/outline → twh.outline). 같은 코어가 세 가지 입구로 서빙되는 구조입니다: MCP(개인 Claude/커서) · 직접 import(포털) · CLI(CI).

CLI (docs-as-code / CI용)

MCP 서버와 같은 코어를 CLI로도 실행할 수 있습니다:

twh types                                             # 문서 타입 목록
twh outline how-to --topic "SSO 연동" \
    --audience "사내 개발자" --goal "SSO 로그인 붙이기"   # 목차 스켈레톤 출력
twh ref add ./작년보고서.hwpx --title "작년 보고서"      # 참조 등록
twh ref search "예산 산출 근거"                         # 참조 검색
twh serve                                             # MCP 서버 실행 (stdio)

내장 문서 타입

Diátaxis 4종(tutorial, how-to, reference, explanation) + README, 릴리스 노트, ADR, 트러블슈팅, API 레퍼런스, 공문·보고서(관공서/대내). 팀 고유 템플릿은 save_team_template 도구로 추가할 수 있습니다.

개발

uv pip install -e ".[dev]"
pytest

로드맵

• Phase 1 — 인터뷰 → 타입 판정 → 질문 달린 목차 제안
• Phase 2(일부) — 참조 문서 등록(BM25 검색) + 근거 기반 초안 컨텍스트
• 전사 문서 포털(DocPortal) 위키에 목차 뼈대 생성 통합
• Phase 2(나머지) — Fumadocs 스캐폴딩 + MDX 페이지 생성
• Phase 3 — HWPX 서식 채우기, Pandoc + 한글화 레이어
• Phase 4 — 목차 대비 섹션 검토, 출처 대조 검사, CI lint
• 포털 문서 인덱스(FTS5)를 참조 검색 백엔드로 연결 — 전사 문서 근거 초안