de en es ja ko ru zh

mdmagic-mcp-server

Name: mdmagic-mcp-server
Author: MDMagic-MCP

by MDMagic-MCP

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

MDMagic MCP 서버

사용자 지정 Word 템플릿(레터헤드, 브랜딩, 폰트 등)을 사용하여 Markdown을 DOCX, PDF 및 HTML로 변환하세요. 자체 템플릿이 없는 경우를 위해 15가지 디자이너 제작 템플릿도 제공합니다.

npm version MCP Registry Smithery license

MDMagic은 Claude, Cursor, VS Code 및 모든 MCP 호환 AI 어시스턴트에 직접 연결되어 전문적인 문서 변환 파이프라인(Pandoc + Microsoft Graph + Mammoth.js)과 사용자 템플릿에 직접 액세스할 수 있게 해줍니다. 기존 레터헤드, 문구류, 브랜드 가이드라인, 계약서 양식, 제안서 템플릿 등 Microsoft Word에서 사용하는 모든 것을 업로드하면, AI 어시스턴트가 Markdown을 사용자의 로고, 폰트, 색상, 바닥글, 페이지 번호, 워터마크 및 서명 블록이 포함된 세련된 문서로 직접 변환합니다. 결과물은 일반적인 AI 내보내기가 아닌 디자인 팀이 작업한 것처럼 보입니다.

You: "Take this report and turn it into an Executive_Platinum PDF."

Claude: ✅ Done. Here's your secure download link.
        14-page PDF, 2.3 MB, expires in 60 minutes.

설치

MDMagic 계정(무료 티어 제공)이 필요하며 계정 페이지에서 API 키를 발급받아야 합니다.

Claude Desktop

claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

설정 파일 위치:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
Linux — ~/.config/Claude/claude_desktop_config.json

Claude Desktop을 재시작하세요. 도구 목록에 MDMagic 도구가 나타납니다.

Cursor

~/.cursor/mcp.json에 추가하거나 설정 → MCP를 통해 추가하세요:

{
  "mcpServers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code (MCP 확장 프로그램 사용)

{
  "mcp.servers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

호스팅 버전 (설치 불필요)

사용자 컴퓨터에 Node를 설치하고 싶지 않으신가요? 호스팅된 엔드포인트를 사용하세요:

{
  "mcpServers": {
    "mdmagic": {
      "url": "https://api.mdmagic.ai/mcp",
      "headers": {
        "x-api-key": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

동일한 도구와 템플릿을 Streamable HTTP를 통해 제공합니다. 로컬 프로세스를 실행하지 않는 클라이언트에게 유용합니다.

Related MCP server: AI Group Markdown to Word MCP Server

주요 기능

연결 후 AI 어시스턴트에게 다음과 같이 요청할 수 있습니다:

"이 마크다운을 Executive_Platinum 템플릿을 사용하여 PDF로 변환해 줘."
"사용 가능한 템플릿이 뭐야?"
"이 800단어 보고서를 DOCX + PDF로 렌더링하는 데 몇 크레딧이 필요해?"
"이것을 가로 방향, US Letter 크기, Legal_Burgundy 템플릿으로 렌더링해 줘."
"내 크레딧 잔액을 확인해 줘."

AI가 적절한 도구를 선택하고 안전한 기간 한정 다운로드 링크를 반환합니다.

도구

도구	기능
`convert_document`	Markdown을 DOCX / PDF / HTML 또는 세 가지 모두로 변환합니다. 안전한 만료 URL을 반환합니다.
`validate_markdown`	변환 전 사전 검사입니다. 잘못된 표, 닫히지 않은 코드 펜스 및 기타 구문 문제를 찾아냅니다.
`estimate_conversion_cost`	단어 수, 페이지 수, 형식 및 템플릿 유형을 기반으로 변환 비용을 사전 산정합니다.
`check_credit_balance`	현재 크레딧 잔액(구독 + 구매 풀) 및 플랜 상태를 확인합니다.
`list_all_templates`	전체 템플릿 카탈로그: 15개의 내장 템플릿(카테고리별 그룹화) + 사용자 지정 업로드 템플릿.
`list_builtin_templates`	내장 템플릿만 표시: 비즈니스(5), 크리에이티브(6), 전문가용(2), 기술 분야(2).
`list_custom_templates`	사용자가 업로드한 사용자 지정 템플릿만 표시합니다.
`get_template_details`	특정 템플릿에 대해 사용 가능한 변형(페이지 크기 × 방향)을 표시합니다.
`recommend_template`	설명된 목적에 가장 적합한 내장 템플릿을 제안합니다 ("Q4 이사회 자료" → Executive_Platinum).
`show_default_settings`	기본 페이지 크기, 방향 및 템플릿 환경 설정을 표시합니다.

`convert_document` — 입력 옵션

소스를 제공하는 세 가지 방법:

content — 원시 마크다운 문자열 (가장 일반적)
filePath — .md 파일의 절대 경로 (IDE 워크플로우에 적합)
fileContent — base64로 인코딩된 마크다운 (바이너리 안전 전송용)

추가 옵션:

templateName — 예: Executive_Platinum, Legal_Burgundy 또는 사용자 지정 템플릿 UUID
outputFormat — docx, pdf, html, all 또는 all-formats
pageSize — A4, A3, US_Letter, US_Legal, Executive
orientation — Portrait 또는 Landscape

설정

변수	기본값	참고
`MDMAGIC_API_KEY`	(필수)	mdmagic.ai/account에서 발급받은 개인 API 키
`MDMAGIC_BASE_URL`	`https://api.mdmagic.ai`	로컬 개발 또는 스테이징 환경에서만 재정의
`REQUEST_TIMEOUT`	`30000`	요청 시간 제한 (ms)
`MCP_TRANSPORT`	`stdio`	`stdio` (기본값) 또는 자체 호스팅 Streamable HTTP용 `http`
`MCP_HTTP_PORT`	`3001`	HTTP 전송 모드용 포트
`MCP_HTTP_HOST`	`127.0.0.1`	HTTP 전송 모드용 바인딩 주소

대부분의 사용자는 MDMAGIC_API_KEY만 설정하면 됩니다.

가격

변환 비용은 페이지 수와 출력 형식에 따라 크레딧으로 계산됩니다:

DOCX: 페이지당 1 크레딧 (기본)
PDF: 페이지당 +1 크레딧
HTML: 페이지당 +1 크레딧
사용자 지정 템플릿: 페이지당 +1 크레딧

사용자 지정 템플릿을 사용하여 5페이지 보고서를 DOCX + PDF + HTML로 변환하는 경우 = 5 × (1 + 1 + 1 + 1) = 20 크레딧.

estimate_conversion_cost 도구는 비용을 지불하기 전에 정확한 수치를 반환합니다. 또한 잔액이 부족하면 MCP가 실행을 거부하므로 예상치 못한 청구서가 발생하지 않습니다.

무료 티어 크레딧은 매달 갱신됩니다. 유료 플랜 및 크레딧 충전은 mdmagic.ai에서 가능합니다.

개인정보 보호

영구 저장 없음. 문서는 PDF 렌더링을 위해 Microsoft Graph API를 거치며 5~10초 이내에 삭제됩니다. 출력 파일은 다운로드 후 또는 60분 후(둘 중 빠른 시점)에 MDMagic 서버에서 삭제됩니다.
무작위 파일명. 소스 파일은 UUID를 사용하며, 사용자를 식별할 수 있는 이름은 절대 사용하지 않습니다.
보안 다운로드 URL. 각 변환은 세션 ID와 다운로드 토큰이 포함된 일회용 URL을 반환합니다. 공개 파일 디렉토리는 없습니다.
API 키 격리. 각 사용자는 자신의 키로 인증합니다. 공유 자격 증명은 없습니다.

문제 해결

MDMAGIC_API_KEY environment variable is required 클라이언트 설정(JSON의 env 블록)에 환경 변수를 설정하세요. 셸에 넣지 마세요. npx는 이를 인식하지 못합니다.

Invalid API key format 키는 mdmagic- 뒤에 정확히 16자리 숫자가 와야 합니다. 계정 페이지에서 정확히 복사하세요.

Failed to connect to MDMagic API 브라우저에서 https://api.mdmagic.ai/health를 확인하세요. 접속이 가능하다면 로컬 네트워크나 방화벽 문제입니다. MCP를 실행 중인 컴퓨터에서 MDMAGIC_BASE_URL(기본값 https://api.mdmagic.ai)에 도달할 수 있는지 확인하세요.

Claude Desktop에 도구가 나타나지 않음 claude_desktop_config.json을 수정한 후 Claude Desktop을 완전히 종료하고 다시 실행하세요. 창을 닫는 것만으로는 충분하지 않습니다.

Insufficient credits check_credit_balance를 사용하여 잔액을 확인하고, estimate_conversion_cost로 비용을 미리 확인하거나 mdmagic.ai/account에서 충전하세요.

로컬 개발

git clone https://github.com/MDMagic-MCP/mdmagic-mcp-server.git
cd mdmagic-mcp-server
npm install

# Set your API key (use http://localhost:3000 if running the API locally)
cp .env.example .env
# edit .env

# Build and inspect
npm run build
npm run inspector

MCP Inspector(npm run inspector)는 도구별로 서버를 테스트할 수 있는 웹 UI를 실행합니다. 새로운 도구를 추가하거나 인수 유효성 검사를 디버깅할 때 유용합니다.

npm test로 테스트를 실행하세요.

링크

MDMagic — mdmagic.ai
API 키 발급 — mdmagic.ai/account
이슈 — github.com/MDMagic-MCP/mdmagic-mcp-server/issues
MCP 사양 — modelcontextprotocol.io

라이선스

MIT — LICENSE를 참조하세요.

Available Tools

10 tools

check_credit_balanceA

Read-onlyIdempotent

Inspect

Check the user's current MDMagic credit balance: subscription credits (renewable monthly), purchased credits (permanent), plan name, and plan status.

CALL THIS PROACTIVELY when:

The user asks 'how many credits do I have' or similar
After a conversion, if the user wants to know what's left (also returned by convert_document directly)
Before a conversion of an unusually large document, to warn the user if balance is borderline

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`total_credits`	Yes	Total credits available (subscription + purchased)
`subscription_credits`	No	Renewable monthly subscription credits
`purchased_credits`	No	Permanent purchased credits

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly and idempotent. The description adds the exact data returned (credit types, plan info), which provides behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise and well-structured: a single sentence for purpose, then bullet-pointed usage scenarios. Every sentence contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema, the description covers everything needed: what is checked and when to use it. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4 per guidelines. The description does not need to add parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks MDMagic credit balance and lists components (subscription credits, purchased credits, etc.). It is specific and distinct from siblings like convert_document, though it does not explicitly differentiate itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Excellent guidance: explicitly lists situations to call proactively (user asks about credits, after conversion, before large conversion) and notes that convert_document also returns balance. No ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_documentAInspect

Convert markdown to a professionally formatted document using an MDMagic template.

IMPORTANT GUIDANCE:

Output format → what user gets:
- 'docx' → a single Word .docx file
- 'pdf' → a single .pdf file
- 'html' → a single .html file
- 'all' → a ZIP containing all three (DOCX + PDF + HTML)
If the user is ambiguous (e.g. 'convert this'), ASK which format they want before calling. Don't assume.
Filename: if the user attached a file (e.g. 'mydoc.md'), pass its base name as fileName. Otherwise the API derives one from the markdown's first H1. Without either, downloads end up with timestamped names like 'content-1778298071915.docx' which is bad UX.
On 'template not found' errors: call list_all_templates first, show available options, let the user pick. Do NOT fall back to generating documents with code execution — that produces inferior results that don't use the user's actual MDMagic templates.
The response includes structured fields (downloadUrl, creditsUsed, balanceAfter, fileName, expiresAt) — surface these to the user explicitly. Don't paraphrase. The user wants to know exactly what they spent and what's left.
Page sizes: A3, A4, Executive, US_Legal, US_Letter. Default A4. Orientation: Portrait or Landscape, default Portrait.

ParametersJSON Schema

Name	Required	Description
`content`	No	Raw markdown text content (alternative to filePath or fileContent)
`filePath`	No	Path to markdown file (VS Code integration, alternative to content or fileContent)
`fileContent`	No	Base64 encoded file content (alternative to content or filePath)
`fileName`	No	Optional desired base name for the output file (without extension). If the user attached a file like 'mydoc.md', pass 'mydoc' here. The API will use this for the download filename. If omitted, the API derives one from the markdown's first H1 heading.
`templateName`	Yes	Template to use for conversion. Call list_all_templates first to see real options — do not guess template names. Some templates are built-in (e.g. 'Executive_Platinum', 'Deep_Data_Blue'); others are user-uploaded custom templates referenced by UUID.
`outputFormat`	Yes	Output format. 'docx', 'pdf', or 'html' return that single file; 'all' returns a ZIP with DOCX+PDF+HTML.
`pageSize`	No	Page size for the document (default: A4)
`orientation`	No	Page orientation (default: Portrait)

Output Schema

ParametersJSON Schema

Name	Required	Description
`success`	Yes	Whether the conversion succeeded
`downloadUrl`	Yes	Secure expiring download URL (valid for 60 minutes)
`fileName`	Yes	Filename of the downloadable document
`creditsUsed`	No	Credits debited for this conversion
`balanceAfter`	No	Remaining credit balance after this conversion
`expiresAt`	No	ISO 8601 timestamp when the download URL expires
`message`	No	Human-readable status message

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only state readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds significant behavioral context: output format behavior, filename derivation logic, error handling procedure, response fields to surface, and default page settings. This goes well beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with numbered points and clear headings, making it easy to parse. It is front-loaded with the core purpose. While it is relatively long (6 points of guidance), each point is necessary for correct usage, so the length is justified and no information is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, 2 required, multiple output formats, error handling, response fields), the description covers all crucial aspects: input sources, output options, error recovery, response structure, page settings, and defaults. No important aspect is omitted. The description compensates for the missing output schema details by specifying the fields to surface.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, yet the description adds richer context: it explains importance of passing fileName for UX, warns not to guess templateName but to call list_all_templates, clarifies outputFormat values, and documents defaults for pageSize and orientation. This adds meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear, specific verb 'Convert markdown to a professionally formatted document using an MDMagic template', which precisely states the action and resource. It distinguishes itself from sibling tools (like list_all_templates or check_credit_balance) by being the only conversion tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and when-not-to-use guidance, e.g., asking users for format if ambiguous, not falling back to code generation on template missing, and instead calling list_all_templates. It includes concrete actions like 'if the user is ambiguous... ASK' and 'on template not found errors: call list_all_templates first'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

estimate_conversion_costA

Read-onlyIdempotent

Inspect

Estimate credit cost for a conversion BEFORE running it. Returns word count, page calculation (300 words/page), and a credit breakdown by format and template type. Use this when the user asks 'how much will this cost?' or when you suspect a conversion might exceed their balance — convert_document refuses to run if credits are insufficient, so estimating first is friendlier.

ParametersJSON Schema

Name	Required	Description
`content`	Yes	Markdown content to estimate credit cost for
`templateName`	Yes	Template ID or name (UUID for custom templates, name for system templates)
`outputFormat`	Yes	Output format(s): docx (DOCX only), pdf (DOCX+PDF), html (DOCX+HTML), all/all-formats (DOCX+PDF+HTML)
`pageSize`	No	Page size for the document
`orientation`	No	Page orientation

Output Schema

ParametersJSON Schema

Name	Required	Description
`wordCount`	No	Word count of the markdown content
`pageCount`	No	Estimated page count (300 words/page)
`totalCredits`	Yes	Total credits required for this conversion
`breakdown`	No	Human-readable breakdown of how credits are calculated

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, destructive=false, idempotent=true. Description adds context that convert_document refuses if insufficient credits, explaining the behavioral context of the estimate. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each valuable: first states purpose, second lists return values, third gives when-to-use guidance. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters with full schema descriptions and an output schema (present), the description effectively covers usage context, behavioral traits, and relationship to sibling tool convert_document. Complete for an estimation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions for all 5 parameters. The description adds value by explaining that the estimate includes credit breakdown by format and template type, and mentions the 300 words/page calculation, which provides additional insight into how parameters affect the result.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it estimates credit cost before conversion, specifies return values (word count, page calculation, credit breakdown), and distinguishes itself from convert_document by mentioning it is friendly to use before running the actual conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use: when user asks 'how much will this cost?' or when suspecting insufficient balance. Also contrasts with convert_document that refuses if credits are insufficient, making the estimation alternative clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_template_detailsA

Read-onlyIdempotent

Inspect

Show available variants (page sizes and orientations) for a specific template. All MDMagic templates support the full 5×2 matrix: A3, A4, Executive, US_Legal, US_Letter × Portrait/Landscape. Use this when the user asks 'does this template come in Legal Landscape?' or 'what sizes are available?' — confirms the variant before convert_document runs.

ParametersJSON Schema

Name	Required	Description	Default
`templateName`	Yes	Template ID or name (e.g. Executive_Platinum, or a UUID for custom templates)

Output Schema

ParametersJSON Schema

Name	Required	Description
`template`	Yes
`pageSizes`	Yes	Supported page sizes
`orientations`	Yes	Supported orientations

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds: all templates support a 5x2 matrix, and it serves as a pre-check for convert_document. This enriches behavioral context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, followed by usage examples. Every sentence is informative and necessary. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, and output context (matrix of sizes). With an output schema present, return details are not needed. Slight gap: no mention of error handling for invalid templates, but overall sufficient for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description of templateName. Description doesn't add new parameter details (e.g., format specifics) beyond schema, which is adequate. Baseline 3 applies as schema already covers the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Show available variants (page sizes and orientations) for a specific template', specifying verb and resource. It distinguishes from siblings like list_all_templates and explicitly ties to convert_document, making purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit example queries ('does this template come in Legal Landscape?') and advises using before convert_document. While it lacks explicit alternatives or when-not-to-use, the context is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_all_templatesA

Read-onlyIdempotent

Inspect

List all 15 built-in MDMagic templates plus any custom templates the user has uploaded.

CALL THIS PROACTIVELY when:

The user mentions a template by name (verify it exists before convert_document)
The user asks 'what templates are available' or similar
A previous convert_document call returned 'template not found'
The user describes the look they want without naming a template (so you can suggest a real one)

Returns: name, description, type (built-in vs custom), and category. Categories are: Business (5 templates), Creative (6), Professional (2), Technical (2). Use the optional category filter to narrow recommendations (e.g. 'for legal documents' → category: 'Professional').

ParametersJSON Schema

Name	Required	Description	Default
`includeDetails`	No	Include template details like available page sizes and orientations (default: false)
`category`	No	Optional filter — return only built-in templates in this category. Custom templates are always included regardless. Categories: Business (executive/financial), Creative (designer/artistic/novelty), Professional (legal), Technical (code/data documentation).

Output Schema

ParametersJSON Schema

Name	Required	Description
`builtinCount`	No	Number of built-in templates returned
`customCount`	No	Number of custom templates returned
`templates`	Yes	All matching templates

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds value beyond annotations by describing return fields (name, description, type, category) and category counts, plus noting custom templates always included regardless of filter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with main purpose, uses bullet points for usage scenarios, but could be slightly more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Sufficiently covers what the tool returns and usage patterns, though output schema is not fully utilized for additional structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage but description reinforces usage of category filter for narrowing recommendations and adds context about custom templates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies it lists 15 built-in MDMagic templates plus custom templates, distinguishing it from siblings like list_builtin_templates and list_custom_templates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-call scenarios: verify template existence, answer 'what templates', handle 'template not found' errors, and suggest templates when user describes look without naming one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_builtin_templatesA

Read-onlyIdempotent

Inspect

List the 15 built-in MDMagic templates, grouped by category. Same as list_all_templates but excludes the user's custom uploads. Use this when the user asks specifically about MDMagic's bundled templates rather than their personal ones.

Categories available: Business (5), Creative (6), Professional (2), Technical (2).

ParametersJSON Schema

Name	Required	Description	Default
`includeDetails`	No	Include template details like available page sizes and orientations (default: false)
`category`	No	Optional filter — return only templates in this category.

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No	Number of templates returned
`templates`	Yes	Matching built-in templates

TDQS

A4.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds category grouping and count details but no additional behavioral caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded purpose and clear structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple read-only tool with output schema present; description fully covers purpose, usage, and parameter context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100%, description mentions categories and optional filter, adding grouping and count context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists the 15 built-in MDMagic templates grouped by category, and distinguishes from list_all_templates and list_custom_templates by excluding custom uploads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use this when the user asks about bundled templates rather than personal ones, differentiating from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_custom_templatesA

Read-onlyIdempotent

Inspect

List only the user's custom-uploaded Word templates. Use this when the user asks about their own templates ('show me my templates', 'do I have a letterhead?'). Custom templates are referenced by UUID, not name, when calling convert_document.

ParametersJSON Schema

Name	Required	Description	Default
`includeDetails`	No	Include template details like available page sizes and orientations (default: false)

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No	Number of custom templates returned
`templates`	Yes	User's custom templates

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and idempotentHint; description adds behavioral context that it only lists custom templates and that templates are referenced by UUID. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose, and includes essential usage guidance without any unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (1 optional parameter, output schema exists, annotations cover safety), the description is complete: it specifies the scope (custom only), links to a related tool, and the schema and annotations provide full parameter and behavioral details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter (includeDetails) with full description coverage (100%). The tool description does not add extra meaning to this parameter, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the specific resource 'user's custom-uploaded Word templates'. It distinguishes itself from sibling tools like list_all_templates and list_builtin_templates by focusing on custom templates and mentioning UUID referencing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description explicitly provides scenarios for use ('when the user asks about their own templates') and gives guidance on using templates with convert_document via UUID. It does not list when not to use, but the context is clear enough for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recommend_templateA

Read-onlyIdempotent

Inspect

Suggest the best built-in template(s) for a described purpose. Use this when the user describes WHAT the document is (e.g. 'Q4 board pack', 'API reference', 'wedding invitation', 'legal contract') without naming a template. Returns ranked recommendations with rationale.

Why this exists: AI assistants often guess template names that don't exist. This tool maps purpose → real template names from MDMagic's catalog, so convert_document doesn't fail with 'template not found'.

ParametersJSON Schema

Name	Required	Description	Default
`purpose`	Yes	Free-text description of the document's purpose. Examples: 'Q4 board pack for investors', 'restaurant menu', 'developer API documentation', 'wedding invitation'.
`topN`	No	How many recommendations to return (1-5, default 3)

Output Schema

ParametersJSON Schema

Name	Required	Description
`purpose`	No	Echoes back the purpose that was matched
`rationale`	No	Why these templates were picked
`recommendations`	Yes	Ranked list of template IDs to pass to convert_document

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only and idempotent. The description adds value by stating that it 'returns ranked recommendations with rationale', which is behavioral context not covered by annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, with the first sentence stating the core action. Two paragraphs: one for usage and one for rationale. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a two-parameter tool with existing output schema. It explains the input, output (ranked recommendations with rationale), and the problem it solves, linking to the sibling tool convert_document.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with detailed descriptions for both parameters (purpose and topN). The tool description does not add further explanation beyond the schema, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Suggest the best built-in template(s) for a described purpose.' It uses the specific verb 'suggest' and resource 'built-in templates', and explicitly distinguishes from sibling tools like list_all_templates by noting that this tool maps purpose to real template names to avoid conversion failures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'when the user describes WHAT the document is (e.g. ...) without naming a template.' It also explains why it exists (to prevent AI assistants from guessing non-existent templates) and implicitly indicates not to use when a template name is already known.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show_default_settingsA

Read-onlyIdempotent

Inspect

Show the user's default paper size and orientation preferences (set on their account page). Useful when the user hasn't specified pageSize/orientation explicitly — call this to honor their defaults instead of using A4/Portrait blindly.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`default_page_size`	Yes	User's preferred page size
`default_orientation`	Yes	User's preferred page orientation

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds context about reading account page preferences, which aligns with annotations and gives slightly more insight into the data source.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences, front-loading the purpose and immediately following with usage guidance. Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and has an output schema, the description sufficiently covers purpose and usage. No additional details are necessary for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description does not need to elaborate on parameters; baseline score of 4 for zero-parameter tools is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows default paper size and orientation preferences from the user's account page, using specific verb 'show' and resource 'defaults'. It distinguishes from sibling tools by focusing on a specific setting retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises when to use this tool (when user hasn't specified pageSize/orientation) and contrasts with a default behavior (A4/Portrait), providing clear context for appropriate invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_markdownA

Read-onlyIdempotent

Inspect

Pre-flight markdown validation BEFORE conversion. Catches malformed tables (mismatched pipes), unclosed code fences, broken task lists, and unsupported syntax. Returns a green/amber/red status plus the detected markdown features.

CALL THIS PROACTIVELY when:

The user is about to convert a long document (>5 pages) — validating first is cheap; running a doomed conversion costs credits
The user reports a previous conversion produced broken output
You generated the markdown yourself and want to verify it's clean before spending credits

Returns: status (green=safe, amber=minor issues, red=will likely break), detected features (tables, code blocks, task lists, math), and a human-readable message.

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes	Markdown content to validate
`filename`	No	Optional filename label for the response (defaults to 'content.md')

Output Schema

ParametersJSON Schema

Name	Required	Description
`filename`	No	Filename label echoed back
`status`	Yes	Validation verdict
`message`	Yes	Human-readable explanation of any issues
`inputFormat`	No	Detected markdown flavour (e.g. gfm, commonmark)
`additionalPandocFlags`	No	Pandoc flags that will be applied
`detectedFeatures`	No	Map of markdown features found in the content

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnly, idempotent), the description reveals that validation is cheap, returns a green/amber/red status plus detected features, and helps avoid costly conversion failures. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening, bulleted usage guidelines, and a return summary. It is appropriately sized but could be slightly more concise without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple validation tool with full schema coverage and an output schema, the description covers purpose, when to use, what it detects, and what it returns. No missing critical information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds minimal extra meaning to parameters. It does not elaborate on the content or filename beyond what the schema already specifies, but the return value description compensates slightly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Pre-flight markdown validation BEFORE conversion' and lists specific issues caught (malformed tables, unclosed code fences, etc.). It distinguishes itself from sibling tools like convert_document, which performs the actual conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides three scenarios when to call the tool proactively: before converting a long document, after broken output, and when verifying self-generated markdown. It contrasts with the cost of a failed conversion, offering clear guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

10 tool updatesv0.1.0May 9, 2026
- First observedcheck_credit_balance
- First observedconvert_document
- First observedestimate_conversion_cost
- First observedget_template_details
- First observedlist_all_templates
- First observedlist_builtin_templates
- First observedlist_custom_templates
- First observedrecommend_template
- First observedshow_default_settings
- First observedvalidate_markdown

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.6/5.0

Scored 2026-05-09 23:50 across 10 tools

Disambiguation5/5

Each tool has a distinct and non-overlapping purpose—balance checking, conversion, cost estimation, template listing/details, recommendations, defaults, and validation. No two tools could be confused.

Naming Consistency5/5

All tools use a consistent verb_noun snake_case pattern (e.g., list_all_templates, validate_markdown), making the set predictable and easy to navigate.

Tool Count5/5

With 10 tools, the count is well-scoped for a document conversion service. Each tool addresses a necessary step in the user workflow without unnecessary bloat.

Completeness5/5

The tool surface covers the full lifecycle: template discovery, defaults retrieval, markdown validation, cost estimation, credit checking, conversion, and post-conversion feedback. No obvious gaps for the stated purpose.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

netcafe-docflow A
com.ainetcafe
Markdown in, any format out. PDFs merged, split, watermarked. Runs on our own doc engines.
Developer Tools Documentation Access
1311
UnmarkdownOAuth
io.github.UnMarkdown
The document publishing layer for AI tools. Convert markdown to 6 destinations, 62 templates.
Developer Tools Content Management Systems App Automation
21
mcpOAuth
com.mdtidy
Clean, repair, and convert AI-generated Markdown to HTML/PDF/DOCX/PNG; save and share documents.
Content Management Systems Developer Tools
2
file2markdown A
ai.file2markdown
Convert docs and web pages to clean Markdown: PDF, DOCX, XLSX, EPUB, scans, URLs. Batch of 10.
Browser Automation Documentation Access Web Scraping
51

Related MCP Servers

Word MCP Server
Workplace & Productivity Content Management Systems Developer Tools
mndambuki
F
license
Not graded
quality
D
maintenance
Enables creation and management of Word documents from markdown content, with support for multiple templates and conversion of chat conversations to formatted Word documents.
Updated 10 months ago (2025-12-07 09:04 UTC)
-
AI Group Markdown to Word MCP
Developer Tools Workplace & Productivity Content Management Systems
jackdark425
A
license
A
quality
C
maintenance
Converts Markdown documents to professional Word documents with advanced formatting capabilities including mathematical formulas, custom styling, tables, images, headers/footers, and watermarks.
Updated 6 months ago (2026-04-24 05:56 UTC)
4
80 npm
14
MIT
mcp-server-docx
Workplace & Productivity Developer Tools
jamesmehorter
F
license
B
quality
C
maintenance
Enables creating professional Word documents from markdown or structured content with fast, customized formatting via natural language.
Updated a year ago (2025-10-18 14:56 UTC)
7
1
-
mcp-md-pdf
Workplace & Productivity Developer Tools
sham-devs
A
license
A
quality
D
maintenance
Converts Markdown files to Word (.docx) and PDF documents. Supports .dotx templates for branded styling and batch conversion.
Updated a year ago (2025-10-24 13:05 UTC)
3
1
MIT

MDMagic MCP 서버

설치

Claude Desktop

Cursor

VS Code (MCP 확장 프로그램 사용)

호스팅 버전 (설치 불필요)

주요 기능

도구

convert_document — 입력 옵션

설정

가격

개인정보 보호

문제 해결

로컬 개발

링크

라이선스

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`convert_document` — 입력 옵션