文档生成框架

docgen mcp

AI代理的类型安全文档生成框架，由 类型 以及模型上下文协议（MCP）。通过带有自动验证和PDF编译的结构化JSON生成专业简历、求职信等。

概述

docgen mcp是一个 代码优先文档生成框架 这使得AI代理可以轻松创建专业格式的文档：

• 类型安全 --文档结构定义为Rust类型，具有自动JSON模式生成功能
• AI优化 --发现工具、最佳实践提示和沙盒感知文件处理
• 专业输出 --Typst支持的PDF生成，具有生产质量模板
• 可扩展 --通过定义Rust类型和Typst模板添加新的文档类型

文档类型

• ✅ 简历 --1-2页专业总结（北美行业标准）
• ✅ 求职信 --一页个性化申请信
• 🔲 简历 --综合学术/研究文件（计划中）

sequenceDiagram
    participant Client as AI Agent
    participant Server as docgen-mcp Server
    participant Schema as Schema Generator<br/>(schemars)
    participant Validator as Type Validator<br/>(serde)
    participant Typst as Typst Compiler
    participant FS as File System

    Note over Client,Server: 1. Get Best Practices (Recommended)
    Client->>+Server: tools/call<br/>"get_resume_best_practices"
    Server-->>-Client: Writing guidelines & tips

    Note over Client,Server: 2. Get Schema (Recommended)
    Client->>+Server: tools/call<br/>"get_resume_schema"
    Server->>+Schema: Generate JSON Schema<br/>from Rust types
    Schema-->>-Server: JSON Schema
    Server-->>-Client: Resume schema structure

    Note over Client,Server: 3. Validate (Recommended)
    Client->>+Server: tools/call<br/>"validate_resume"<br/>+ JSON payload
    Server->>+Validator: Deserialize JSON
    Validator-->>-Server: Validation result
    Server-->>-Client: Valid / Error with paths

    Note over Client,Server: 4. Generate Resume
    Client->>+Server: tools/call<br/>"generate_resume"<br/>+ JSON payload + filename
    Server->>+Validator: Deserialize & validate
    Validator-->>-Server: Validated Resume struct
    Server->>Server: Transform to Typst markup
    Server->>+Typst: Compile document
    Typst-->>-Server: PDF bytes
    Server->>+FS: Write to file
    FS-->>-Server: Success
    Server-->>-Client: File path & success message

    Note over Client: AI tells user:<br/>"Resume saved to<br/>john-doe-resume.pdf"

特性

• 类型安全 --文档结构定义为Rust类型 schemars 用于JSON模式生成
• 代码优先 --Rust类型中的单一真实来源，没有模式漂移
• 可扩展 --通过定义Rust类型和Typst模板添加新的文档类型
• 嵌入式编译器 --无需外部Typst安装；编译器在进程内运行
• 双重运输 --支持HTTP/SSE（Claude.ai远程）和stdio（Claude桌面本地）

快速开始

本地开发

# Clone and build
git clone https://github.com/yourname/docgen-mcp
cd docgen-mcp
cargo build --release

# Run the MCP server locally
# (Supports both stdio and HTTP/SSE transports)
./target/release/docgen-mcp

生产部署（铁路）

1. 将您的存储库推送到GitHub
2. 在上创建新项目 铁路
3. 连接您的GitHub存储库
4. 铁路将自动检测Rust项目并构建它
5. 在铁路设置中配置公共域
6. 复制URL以在Claude.ai中使用

MCP配置

对于第ai条（远程MCP-推荐）：

适用于Pro、Max、Team和Enterprise计划。

1. 导航到Claude.ai中的“设置”>“连接器”
2. 选择“添加自定义连接器”
3. 输入您的铁路部署URL（例如。， https://your-app.railway.app)
4. 可选配置OAuth进行身份验证
5. 查看并启用要使用的工具

对于Claude Desktop（本地）：

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "docgen": {
      "command": "/path/to/docgen-mcp"
    }
  }
}

注意：Claude Desktop使用stdio传输，而Claude.ai使用HTTP/SSE传输。

MCP接口

资源

提示

工具

文档类型发现

简历工具

求职信工具

AI代理的推荐工作流程：

1. 发现 --呼叫 get_document_types 了解用户需要哪些文档
2. 学习 --打电话给合适的 get_X_best_practices 用于理解内容指南的工具
3. 结构 --呼叫 get_X_schema 查看预期的JSON结构
4. 聚集 --从用户那里收集信息并构造JSON
5. 验证 --呼叫 validate_X 在生成之前检查结构
6. 生成 --呼叫 generate_X 创建PDF文件

关于沙盒环境的说明： 生成的PDF返回文件路径（本地模式）或下载URL（远程模式）。在沙盒环境中运行的AI代理应该向用户提供URL，而不是试图直接访问文件。

项目结构

docgen-mcp/
├── Cargo.toml
├── src/
│   ├── main.rs              # Entry point, MCP server setup (HTTP/SSE + stdio)
│   ├── mcp/
│   │   ├── mod.rs
│   │   ├── resources.rs     # Schema resource handlers (serves generated schemas)
│   │   ├── prompts.rs       # Best practices prompts
│   │   └── tools.rs         # Generate/validate tool handlers
│   ├── documents/
│   │   ├── mod.rs
│   │   └── resume.rs        # Resume types (Deserialize + Serialize + JsonSchema)
│   ├── typst/
│   │   ├── mod.rs
│   │   ├── world.rs         # Typst World trait implementation
│   │   ├── compiler.rs      # Compilation orchestration
│   │   └── transform.rs     # Rust types → Typst markup codegen
├── templates/
│   └── resume.typ           # Typst template (embedded at compile time)
└── tests/
    ├── integration.rs
    └── fixtures/
        └── sample_resume.json

注： 模式是在运行时使用Rust类型生成的 schemars，消除了对单独JSON模式文件的需要。

建筑

传输层

远程（Claude.ai）： 用于云部署的HTTP/SSE传输 本地（克劳德桌面）： 用于本地子进程通信的stdio传输

数据流

推荐工作流程：

1. 最佳实践 --AI代理调用 get_resume_best_practices 理解指南的工具
2. 架构发现 --AI代理调用 get_resume_schema 查看JSON结构的工具
3. 内容创作 --AI代理从用户那里收集信息，并构建与模式匹配的JSON
4. 验证 --AI代理调用 validate_resume 在生成之前验证结构
5. 生成 --AI代理调用 generate_resume 带有JSON有效载荷（和可选文件名）
6. 转变 --服务器将经过验证的Rust类型转换为Typst标记
7. 编译 --嵌入式Typst编译器呈现文档
8. 文件输出 --PDF保存到工作目录，文件路径返回给AI代理

备选方案（高级）： 代理还可以直接访问MCP资源/提示：

• 资源 docgen://schemas/resume 对于模式
• 提示 resume-best-practices 指南

为什么选择工具而不是base64？

• 保存令牌（无70KB+base64字符串）
• AI代理可以自然地引用文件
• 用户可以立即访问文件
• 整体用户体验更好

关键依赖关系

模式管理

此项目使用 代码优先 模式管理方法：

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, JsonSchema)]
struct Resume {
    basics: Basics,
    work: Vec<WorkExperience>,
    // ...
}

优点：

• 单一真实来源（Rust类型）
• 模式和类型之间没有漂移
• 编译时型安全
• 通过编程生成的JSON模式 schemars
• 类似于Pydantic的方法（类型为合约）

生成的JSON模式通过 docgen://schemas/resume MCP客户端发现和验证的资源。

里程碑

里程碑0：项目脚手架✅

使用双传输支持编译和运行骨架

• [x] 初始化Cargo工作区
• [x] 添加核心依赖项(rmcp 随着 server 和 axum 特征， tokio, serde, serde_json)
• [x] 使用stdio传输创建最小的MCP服务器（Claude Desktop）
• [x] 使用Axum添加HTTP/SSE传输（Claude.ai远程）
• [x] 服务器响应 initialize 在两种运输方式上
• [x] 设置基本项目结构（目录、mod.rs文件）
• [x] 添加CI工作流程（货物检查、剪贴、测试）

可交付成果： 服务器通过stdio和HTTP/SSE传输完成MCP握手✅

实施说明：

• 用过的 cargo add 用于自动版本解析
• 实现 ServerHandler 特质与 get_info() 提供服务器元数据的方法
• 默认为标准模式；通过激活HTTP --http 旗帜或 PORT env 是
• HTTP服务器使用流式HTTP传输（MCP协议版本2025-03-26）
• HTTP服务器绑定到 0.0.0.0 带可配置端口（默认值：3000）
• MCP端点位于 /mcp 用于HTTP模式
• 集成测试验证stdio和HTTP服务器的启动
• 所有CI检查均通过（货物检查、剪贴、测试）

确定的其他任务：

• [x] 添加适当的MCP HTTP/SSE端点（使用流式HTTP传输）
• [x] 在ServerHandler中实现服务器信息元数据（名称、版本）
• [x] 添加MCP协议握手的集成测试

里程碑1：架构资源✅

定义Rust类型并将生成的JSON模式作为MCP资源公开

• [x] 添加 schemars 对Cargo.toml的依赖
• [x] 定义简历Rust类型（从简单开始： Basics, WorkExperience, Education, Skills)
• [x] 衍生 Deserialize, Serialize，以及 JsonSchema 关于类型
• [x] 使用以下命令在运行时生成JSON模式 schemars::schema_for!
• [x] 实施MCP resources/list 处理器
• [x] 实施MCP resources/read 处理程序 docgen://schemas/resume
• [x] 添加资源处理程序和模式生成的测试

可交付成果： 客户端可以通过MCP读取简历模式（由Rust类型生成）✅

实施说明：

• 中定义的简历类型 src/documents/resume.rs 带有完整的schemars注释
• 类型包括： Resume, Basics, Profile, WorkExperience, Education, Skill
• 自由形式 publications 灵活的出版物摘要字段
• 通过以下方式启用资源能力 ServerCapabilities::builder().enable_resources()
• 架构在以下位置公开 docgen://schemas/resume 统一资源标识符
• 在以下位置添加了样品夹具 tests/fixtures/sample_resume.json
• 10个测试，涵盖序列化、反序列化、模式生成和资源处理程序

里程碑2：验证工具✅

接受JSON有效载荷并通过类型反序列化进行验证

• [x] 实施 validate_resume 工具
• [x] 使用 serde_json::from_value 反序列化和验证
• [x] 将serde错误转换为结构化验证错误（路径+消息）
• [x] 添加具有有效/无效夹具的集成测试
• [x] 测试边缘情况（缺少必填字段、类型错误等）

可交付成果： validate_resume 工具返回成功或详细的serde验证错误✅

实施说明：

• 工具在 src/mcp/tools.rs 随着 ValidationResult enum（有效/无效）
• ValidationError struct提供了结构化错误 path 和 message 领域
• Serde错误解析提取字段名并从类型上下文推断路径
• 通过启用工具功能 ServerCapabilities::builder().enable_tools()
• list_tools 和 call_tool 处理程序已连接 ServerHandler
• 通过以下方式返回结构化JSON响应 CallToolResult::structured()
• 为测试边缘情况添加了4个无效的夹具文件
• 17个与工具相关的测试，涵盖有效、无效和边缘情况
• 所有28项测试通过（25个单元+3个集成）

里程碑3：典型集成✅

将最小的Typst文档编译为PDF

• [x] 添加Typst板条箱(typst, typst-pdf, typst-kit, typst-assets)
• [x] 实施 World 记忆编译的特点
• [x] 创建最小简历Typst模板
• [x] 将硬编码内容编译为PDF作为概念证明
• [x] 处理字体加载（通过嵌入 typst-assets 或捆绑子集）

可交付成果： 服务器可以从静态Typst源生成PDF✅

实施说明：

• 添加 typst, typst-pdf，以及 typst-assets 随着 fonts 功能已启用
• 实现 DocgenWorld 使用 typst::World 记忆编译的特点
• 创建 compile 功能 src/typst/compiler.rs 编排PDF生成
• 集成 typst-assets 提供专业字体（Libertinus Serif）
• 添加 pdf-extract 在单元测试中验证PDF内容的开发依赖性
• 26个单元测试+3个集成测试通过

里程碑4：简历生成工具✅

完整管道：JSON→ 类型→ PDF

• [x] 转换 Resume 将结构转换为Typst标记字符串
• [x] 接线 generate_resume 工具：验证→ 变换→ 编译→ save
• [x] 将PDF保存到文件并返回文件路径
• [x] 添加编译失败的错误处理
• [x] 集成测试：JSON示例→ 有效PDF

可交付成果： 端到端简历生成工作✅

实施说明：

• 重新设计 templates/resume.typ 成为一个功能强大、动态的模板
• 实施了专业的“Jake Ryan”布局（中心标题、小帽部分、四象限条目）
• 添加 Project 结构到架构和 location 字段到 WorkExperience 和 Education
• 创建 src/typst/transform.rs 将JSON数据安全地注入Typst
• 实现 generate_resume 结合验证、转换和编译的工具
• 将输出从base64更改为基于文件（节省令牌，更好的AI代理用户体验）
• 添加可选 filename 从名称自动生成的参数
• 增加集成测试超时，以处理增加的二进制大小和启动时间
• 所有测试均已通过✅

里程碑5：最佳实践提示✅

引导LLMs更好地撰写简历

• [x] 撰写简历最佳实践内容（简洁、可操作）
• [x] 实施MCP prompts/list 处理器
• [x] 实施MCP prompts/get 处理程序 resume-best-practices
• [x] 在上下文提示中包含架构引用

可交付成果： 客户可以在生成之前请求指导✅

实施说明：

• 创建 src/mcp/prompts.rs 有全面的简历撰写指南
• 提示包括内容指南（联系信息、摘要、工作经验、教育、技能、项目）
• 写作风格注意事项（简洁、无代词、量化成就等）
• LLM上下文提示中嵌入了完整的JSON模式
• 用于工作流指导的架构URI参考
• 通过启用提示功能 ServerCapabilities::builder().enable_prompts()
• list_prompts 和 get_prompt 处理程序已连接 ServerHandler
• 新增5个与提示相关的测试
• 全部40项测试（37个单元+3集成）通过✅

里程碑6：模板优化✅

专业品质简历输出

• [x] 设计精美的排版模板（干净的排版、间距）
• [x] 支持多个部分（项目、认证、语言等）
• [x] 添加可选模板变体（经典、现代、简约）
• [x] 处理边缘情况（缺少可选字段、内容过长）

可交付成果： 生成的简历看起来很专业✅

实施说明：

• 重新设计的模板，改进了排版（10pt基础，12pt标题，对齐文本）
• 为一致的条目标题添加了辅助函数（4象限网格布局）
• 添加 format-dates 用于一致日期范围格式设置的助手
• 模板中添加了新部分：摘要、证书、奖项、语言、出版物
• 新架构类型： Certification, Award, Language 带有完整的schemars注释
• 位置现在显示在名称下方的标题中
• 专业摘要以斜体文本显示在联系信息下方
• 强大的边缘案例处理能力 if 检查所有可选字段
• 教育部分现在支持亮点（课程作业、荣誉）
• 项目部分现在显示URL和描述
• 当前模板作为“经典”变体；可以通过里程碑7中的模板参数添加其他变体（现代、最小）
• 全部40项测试（37个单元+3集成）通过✅

里程碑7：配置和定制✅

用户对输出的控制

• [x] 添加用于自定义的工具参数（模板变体、强调色、字体）--为保持风格一致而跳过
• [x] 支持页面大小选项（信纸、A4）--跳过以保持风格一致
• [x] 允许自定义部分订购
• [x] 架构中的文档配置选项

可交付成果： 用户可以自定义部分排序，同时保持一致的专业风格✅

实施说明：

• 添加 sectionOrder 字段用于恢复自定义节排序的架构
• 有效部分： education, experience, projects, certifications, awards, publications, skills, languages
• 在以下情况下使用的默认顺序 sectionOrder 未指定
• 从列表中省略部分以完全隐藏它们
• 重构的模板，带有用于动态排序的部分渲染器函数
• 模板使用节调度器模式来实现干净、可维护的代码
• 有意跳过样式自定义（颜色、字体、页面大小），以获得一致的专业输出
• 架构描述记录了所有配置选项
• 全部41项测试（38单元+3集成）通过✅

里程碑8:AI Agent用户体验优化✅

让服务器与任何AI代理协同工作

• [x] 添加方便的工具包装资源/提示以实现可发现性
• [x] 实施 get_resume_schema 工具（包装资源）
• [x] 实施 get_resume_best_practices 工具（包装提示）
• [x] 更新服务器说明，以指导AI代理完成推荐的工作流程
• [x] 将PDF输出从base64更改为基于文件（令牌效率）
• [x] 添加可选 filename 参数到 generate_resume
• [x] 更新工具描述以参考工作流程步骤
• [x] 为新工具和文件输出添加测试

可交付成果： 针对AI代理发现和使用进行了优化的服务器✅

实施说明：

• 添加 get_resume_schema 和 get_resume_best_practices 作为可发现的工具
• 这些包装了现有的资源/提示，提供了语义MCP结构和实用的可发现性
• 服务器指令现在明确地指导AI代理完成5步工作流程
• 改变 generate_resume 从base64编码的PDF输出到文件路径
  • 每份简历可节省70KB+令牌
  • AI代理可以自然地引用文件
  • 更好的用户体验
• 如果没有提供，则自动从简历名称生成文件名
• 更新了所有工具说明，以交叉引用和指导工作流程
• 所有48项测试（45个单元+3集成）通过✅

设计理念：

• “成功之坑”-无论人工智能代理的质量如何，服务器都应该工作良好
• 可发现-关键功能作为代理自然发现的工具公开
• 令牌高效-文件输出而不是base64
• 指导-说明和描述引导代理商采用最佳实践

里程碑9：波兰语和发布

生产就绪

• []全面的错误消息
• []使用登录 tracing
• []性能优化（缓存编译字体，重用编译器状态）
• []文档（README、rustdoc、示例）
• []发布主要平台的二进制文件
• []发布到crates.io（可选）

可交付成果： v1.0版本发布

未来想法

• 其他文档类型 --简历（学术）、发票、报告、提案、案例研究
• 模板市场 --在运行时加载自定义Typst模板
• 多格式导出 --HTML、PNG、DOCX超越PDF
• 流媒体编译 --对于非常大的文档
• WASM构建 --在浏览器环境中运行
• 模板定制 --用户可选择的主题、颜色、字体

发展

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run

# Format and lint
cargo fmt
cargo clippy

许可证

麻省理工学院或阿帕奇-2.0

致谢

• 类型 --核心是令人难以置信的排版系统
• 主控程序 --支持AI工具集成的协议
• JSON简历 --简历图式结构的启示