johannesbrandenburger/typst-mcp

Typst MCP Server는 AI 모델이 마크업 기반 조판 시스템(typesetting system)인 Typst와 상호작용할 수 있도록 돕는 MCP (Model Context Protocol) 구현체입니다. 이 서버는 LaTeX와 Typst 간의 변환, Typst 구문(syntax) 검증, 그리고 Typst 코드를 이용한 이미지 생성 도구를 제공합니다.

⚠️ 현재 모든 기능은 tools로 구현되어 있습니다. 이는 Cursor와 VS Code가 아직 다른 프리미티브(primitives)를 처리할 수 없기 때문입니다.

서버는 다음과 같은 도구들을 제공합니다:

: Typst 문서의 모든 장(chapter)을 나열합니다. list_docs_chapters()

• LLM이 문서의 개요를 파악하고 읽을 장을 선택할 수 있게 합니다.

• LLM은 당면한 작업에 따라 읽을 관련 장을 선택해야 합니다.

: Typst 문서에서 특정 장을 가져옵니다. get_docs_chapter(route)

• LLM이 선택한 장을 바탕으로, 이 도구는 해당 장의 내용을 가져옵니다.

• 여러 장을 한 번에 가져오기 위해 get_docs_chapters(routes: list)로도 사용할 수 있습니다.

: Pandoc을 사용하여 LaTeX 코드를 Typst로 변환합니다. latex_snippet_to_typst(latex_snippet)

• LLM은 Typst보다 LaTeX를 더 잘 작성하므로, 이 도구는 LaTeX 코드를 Typst로 변환하는 데 도움을 줍니다.

• 여러 LaTeX 스니펫(snippets)을 한 번에 변환하기 위해 latex_snippets_to_typst(latex_snippets: list)로도 사용할 수 있습니다.

: Typst 코드를 검증합니다. check_if_snippet_is_valid_typst_syntax(typst_snippet)

• Typst 코드를 사용자에게 보내기 전에, LLM은 코드가 유효한지 확인해야 합니다.

• 여러 Typst 스니펫을 한 번에 검증하기 위해 check_if_snippets_are_valid_typst_syntax(typst_snippets: list)로도 사용할 수 있습니다.

: Typst 코드를 PNG 이미지로 렌더링합니다. typst_to_image(typst_snippet)

• 복잡한 Typst 삽화(illustrations)를 사용자에게 보내기 전에, LLM은 코드를 이미지로 렌더링하여 올바르게 보이는지 확인해야 합니다.

• 멀티모달(multi modal) 모델에만 유효합니다.

이 저장소를 클론(Clone)하세요

git clone https://github.com/johannesbrandenburger/typst-mcp.git

typst 저장소를 클론(Clone)하세요

git clone https://github.com/typst/typst.git

• typst 저장소에서 문서 생성(docs generation)을 실행하세요

cargo run --package typst-docs -- --assets-dir ../typst-mcp/typst-docs --out-file ../typst-mcp/typst-docs/main.json

• typst-mcp 저장소를 로컬에 클론(Clone)한 경로에 맞춰 경로를 조정해야 합니다.

• 이 과정을 통해 main.json 파일과 typst-docs 폴더 내의 에셋(assets)이 생성됩니다.

필요한 의존성(dependencies)을 설치하세요:

uv sync

(uv가 설치되어 있지 않다면 설치하세요) -
Typst 설치

서버 스크립트를 실행하세요:

python server.py

또는 Claude Desktop에 MCP로 설치하세요:

mcp install server.py

또는 VS Code의 새로운 에이전트 모드(agent mode)를 사용하세요:

Docker 설치 및 사용법에 대해서는 상세한 빌드 정보와 지침이 담긴 DOCKER.md를 참조하세요.

이 MCP 서버는 다양한 AI 코딩 플랫폼과 통합할 수 있습니다. 아래는 인기 있는 플랫폼들에 대한 설정 지침입니다:

Claude Desktop 설정 파일(claude_desktop_config.json)에 다음을 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"typst": {
...

또는 로컬 설치의 경우:

{
"mcpServers": {
"typst": {
...

프로젝트별 설정을 위해 프로젝트 루트에 .cursor/mcp.json을 생성하세요:

{
"mcpServers": {
"typst": {
...

또는 전역(global) 설정을 위해 ~/.cursor/mcp.json을 생성하세요. 로컬 설치의 경우:

{
"mcpServers": {
"typst": {
...

프로젝트별 설정을 위해 프로젝트 루트에 .roo/mcp.json을 생성하세요:

{
"mcpServers": {
"typst": {
...

또는 Roo Code MCP 설정 뷰를 통해 전역 설정을 편집하세요. 로컬 설치의 경우:

{
"mcpServers": {
"typst": {
...

프로젝트 루트에 opencode.json 파일을 생성하거나 편집하세요:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
...

로컬 설치의 경우:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
...

Claude Code 설정 파일(~/.claude/settings.json)에서 MCP 서버를 구성하세요:

{
"mcpServers": {
"typst": {
...

또는 로컬 설치의 경우:

{
"mcpServers": {
"typst": {
...

VS Code의 에이전트 모드(Agent Mode)는 네이티브 MCP 지원을 제공합니다 (확장 프로그램이 필요하지 않음):

• VS Code 설정에서 에이전트 모드를 활성화하세요 (chat.agent.enabled).
• 워크스페이스에 .vscode/mcp.json 파일을 생성하세요:

{
"servers": {
"typst": {
...

전역 설정을 위해서는 MCP: Open User Configuration 명령을 통해 사용자 프로필에 추가하세요.

⚠️ Typst 문서의 스키마(schema)는 안정적이지 않으며 언제든지 변경될 수 있습니다. 스키마는 Typst 소스 코드에서 생성되며, 완전하거나 정확함이 보장되지 않습니다. 스키마가 변경될 경우, 문서 기능이 다시 작동할 수 있도록 이 리포지토리(repository)도 그에 따라 업데이트되어야 합니다.