[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-vivekVells--mcp-pandoc":3,"tool-vivekVells--mcp-pandoc":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",148568,2,"2026-04-09T23:34:24",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":100,"forks":101,"last_commit_at":102,"license":103,"difficulty_score":32,"env_os":104,"env_gpu":105,"env_ram":106,"env_deps":107,"category_tags":114,"github_topics":115,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":118,"updated_at":119,"faqs":120,"releases":150},6161,"vivekVells\u002Fmcp-pandoc","mcp-pandoc","MCP server for document format conversion using pandoc.","mcp-pandoc 是一款基于 Model Context Protocol (MCP) 构建的开源服务，旨在利用强大的 Pandoc 引擎实现文档格式的无缝转换。它主要解决了不同文档格式（如 Markdown、HTML、LaTeX、Word 等）之间互转困难、格式容易丢失或结构混乱的痛点，让用户在转换过程中能最大程度保留原文的排版与逻辑结构。\n\n这款工具特别适合开发者、技术写作者、研究人员以及需要频繁处理多格式文档的专业人士。对于正在构建 AI 应用或工作流的开发者而言，mcp-pandoc 提供了标准化的接口，可轻松集成到各类智能体系统中，实现自动化的文档处理流程。普通用户若熟悉命令行或希望通过 AI 助手间接调用，也能从中受益，高效完成格式迁移任务。\n\n其技术亮点在于作为官方收录的 MCP 服务器之一，它不仅支持双向格式转换矩阵，还通过 `convert-contents` 等工具提供灵活的输入输出选项——既可直接处理文本内容，也能操作本地文件路径。目前项目虽处于早期开发阶段（例如 PDF 支持仍在完善中），但已具备扎实的转换核心能力，并配有详细的速查表与示例，帮助用户快速上手","mcp-pandoc 是一款基于 Model Context Protocol (MCP) 构建的开源服务，旨在利用强大的 Pandoc 引擎实现文档格式的无缝转换。它主要解决了不同文档格式（如 Markdown、HTML、LaTeX、Word 等）之间互转困难、格式容易丢失或结构混乱的痛点，让用户在转换过程中能最大程度保留原文的排版与逻辑结构。\n\n这款工具特别适合开发者、技术写作者、研究人员以及需要频繁处理多格式文档的专业人士。对于正在构建 AI 应用或工作流的开发者而言，mcp-pandoc 提供了标准化的接口，可轻松集成到各类智能体系统中，实现自动化的文档处理流程。普通用户若熟悉命令行或希望通过 AI 助手间接调用，也能从中受益，高效完成格式迁移任务。\n\n其技术亮点在于作为官方收录的 MCP 服务器之一，它不仅支持双向格式转换矩阵，还通过 `convert-contents` 等工具提供灵活的输入输出选项——既可直接处理文本内容，也能操作本地文件路径。目前项目虽处于早期开发阶段（例如 PDF 支持仍在完善中），但已具备扎实的转换核心能力，并配有详细的速查表与示例，帮助用户快速上手。无论是日常文档整理还是自动化流水线搭建，mcp-pandoc 都能成为得力的格式转换助手。","[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc.svg)](https:\u002F\u002Fpypi.python.org\u002Fpypi\u002Fmcp-pandoc)\n[![CI](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml)\n\u003Cbr \u002F>\n\n![image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_593eb677ed84.png)\n\n\u003C!-- [![Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_72b44b8ad861.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Fmcp-pandoc) -->\n\u003C!-- ![PyPI - Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc?style=social) -->\n\n\u003C!--\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc.svg)](https:\u002F\u002Fpypi.python.org\u002Fpypi\u002Fmcp-pandoc)\n[![CI](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml)\n\u003Ca href=\"https:\u002F\u002Fsmithery.ai\u002Fserver\u002Fmcp-pandoc\">\u003Cimg alt=\"Smithery Badge\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2ab22774b7ca.png\">\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fxyzzgaj9bk\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_89f2d605b343.png\" \u002F>\u003C\u002Fa> \n-->\n[![MseeP.ai Security Assessment Badge](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_5f4c6e0d5e14.png)](https:\u002F\u002Fmseep.ai\u002Fapp\u002Fvivekvells-mcp-pandoc)\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fxyzzgaj9bk\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_89f2d605b343.png\" \u002F>\n\n# mcp-pandoc: A Document Conversion MCP Server\n\n> Officially included in the [Model Context Protocol servers](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fservers\u002Fblob\u002Fmain\u002FREADME.md) open-source project. 🎉\n\n## Overview\n\nA Model Context Protocol server for document format conversion using [pandoc](https:\u002F\u002Fpandoc.org\u002Findex.html). This server provides tools to transform content between different document formats while preserving formatting and structure.\n\nPlease note that mcp-pandoc is currently in early development. PDF support is under development, and the functionality and available tools are subject to change and expansion as we continue to improve the server.\n\nCredit: This project uses the [Pandoc Python package](https:\u002F\u002Fpypi.org\u002Fproject\u002Fpandoc\u002F) for document conversion, forming the foundation for this project.\n\n## 📋 Quick Reference\n\n**New to mcp-pandoc?** Check out **[📖 CHEATSHEET.md](CHEATSHEET.md)** for\n\n- ⚡ Copy-paste examples for all formats\n- 🔄 Bidirectional conversion matrix\n- 🎯 Common workflows and pro tips\n- 🌟 Reference document styling guide\n\n_Perfect for quick lookups and getting started fast!_\n\n## Demo\n\n[![mcp-pandoc - v1: Seamless Document Format Conversion for Claude using MCP server](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_7bb634f0bc73.jpg)](https:\u002F\u002Fyoutu.be\u002FvN3VOb0rygM)\n\n> 🎥 [Watch on YouTube](https:\u002F\u002Fyoutu.be\u002FvN3VOb0rygM)\n\n\u003Cdetails>\n\u003Csummary>Screenshots\u003C\u002Fsummary>\n\n\u003Cimg width=\"2407\" alt=\"Screenshot 2024-12-26 at 3 33 54 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_d1d1a75bff7b.png\" \u002F>\n\u003Cimg width=\"2052\" alt=\"Screenshot 2024-12-26 at 3 38 24 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_ec39f3b93cbc.png\" \u002F>\n\u003Cimg width=\"1498\" alt=\"Screenshot 2024-12-26 at 3 40 51 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2f1655090b74.png\" \u002F>\n\u003Cimg width=\"760\" alt=\"Screenshot 2024-12-26 at 3 41 20 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2475a7981079.png\" \u002F>\n\u003Cimg width=\"1493\" alt=\"Screenshot 2024-12-26 at 3 50 27 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_cf70c73841e9.png\" \u002F>\n\u003C\u002Fdetails>\n\nMore to come...\n\n## Tools\n\n1. `convert-contents`\n   - Transforms content between supported formats\n   - Inputs:\n     - `contents` (string): Source content to convert (required if input_file not provided)\n     - `input_file` (string): Complete path to input file (required if contents not provided)\n     - `input_format` (string): Source format of the content (defaults to markdown)\n     - `output_format` (string): Target format (defaults to markdown)\n     - `output_file` (string): Complete path for output file (required for pdf, docx, rst, latex, epub formats)\n     - `reference_doc` (string): Path to a reference document to use for styling (supported for docx output format)\n     - `defaults_file` (string): Path to a Pandoc defaults file (YAML) containing conversion options\n     - `filters` (array): List of Pandoc filter paths to apply during conversion\n   - Supported input\u002Foutput formats:\n     - markdown\n     - html\n     - pdf\n     - docx\n     - rst\n     - latex\n     - epub\n     - txt\n     - ipynb\n     - odt\n   - Note: For advanced formats (pdf, docx, rst, latex, epub), an output_file path is required\n\n### 🔧 Advanced Features\n\n#### Defaults Files (YAML Configuration)\n\nUse defaults files to create reusable conversion templates with consistent formatting:\n\n```yaml\n# academic-paper.yaml\nfrom: markdown\nto: pdf\nnumber-sections: true\ntoc: true\nmetadata:\n  title: \"Academic Paper\"\n  author: \"Research Team\"\n```\n\nExample usage: `\"Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf\"`\n\n#### Pandoc Filters\n\nApply custom filters for enhanced processing:\n\nExample usage: `\"Convert docs.md to HTML with filters ['\u002Fpath\u002Fto\u002Fmermaid-filter.py'] and save as docs.html\"`\n\n> 💡 **For comprehensive examples and workflows**, see **[CHEATSHEET.md](CHEATSHEET.md)**\n\n## 📊 Supported Formats & Conversions\n\n### Bidirectional Conversion Matrix\n\n| From\\To      | MD  | HTML | TXT | DOCX | PDF | RST | LaTeX | EPUB | IPYNB | ODT |\n| ------------ | --- | ---- | --- | ---- | --- | --- | ----- | ---- | ----- | --- |\n| **Markdown** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **HTML**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **TXT**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **DOCX**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **RST**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **LaTeX**    | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **EPUB**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **IPYNB**    | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **ODT**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n\n### A Note on PDF Support\n\nThis tool uses `pandoc` for conversions, which allows for generating PDF files from the formats listed above. However, converting _from_ a PDF to other formats is not supported. Therefore, PDF should be considered an **output-only** format.\n\n### Format Categories\n\n| Category     | Formats                     | Requirements                    |\n| ------------ | --------------------------- | ------------------------------- |\n| **Basic**    | MD, HTML, TXT, IPYNB, ODT   | None                            |\n| **Advanced** | DOCX, PDF, RST, LaTeX, EPUB | Must specify `output_file` path |\n| **Styled**   | DOCX with reference doc     | Custom template support ⭐      |\n\n### Requirements by Format\n\n- **PDF (.pdf)** - requires TeX Live installation\n- **DOCX (.docx)** - supports custom styling via reference documents\n- **All others** - no additional requirements\n\nNote: For advanced formats:\n\n1. Complete file paths with filename and extension are required\n2. **PDF conversion requires TeX Live installation** (see Critical Requirements section -> For macOS: `brew install texlive`)\n3. When no output path is specified:\n   - Basic formats: Displays converted content in the chat\n   - Advanced formats: May save in system temp directory (\u002Ftmp\u002F on Unix systems)\n\n## Usage & configuration\n\n**NOTE: Ensure to complete installing required packages mentioned below under \"Critical Requirements\".**\n\nTo use the published one\n\n```bash\n{\n  \"mcpServers\": {\n    \"mcp-pandoc\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-pandoc\"]\n    }\n  }\n}\n```\n\n**💡 Quick Start**: See **[CHEATSHEET.md](CHEATSHEET.md)** for copy-paste examples and common workflows.\n\n### ⚠️ Important Notes\n\n#### Critical Requirements\n\n1. **Pandoc Installation**\n\n- **Required**: Install `pandoc` - the core document conversion engine\n- Installation:\n\n  ```bash\n  # macOS\n  brew install pandoc\n\n  # Ubuntu\u002FDebian\n  sudo apt-get install pandoc\n\n  # Windows\n  # Download installer from: https:\u002F\u002Fpandoc.org\u002Finstalling.html\n  ```\n\n- **Verify**: `pandoc --version`\n\n2. **UV package installation**\n\n- **Required**: Install `uv` package (includes `uvx` command)\n- Installation:\n\n  ```bash\n  # macOS\n  brew install uv\n\n  # Windows\u002FLinux\n  pip install uv\n  ```\n\n- **Verify**: `uvx --version`\n\n3. **PDF Conversion Prerequisites:** Only needed if you need to convert & save pdf\n\n- TeX Live must be installed before attempting PDF conversion\n- Installation commands:\n\n  ```bash\n  # Ubuntu\u002FDebian\n  sudo apt-get install texlive-xetex\n\n  # macOS\n  brew install texlive\n\n  # Windows\n  # Install MiKTeX or TeX Live from:\n  # https:\u002F\u002Fmiktex.org\u002F or https:\u002F\u002Ftug.org\u002Ftexlive\u002F\n  ```\n\n4. **File Path Requirements**\n\n- When saving or converting files, you MUST provide complete file paths including filename and extension\n- The tool does not automatically generate filenames or extensions\n\n#### Examples\n\n✅ Correct Usage:\n\n```bash\n# Converting content to PDF\n\"Convert this text to PDF and save as \u002Fpath\u002Fto\u002Fdocument.pdf\"\n\n# Converting between file formats\n\"Convert \u002Fpath\u002Fto\u002Finput.md to PDF and save as \u002Fpath\u002Fto\u002Foutput.pdf\"\n\n# Converting to DOCX with a reference document template\n\"Convert input.md to DOCX using template.docx as reference and save as output.docx\"\n\n# Step-by-step reference document workflow\n\"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx\" or if you already have one, use that\n\"Then convert with custom styling: Convert this text to DOCX using \u002Fpath\u002Fto\u002Fcustom-reference.docx as reference and save as \u002Fpath\u002Fto\u002Fstyled-output.docx\"\n```\n\n❌ Incorrect Usage:\n\n```bash\n# Missing filename and extension\n\"Save this as PDF in \u002Fdocuments\u002F\"\n\n# Missing complete path\n\"Convert this to PDF\"\n\n# Missing extension\n\"Save as \u002Fdocuments\u002Fstory\"\n```\n\n#### Common Issues and Solutions\n\n1. **PDF Conversion Fails**\n\n   - Error: \"xelatex not found\"\n   - Solution: Install TeX Live first (see installation commands above)\n\n2. **File Conversion Fails**\n\n   - Error: \"Invalid file path\"\n   - Solution: Provide complete path including filename and extension\n   - Example: `\u002Fpath\u002Fto\u002Fdocument.pdf` instead of just `\u002Fpath\u002Fto\u002F`\n\n3. **Format Conversion Fails**\n\n   - Error: \"Unsupported format\"\n   - Solution: Use only supported formats:\n     - Basic: txt, html, markdown\n     - Advanced: pdf, docx, rst, latex, epub\n\n4. **Reference Document Issues**\n   - Error: \"Reference document not found\"\n   - Solution: Ensure the reference document path exists and is accessible\n   - Note: Reference documents only work with DOCX output format\n   - How to create: `pandoc -o reference.docx --print-default-data-file reference.docx`\n\n## Quickstart\n\n\u003C!-- Uncomment after smithery fix\n### Install\n\n#### Option 1: Installing manually via claude_desktop_config.json config file\n-->\n\n### Installing manually via claude_desktop_config.json config file\n\n- On MacOS: `open ~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_desktop_config.json`\n- On Windows: `%APPDATA%\u002FClaude\u002Fclaude_desktop_config.json`\n\na) Only for local development & contribution to this repo\n\n\u003Cdetails>\n  \u003Csummary>Development\u002FUnpublished Servers Configuration\u003C\u002Fsummary>\n\nℹ️ Replace \u003CDIRECTORY> with your locally cloned project path\n\n```bash\n\"mcpServers\": {\n  \"mcp-pandoc\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"--directory\",\n      \"\u003CDIRECTORY>\u002Fmcp-pandoc\",\n      \"run\",\n      \"mcp-pandoc\"\n    ]\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\nb) Published Servers Configuration - Consumers should use this config\n\n```bash\n\"mcpServers\": {\n  \"mcp-pandoc\": {\n    \"command\": \"uvx\",\n    \"args\": [\n      \"mcp-pandoc\"\n    ]\n  }\n}\n```\n\n\u003C!-- Uncomment after smithery cli fix\n#### Option 2: To install Published Servers Configuration automatically via Smithery\n\nRun the following bash command to install **published** [mcp-pandoc pypi](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-pandoc) for Claude Desktop automatically via [Smithery](https:\u002F\u002Fsmithery.ai\u002Fserver\u002Fmcp-pandoc):\n\n```bash\nnpx -y @smithery\u002Fcli install mcp-pandoc --client claude\n```\n-->\n\n- If you face any issue, use the \"Published Servers Configuration\" above directly instead of this cli.\n\n**Note**: To use locally configured mcp-pandoc, follow \"Development\u002FUnpublished Servers Configuration\" step above.\n\n## Development\n\n### Testing\n\nTo run the comprehensive test suite and validate all supported bidirectional conversions, use the following command:\n\n```bash\nuv run pytest tests\u002Ftest_conversions.py\n```\n\nThis ensures backward compatibility and verifies the tool's core functionality.\n\n### Building and Publishing\n\nTo prepare the package for distribution:\n\n1. Sync dependencies and update lockfile:\n\n```bash\nuv sync\n```\n\n2. Build package distributions:\n\n```bash\nuv build\n```\n\nThis will create source and wheel distributions in the `dist\u002F` directory.\n\n3. Publish to PyPI:\n\n```bash\nuv publish\n```\n\nNote: You'll need to set PyPI credentials via environment variables or command flags:\n\n- Token: `--token` or `UV_PUBLISH_TOKEN`\n- Or username\u002Fpassword: `--username`\u002F`UV_PUBLISH_USERNAME` and `--password`\u002F`UV_PUBLISH_PASSWORD`\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Finspector).\n\nYou can launch the MCP Inspector via [`npm`](https:\u002F\u002Fdocs.npmjs.com\u002Fdownloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol\u002Finspector uv --directory \u002FUsers\u002Fvivekvells\u002FDesktop\u002Fcode\u002Fai\u002Fmcp-pandoc run mcp-pandoc\n```\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.\n\n---\n\n## Contributing\n\nWe welcome contributions to enhance mcp-pandoc! Here's how you can get involved:\n\n1. **Report Issues**: Found a bug or have a feature request? Open an issue on our [GitHub Issues](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues) page.\n2. **Submit Pull Requests**: Improve the codebase or add features by creating a pull request.\n\n---\n","[![下载量](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc.svg)](https:\u002F\u002Fpypi.python.org\u002Fpypi\u002Fmcp-pandoc)\n[![CI](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml)\n\u003Cbr \u002F>\n\n![image](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_593eb677ed84.png)\n\n\u003C!--\n[![下载量](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_72b44b8ad861.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Fmcp-pandoc)\n![PyPI - 下载量](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc?style=social)\n-->\n\n\u003C!--\n[![下载量](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-pandoc.svg)](https:\u002F\u002Fpypi.python.org\u002Fpypi\u002Fmcp-pandoc)\n[![CI](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Factions\u002Fworkflows\u002Fci.yml)\n\u003Ca href=\"https:\u002F\u002Fsmithery.ai\u002Fserver\u002Fmcp-pandoc\">\u003Cimg alt=\"Smithery Badge\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2ab22774b7ca.png\">\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fxyzzgaj9bk\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_89f2d605b343.png\" \u002F>\u003C\u002Fa> \n-->\n[![MseeP.ai 安全评估徽章](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_5f4c6e0d5e14.png)](https:\u002F\u002Fmseep.ai\u002Fapp\u002Fvivekvells-mcp-pandoc)\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fxyzzgaj9bk\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_89f2d605b343.png\" \u002F>\u003C\u002Fa>\n\n# mcp-pandoc：文档转换 MCP 服务器\n\n> 正式纳入 [Model Context Protocol 服务器](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fservers\u002Fblob\u002Fmain\u002FREADME.md) 开源项目。🎉\n\n## 概述\n\n基于 [pandoc](https:\u002F\u002Fpandoc.org\u002Findex.html) 的文档格式转换 Model Context Protocol 服务器。该服务器提供工具，可在不同文档格式之间转换内容，同时保留格式和结构。\n\n请注意，mcp-pandoc 目前仍处于早期开发阶段。PDF 支持正在开发中，随着我们不断改进服务器，其功能和可用工具可能会发生变化并进一步扩展。\n\n致谢：本项目使用了 [Pandoc Python 包](https:\u002F\u002Fpypi.org\u002Fproject\u002Fpandoc\u002F) 进行文档转换，这是该项目的基础。\n\n## 📋 快速参考\n\n**初次使用 mcp-pandoc？** 请查看 **[📖 CHEATSHEET.md](CHEATSHEET.md)**，了解：\n\n- ⚡ 所有格式的复制粘贴示例\n- 🔄 双向转换矩阵\n- 🎯 常见工作流程和实用技巧\n- 🌟 文档样式参考指南\n\n_非常适合快速查找和快速上手！_\n\n## 演示\n\n[![mcp-pandoc - v1：使用 MCP 服务器为 Claude 提供无缝文档格式转换](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_7bb634f0bc73.jpg)](https:\u002F\u002Fyoutu.be\u002FvN3VOb0rygM)\n\n> 🎥 [在 YouTube 上观看](https:\u002F\u002Fyoutu.be\u002FvN3VOb0rygM)\n\n\u003Cdetails>\n\u003Csummary>截图\u003C\u002Fsummary>\n\n\u003Cimg width=\"2407\" alt=\"Screenshot 2024-12-26 at 3 33 54 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_d1d1a75bff7b.png\" \u002F>\n\u003Cimg width=\"2052\" alt=\"Screenshot 2024-12-26 at 3 38 24 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_ec39f3b93cbc.png\" \u002F>\n\u003Cimg width=\"1498\" alt=\"Screenshot 2024-12-26 at 3 40 51 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2f1655090b74.png\" \u002F>\n\u003Cimg width=\"760\" alt=\"Screenshot 2024-12-26 at 3 41 20 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_2475a7981079.png\" \u002F>\n\u003Cimg width=\"1493\" alt=\"Screenshot 2024-12-26 at 3 50 27 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_readme_cf70c73841e9.png\" \u002F>\n\u003C\u002Fdetails>\n\n更多内容即将推出……\n\n## 工具\n\n1. `convert-contents`\n   - 在支持的格式之间转换内容\n   - 输入：\n     - `contents`（字符串）：要转换的源内容（如果未提供 input_file，则为必填项）\n     - `input_file`（字符串）：输入文件的完整路径（如果未提供 contents，则为必填项）\n     - `input_format`（字符串）：内容的源格式（默认为 markdown）\n     - `output_format`（字符串）：目标格式（默认为 markdown）\n     - `output_file`（字符串）：输出文件的完整路径（对于 pdf、docx、rst、latex、epub 格式，此选项为必填项）\n     - `reference_doc`（字符串）：用于样式的参考文档路径（仅适用于 docx 输出格式）\n     - `defaults_file`（字符串）：包含转换选项的 Pandoc 默认配置文件（YAML）路径\n     - `filters`（数组）：转换过程中要应用的 Pandoc 过滤器路径列表\n   - 支持的输入\u002F输出格式：\n     - markdown\n     - html\n     - pdf\n     - docx\n     - rst\n     - latex\n     - epub\n     - txt\n     - ipynb\n     - odt\n   - 注意：对于高级格式（pdf、docx、rst、latex、epub），必须指定 output_file 路径\n\n### 🔧 高级功能\n\n#### 默认配置文件（YAML 配置）\n\n使用默认配置文件创建可重复使用的转换模板，以保持一致的格式：\n\n```yaml\n# academic-paper.yaml\nfrom: markdown\nto: pdf\nnumber-sections: true\ntoc: true\nmetadata:\n  title: \"学术论文\"\n  author: \"研究团队\"\n```\n\n使用示例：“使用 defaults academic-paper.yaml 将 paper.md 转换为 PDF，并保存为 paper.pdf”\n\n#### Pandoc 过滤器\n\n应用自定义过滤器以增强处理效果：\n\n使用示例：“将 docs.md 转换为 HTML，使用过滤器 ['\u002Fpath\u002Fto\u002Fmermaid-filter.py']，并保存为 docs.html”\n\n> 💡 **有关全面示例和工作流程，请参阅 [CHEATSHEET.md](CHEATSHEET.md)**\n\n## 📊 支持的格式与转换\n\n### 双向转换矩阵\n\n| 来源\\目标      | MD  | HTML | TXT | DOCX | PDF | RST | LaTeX | EPUB | IPYNB | ODT |\n| ------------ | --- | ---- | --- | ---- | --- | --- | ----- | ---- | ----- | --- |\n| **Markdown** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **HTML**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **TXT**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **DOCX**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **RST**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **LaTeX**    | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **EPUB**     | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **IPYNB**    | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n| **ODT**      | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |\n\n### 关于 PDF 支持的说明\n\n此工具使用 `pandoc` 进行转换，可以从上述格式生成 PDF 文件。然而，不支持从 PDF 转换为其他格式。因此，PDF 应被视为仅用于输出的格式。\n\n### 格式分类\n\n| 类别     | 格式                     | 要求                    |\n| -------- | --------------------------- | ----------------------- |\n| **基础** | MD、HTML、TXT、IPYNB、ODT   | 无                      |\n| **高级** | DOCX、PDF、RST、LaTeX、EPUB | 必须指定 `output_file` 路径 |\n| **带样式** | 带参考文档的 DOCX         | 自定义模板支持 ⭐      |\n\n### 格式要求\n\n- **PDF (.pdf)** - 需要安装 TeX Live\n- **DOCX (.docx)** - 支持通过参考文档自定义样式\n- **其他所有格式** - 无额外要求\n\n注意：对于高级格式：\n\n1. 必须提供包含文件名和扩展名的完整文件路径\n2. **PDF 转换需要安装 TeX Live**（参见“关键要求”部分 -> 对于 macOS：`brew install texlive`）\n3. 如果未指定输出路径：\n   - 基本格式：转换后的内容会显示在聊天中\n   - 高级格式：可能会保存到系统临时目录（Unix 系统上为 \u002Ftmp\u002F）\n\n## 使用与配置\n\n**注意：请确保按照下方“关键要求”中的说明完成所需软件包的安装。**\n\n使用已发布的版本：\n\n```bash\n{\n  \"mcpServers\": {\n    \"mcp-pandoc\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-pandoc\"]\n    }\n  }\n}\n```\n\n**💡 快速入门**：请参阅 **[CHEATSHEET.md](CHEATSHEET.md)**，获取可复制粘贴的示例及常用工作流程。\n\n### ⚠️ 重要提示\n\n#### 关键要求\n\n1. **Pandoc 安装**\n\n- **必需**：安装 `pandoc` - 核心文档转换引擎\n- 安装方法：\n\n  ```bash\n  # macOS\n  brew install pandoc\n\n  # Ubuntu\u002FDebian\n  sudo apt-get install pandoc\n\n  # Windows\n  # 从 https:\u002F\u002Fpandoc.org\u002Finstalling.html 下载安装程序\n  ```\n\n- **验证**：`pandoc --version`\n\n2. **UV 包安装**\n\n- **必需**：安装 `uv` 包（包含 `uvx` 命令）\n- 安装方法：\n\n  ```bash\n  # macOS\n  brew install uv\n\n  # Windows\u002FLinux\n  pip install uv\n  ```\n\n- **验证**：`uvx --version`\n\n3. **PDF 转换前提条件**：仅在需要转换并保存 PDF 时才需安装\n\n- 在尝试 PDF 转换之前，必须先安装 TeX Live\n- 安装命令：\n\n  ```bash\n  # Ubuntu\u002FDebian\n  sudo apt-get install texlive-xetex\n\n  # macOS\n  brew install texlive\n\n  # Windows\n  # 从以下网址安装 MiKTeX 或 TeX Live：\n  # https:\u002F\u002Fmiktex.org\u002F 或 https:\u002F\u002Ftug.org\u002Ftexlive\u002F\n  ```\n\n4. **文件路径要求**\n\n- 在保存或转换文件时，必须提供包含文件名和扩展名的完整文件路径\n- 工具不会自动生成文件名或扩展名\n\n#### 示例\n\n✅ 正确用法：\n\n```bash\n# 将内容转换为 PDF 并保存为 \u002Fpath\u002Fto\u002Fdocument.pdf\n“将这段文字转换为 PDF，并保存为 \u002Fpath\u002Fto\u002Fdocument.pdf”\n\n# 在不同文件格式之间转换\n“将 \u002Fpath\u002Fto\u002Finput.md 转换为 PDF，并保存为 \u002Fpath\u002Fto\u002Foutput.pdf”\n\n# 使用参考文档模板将 Markdown 转换为 DOCX\n“使用 template.docx 作为参考，将 input.md 转换为 DOCX，并保存为 output.docx”\n\n# 分步参考文档工作流程\n“首先创建一个参考文档：pandoc -o custom-reference.docx --print-default-data-file reference.docx”，或者如果你已经有现成的参考文档，就直接使用它。\n“然后进行自定义样式转换：将这段文字转换为 DOCX，使用 \u002Fpath\u002Fto\u002Fcustom-reference.docx 作为参考，并保存为 \u002Fpath\u002Fto\u002Fstyled-output.docx”\n```\n\n❌ 错误用法：\n\n```bash\n# 缺少文件名和扩展名\n“把这个保存为 PDF，放在 \u002Fdocuments\u002F 目录下”\n\n# 缺少完整路径\n“把这个转换为 PDF”\n\n# 缺少扩展名\n“保存为 \u002Fdocuments\u002Fstory”\n```\n\n#### 常见问题及解决方案\n\n1. **PDF 转换失败**\n\n   - 错误信息：“xelatex 未找到”\n   - 解决方案：先安装 TeX Live（参见上述安装命令）\n\n2. **文件转换失败**\n\n   - 错误信息：“无效的文件路径”\n   - 解决方案：提供包含文件名和扩展名的完整路径\n   - 示例：`\u002Fpath\u002Fto\u002Fdocument.pdf` 而不是仅仅 `\u002Fpath\u002Fto\u002F`\n\n3. **格式转换失败**\n\n   - 错误信息：“不支持的格式”\n   - 解决方案：仅使用支持的格式：\n     - 基本格式：txt、html、markdown\n     - 高级格式：pdf、docx、rst、latex、epub\n\n4. **参考文档问题**\n   - 错误信息：“参考文档未找到”\n   - 解决方案：确保参考文档的路径存在且可访问\n   - 注意：参考文档仅适用于 DOCX 输出格式\n   - 如何创建：`pandoc -o reference.docx --print-default-data-file reference.docx`\n\n## 快速入门\n\n\u003C!-- 待 smithery 修复后取消注释\n### 安装\n\n#### 方法一：通过 claude_desktop_config.json 配置文件手动安装\n-->\n\n### 通过 claude_desktop_config.json 配置文件手动安装\n\n- 在 macOS 上：`open ~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_desktop_config.json`\n- 在 Windows 上：`%APPDATA%\u002FClaude\u002Fclaude_desktop_config.json`\n\na) 仅用于本地开发及向本仓库贡献代码\n\n\u003Cdetails>\n  \u003Csummary>开发\u002F未发布服务器配置\u003C\u002Fsummary>\n\nℹ️ 将 \u003CDIRECTORY> 替换为你本地克隆的项目路径\n\n```bash\n\"mcpServers\": {\n  \"mcp-pandoc\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"--directory\",\n      \"\u003CDIRECTORY>\u002Fmcp-pandoc\",\n      \"run\",\n      \"mcp-pandoc\"\n    ]\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\nb) 已发布服务器配置 - 消费者应使用此配置\n\n```bash\n\"mcpServers\": {\n  \"mcp-pandoc\": {\n    \"command\": \"uvx\",\n    \"args\": [\n      \"mcp-pandoc\"\n    ]\n  }\n}\n```\n\n\u003C!-- 待 smithery cli 修复后取消注释\n#### 方法二：通过 Smithery 自动安装已发布服务器配置\n\n运行以下 bash 命令，即可通过 [Smithery](https:\u002F\u002Fsmithery.ai\u002Fserver\u002Fmcp-pandoc) 自动为 Claude Desktop 安装 **已发布** 的 [mcp-pandoc pypi](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-pandoc)：\n\n```bash\nnpx -y @smithery\u002Fcli install mcp-pandoc --client claude\n```\n-->\n\n- 如果遇到任何问题，请直接使用上方的“已发布服务器配置”，而不是使用此 CLI。\n\n**注意**：若要使用本地配置的 mcp-pandoc，请按照上方的“开发\u002F未发布服务器配置”步骤操作。\n\n## 开发\n\n### 测试\n\n要运行全面的测试套件并验证所有支持的双向转换功能，可以使用以下命令：\n\n```bash\nuv run pytest tests\u002Ftest_conversions.py\n```\n\n这将确保向后兼容性，并验证工具的核心功能。\n\n### 构建与发布\n\n为准备分发软件包：\n\n1. 同步依赖并更新锁定文件：\n\n```bash\nuv sync\n```\n\n2. 构建软件包分发文件：\n\n```bash\nuv build\n```\n\n这将在 `dist\u002F` 目录下生成源码和轮子分发文件。\n\n3. 发布到 PyPI：\n\n```bash\nuv publish\n```\n\n注意：你需要通过环境变量或命令行参数设置 PyPI 凭证：\n\n- Token：`--token` 或 `UV_PUBLISH_TOKEN`\n- 或用户名\u002F密码：`--username`\u002F`UV_PUBLISH_USERNAME` 和 `--password`\u002F`UV_PUBLISH_PASSWORD`\n\n### 调试\n\n由于 MCP 服务器通过标准输入输出运行，调试可能较为困难。为了获得最佳调试体验，我们强烈建议使用 [MCP Inspector](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Finspector)。\n\n你可以通过 [`npm`](https:\u002F\u002Fdocs.npmjs.com\u002Fdownloading-and-installing-node-js-and-npm) 使用以下命令启动 MCP 侦查器：\n\n```bash\nnpx @modelcontextprotocol\u002Finspector uv --directory \u002FUsers\u002Fvivekvells\u002FDesktop\u002Fcode\u002Fai\u002Fmcp-pandoc run mcp-pandoc\n```\n\n启动后，侦查器会显示一个 URL，你可以在浏览器中访问该 URL 来开始调试。\n\n---\n\n## 贡献\n\n我们欢迎对 mcp-pandoc 的贡献！以下是您可以参与的方式：\n\n1. **报告问题**：发现 bug 或有功能需求？请在我们的 [GitHub Issues](https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues) 页面上提交一个问题。\n2. **提交 Pull Request**：通过创建 Pull Request 来改进代码库或添加新功能。\n\n---","# mcp-pandoc 快速上手指南\n\nmcp-pandoc 是一个基于 Model Context Protocol (MCP) 的文档格式转换服务器，利用强大的 [Pandoc](https:\u002F\u002Fpandoc.org) 引擎，帮助你在不同文档格式（如 Markdown, HTML, PDF, DOCX 等）之间无缝转换。\n\n## 1. 环境准备\n\n在开始之前，请确保你的系统已安装以下核心依赖。**PDF 转换功能需要额外的 LaTeX 环境支持**。\n\n### 核心依赖\n*   **Pandoc**: 文档转换核心引擎。\n*   **UV**: Python 包管理工具（用于运行 `uvx` 命令）。\n\n### 可选依赖（仅当需要生成 PDF 时）\n*   **TeX Live**: PDF 渲染引擎。如果不安装此组件，将无法生成 PDF 文件。\n\n### 安装命令\n\n**macOS (推荐使用 Homebrew):**\n```bash\n# 安装 Pandoc\nbrew install pandoc\n\n# 安装 UV\nbrew install uv\n\n# 安装 TeX Live (仅用于 PDF 输出)\nbrew install texlive\n```\n\n**Ubuntu\u002FDebian:**\n```bash\n# 安装 Pandoc\nsudo apt-get install pandoc\n\n# 安装 UV\npip install uv\n\n# 安装 TeX Live (仅用于 PDF 输出)\nsudo apt-get install texlive-xetex\n```\n\n**Windows:**\n1.  **Pandoc**: 下载并运行安装包：https:\u002F\u002Fpandoc.org\u002Finstalling.html\n2.  **UV**: 打开 PowerShell 或 CMD 运行 `pip install uv`\n3.  **TeX Live**: 下载并安装 MiKTeX 或 TeX Live：https:\u002F\u002Fmiktex.org\u002F 或 https:\u002F\u002Ftug.org\u002Ftexlive\u002F\n\n### 验证安装\n在终端执行以下命令确认安装成功：\n```bash\npandoc --version\nuvx --version\n```\n\n---\n\n## 2. 安装步骤 (配置 MCP 服务器)\n\n你需要将 mcp-pandoc 配置到你的 MCP 客户端中（以 Claude Desktop 为例）。\n\n### 配置文件路径\n*   **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n*   **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### 配置内容\n打开上述配置文件，在 `mcpServers` 对象中添加以下配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-pandoc\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-pandoc\"]\n    }\n  }\n}\n```\n\n保存文件后，重启 Claude Desktop 即可生效。\n\n---\n\n## 3. 基本使用\n\n配置完成后，你可以直接在对话中请求进行文档转换。mcp-pandoc 支持 Markdown, HTML, TXT, DOCX, PDF, RST, LaTeX, EPUB, IPYNB, ODT 等多种格式的互转。\n\n### ⚠️ 重要使用规则\n1.  **完整路径**: 对于高级格式（PDF, DOCX, RST, LaTeX, EPUB），**必须**提供包含文件名和扩展名的完整输出路径（例如 `\u002FUsers\u002Fname\u002Fdoc.pdf`），不能只提供目录。\n2.  **PDF 限制**: PDF 仅支持作为**输出**格式，不支持从 PDF 转换为其他格式。\n\n### 使用示例\n\n#### 场景 1：将文本内容直接转换为 PDF\n> “将这段文字转换为 PDF 格式，并保存为 `\u002FUsers\u002Fmyname\u002Fdocuments\u002Freport.pdf`\"\n\n#### 场景 2：转换本地文件格式 (Markdown 转 Word)\n> “将 `\u002FUsers\u002Fmyname\u002Fnotes.md` 转换为 DOCX 格式，保存为 `\u002FUsers\u002Fmyname\u002Fnotes.docx`\"\n\n#### 场景 3：使用参考文档进行样式化转换 (DOCX)\n如果你希望生成的 Word 文档遵循特定的样式模板：\n1.  首先准备一个参考文档（或使用现有的 `.docx` 文件）。\n2.  发送指令：\n> “将 `input.md` 转换为 DOCX 格式，使用 `\u002Fpath\u002Fto\u002Ftemplate.docx` 作为参考样式文档，输出保存为 `\u002Fpath\u002Fto\u002Foutput.docx`\"\n\n#### 场景 4：简单格式互转 (无需指定输出文件)\n对于基础格式（如 Markdown 转 HTML 文本），可以直接在对话框中查看结果：\n> “将以下内容转换为 HTML 格式：[在此粘贴内容]\"","某技术团队需要将分散在 GitHub Wiki（Markdown）、内部文档系统（HTML）和旧版报告（Docx）中的多源内容，统一整合为一份格式规范的 PDF 产品手册供客户查阅。\n\n### 没有 mcp-pandoc 时\n- **手动转换繁琐**：开发者需逐个打开不同文件，手动复制内容到 Word 或在线转换工具，再另存为 PDF，重复劳动且极易出错。\n- **格式严重丢失**：在不同格式间反复拷贝时，代码块高亮、数学公式、表格结构经常错乱，后期人工修复排版耗时甚至超过编写时间。\n- **自动化断点**：无法将文档转换环节嵌入 CI\u002FCD 流水线，每次发布新版本手册都依赖人工介入，导致交付周期长且版本难以同步。\n- **上下文割裂**：AI 助手虽能生成内容，但受限于本地环境缺乏通用转换能力，无法直接输出最终交付格式，迫使人员在 AI 对话与本地软件间频繁切换。\n\n### 使用 mcp-pandoc 后\n- **一键智能流转**：通过自然语言指令，mcp-pandoc 直接读取 Markdown、HTML 或 Docx 源文件，自动调用 Pandoc 内核将其精准转换为目标格式。\n- **结构完美保留**：工具在转换过程中自动维护代码语法高亮、目录层级及复杂表格样式，确保生成的 PDF 专业美观，无需二次调整。\n- **工作流无缝集成**：作为 MCP 服务器，mcp-pandoc 可被 AI Agent 直接调度，实现从“内容生成”到“格式交付”的全自动闭环，显著提升发布效率。\n- **沉浸式体验**：开发者只需在对话框中描述需求（如“将 wiki 目录转为带页码的 PDF\"），mcp-pandoc 即在后台静默完成所有技术细节，让人专注于内容本身。\n\nmcp-pandoc 的核心价值在于消除了多格式文档协作中的技术摩擦，让内容创作与格式交付像呼吸一样自然流畅。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FvivekVells_mcp-pandoc_593eb677.png","vivekVells","Vivek Vellaiyappan ","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FvivekVells_cca75469.jpg","Dreamer. Engineer. Loves to Code & Architect software designs. Prepping up to do amazing things in my field. ",null,"https:\u002F\u002Fvivekvells.com","https:\u002F\u002Fgithub.com\u002FvivekVells",[81,85,89,92,96],{"name":82,"color":83,"percentage":84},"Python","#3572A5",96.1,{"name":86,"color":87,"percentage":88},"HTML","#e34c26",1.5,{"name":90,"color":91,"percentage":88},"Dockerfile","#384d54",{"name":93,"color":94,"percentage":95},"Jupyter Notebook","#DA5B0B",0.6,{"name":97,"color":98,"percentage":99},"TeX","#3D6117",0.2,524,56,"2026-04-09T08:49:03","MIT","Linux, macOS, Windows","不需要 GPU","未说明",{"notes":108,"python":109,"dependencies":110},"1. 必须安装 Pandoc 作为核心转换引擎。2. 必须安装 uv 包管理器（包含 uvx 命令）。3. 若需转换为 PDF 格式，必须额外安装 TeX Live (macOS 用 brew install texlive, Ubuntu\u002FDebian 用 apt-get install texlive-xetex, Windows 用 MiKTeX 或 TeX Live)。4. 转换高级格式（如 PDF, DOCX）时必须指定完整的输出文件路径（含文件名和扩展名）。5. PDF 仅支持作为输出格式，不支持从 PDF 转换。","未说明 (需安装 uv 包管理器)",[111,112,113],"pandoc","uv","texlive (仅 PDF 输出需要)",[13,52],[111,116,117],"pandoc-markdown","pandoc-template","2026-03-27T02:49:30.150509","2026-04-10T15:55:38.424579",[121,126,131,136,141,146],{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},27902,"MCP 服务器加载失败或无法启动怎么办？","此问题通常由旧版本 SDK 兼容性引起，已在 v0.8.0 中修复。请执行以下步骤升级：\n1. 运行命令升级：`uvx install --upgrade mcp-pandoc` 或重新安装 `uvx install mcp-pandoc`。\n2. 确保配置文件正确：\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-pandoc\": {\n         \"command\": \"uvx\",\n         \"args\": [\"mcp-pandoc\"]\n       }\n     }\n   }\n   ```\n3. 重启 MCP 客户端（如 Claude Desktop），检查服务器列表中出现 mcp-pandoc 且状态为已连接。","https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues\u002F7",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},27903,"在 Cursor IDE 中启用 mcp-pandoc 后出现“连接模型提供商困难”的错误如何解决？","这是由于 JSON Schema 兼容性问题导致的，已在 v0.8.0 中通过升级 MCP SDK (1.1.0 → 1.13.1) 解决。\n解决方法：\n1. 升级包：`uvx install --upgrade mcp-pandoc`。\n2. 在 `mcp.json` 中保留以下配置：\n   ```json\n   \"mcp-pandoc\": {\n     \"command\": \"uvx\",\n     \"args\": [\"mcp-pandoc\"]\n   }\n   ```\n3. 重启 Cursor IDE，错误应消失，可正常进行 Markdown 转 DOCX 等操作。","https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues\u002F22",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},27904,"Claude Desktop 报错 'spawn uvx ENOENT' 或服务器断开连接怎么办？","该错误表示系统找不到 `uvx` 命令，通常是因为未安装 `uv` 包管理器。\n解决方案：\n1. 确保已安装 `uv` (包含 uvx)。可以通过官方脚本安装：`curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh`。\n2. 验证安装：在终端运行 `uvx --version` 确认有输出。\n3. 如果使用的是 npx 或其他启动方式，请改为直接使用 `uvx` 命令，并确保其在系统 PATH 中。\n4. 重启 Claude Desktop 客户端。","https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues\u002F18",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},27905,"遇到 'name false is not defined' 的 Python 错误如何处理？","这是一个代码逻辑 Bug，已在 v0.8.1 版本中修复。\n解决方法：\n1. 升级到最新版本：`uvx install --upgrade mcp-pandoc` (确保版本 >= 0.8.1)。\n2. 如果问题依旧，请检查是否缓存了旧版本，尝试彻底卸载后重装。\n3. 维护者已添加预提交钩子（pre-commit hook）和 CI 检查以防止此类问题再次发生。","https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues\u002F32",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},27906,"mcp-pandoc 是否支持中文内容处理？","mcp-pandoc 本身作为转换工具，主要依赖底层的 Pandoc 和 LLM 的能力。对于中文内容的支持：\n1. 确保安装的 Pandoc 版本支持中文编码（通常现代版本均支持）。\n2. 中文处理能力更多取决于你连接的 LLM（大语言模型）是否支持中文，而非 MCP 服务器本身。\n3. 如果在使用中遇到乱码，请检查文件编码是否为 UTF-8。","https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fissues\u002F21",{"id":147,"question_zh":148,"answer_zh":149,"source_url":130},27907,"不同 MCP 客户端（如 Augment, Roo Cline）的兼容性表现如何？","在 v0.8.0 之前，部分客户端（如 Cursor, Augment）可能会遇到连接错误，而 Roo Cline 可能表现正常。这是因为不同客户端对 JSON Schema 的严格程度不同。\n现状：\n- 自 v0.8.0 起，通过升级 SDK 实现了通用兼容性，理论上适用于所有标准 MCP 客户端（包括 Claude Desktop, Cursor, Augment 等）。\n- 如果遇到特定客户端问题，请首先确保已升级到最新版 `uvx install --upgrade mcp-pandoc`。",[151,156,161,166,171],{"id":152,"version":153,"summary_zh":154,"released_at":155},188849,"v0.8.1","## 变更内容\n* 修复：将 `false` 改为 `False`，由 @acdzh 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F31 中完成\n\n## 新贡献者\n* @acdzh 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F31 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fcompare\u002Fv0.8.0...v0.8.1","2025-08-30T01:27:22",{"id":157,"version":158,"summary_zh":159,"released_at":160},188850,"v0.8.0","**完整变更日志**：https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fcompare\u002Fv0.5.0...v0.8.0\n\n修复：通用 MCP 客户端兼容性及 SDK 升级至 v0.8.0 - 解决 4 个严重问题 #28 @vivekVells","2025-08-24T17:37:32",{"id":162,"version":163,"summary_zh":164,"released_at":165},188851,"v0.5.0","## 变更内容\n* 功能：增强了默认配置文件和过滤器的支持（基于 @dipseth 的 PR #24），由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F25 中实现。\n* 增加了 Pandoc 默认配置文件支持，并改进了过滤器路径解析，由 @dipseth 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F24 中实现。\n\n## 新贡献者\n* @dipseth 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F24 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fcompare\u002Fv0.4.0...v0.5.0","2025-07-13T05:22:02",{"id":167,"version":168,"summary_zh":169,"released_at":170},188852,"v0.4.0","## 变更内容\n* 功能新增：由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F23 中添加了对 IPYNB 和 ODT 格式的双向支持。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fcompare\u002Fv0.3.4...v0.4.0","2025-06-29T16:41:08",{"id":172,"version":173,"summary_zh":174,"released_at":175},188853,"v0.3.4","## 变更内容\n* chore：为提高代码清晰度进行了重构，并由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F1 中添加了示例内容。\n* add：由 @punkpeye 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F4 中添加了 MCP 服务器徽章。\n* feat：由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F6 中增加了对 .docx 和 .pdf 格式的支持。\n* Revert：“feat：增加了 .docx 和 .pdf 格式的支持”由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F8 中撤销。\n* build：最近的撤销更改——发布修补版 uv 版本，由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F9 中完成。\n* feat：支持多种格式，并增强了 Pandoc 内容转换器，增加了文件支持和格式处理功能，由 @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F11 中实现。\n* Add：由 @calclavia 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F10 中将 Smithery 添加到 README 文件中。\n* Add：由 @lwsinclair 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F17 中将 MseeP.ai 徽章添加到 README 文件中。\n* Deployment：由 @calclavia 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F13 中提供了 Dockerfile 和 Smithery 配置。\n* added：由 @SundaramManickam 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F20 中添加了用于模板处理的参考文档功能。\n\n## 新贡献者\n* @vivekVells 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F1 中做出了首次贡献。\n* @punkpeye 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F4 中做出了首次贡献。\n* @calclavia 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F10 中做出了首次贡献。\n* @lwsinclair 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F17 中做出了首次贡献。\n* @SundaramManickam 在 https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fpull\u002F20 中做出了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FvivekVells\u002Fmcp-pandoc\u002Fcommits\u002Fv0.3.4","2025-06-29T16:25:06"]