使用说明
OCR-MCP服务器
项目概述
该项目实现了 模型上下文协议（MCP） 用于批量OCR处理学生文档的服务器。它是一个模块化的流水线，旨在处理大规模手写识别，同时确保数据隐私并保持高文本质量。
关键技术栈：
- FastMCP： 用于快速服务器开发。
- Qwen VL： 通过兼容OpenAI的API实现卓越的手写文本识别（OCR）。
- SQLite（嵌入式）： 用于强大的数据存储、状态管理和工具切换。
- xAI（Grok）： 可选的基于人工智能的文本规范化（人机交互）。
- 紫外线： 用于快速、可重复的依赖关系管理。
- Regex洗涤器： 基于列表的原子PII编辑，保护学生隐私。
架构：“数据库优先”的管道
该服务器遵循模块化的“重型升降机”模式来管理大量数据，而不会淹没AI代理的上下文窗口。
- 作业编排： 每次批处理运行都会创建一个唯一的 作业ID 以及用于文件工件的专用目录。
- 状态存储： 所有提取的文本和学生元数据都存储在嵌入式 SQLite 数据库(
edmcp.db).这确保了数据完整性，并允许工具跟踪其进度（例如。，PENDING->SCRUBBED->NORMALIZED). - 模块化交接： 代理只传递一个文本块，而不是在聊天中传递大量文本块
job_id工具之间。每个工具都会查询数据库以获取所需数据，执行其任务并更新记录。 - 人在循环清理： 默认情况下，Qwen VL等现代型号会产生高质量的OCR。对于字迹较差的批次，可选
normalize_processed_job可以触发该工具，使用xAI修复拼写错误，从而在最终评估之前进行经过验证的清理。
模块化工具集
文档转换（预处理）
注： 此服务器接受 仅限PDF文件 用于论文处理。教师应在提交前将Word文档保存/导出为PDF。大多数文字处理器都有内置的“另存为PDF”或“导出为PDF”功能。
convert_image_to_pdf：将单个图像（JPEG、PNG）转换为PDF格式。batch_convert_images_to_pdf：将目录中的所有图像转换为单独的PDF文件。merge_images_to_pdf：将多个图像合并为一个多页PDF（例如扫描的论文页面）。convert_pdf_to_text：将PDF转换为纯文本（用于量规/参考资料）。check_conversion_capabilities：验证安装了哪些转换工具，并提供设置说明。
OCR和处理管道
batch_process_documents：入口点。接受以下目录 PDF文件，将其转换为图像，通过Qwen VL执行OCR，并保存 原始文本 到数据库。get_job_statistics：返回作业的清单（学生姓名、页数、字数）。在清理之前验证页面聚合是否正确至关重要。scrub_processed_job：使用预定义的CSV姓名列表自动编辑学生姓名和PII。normalize_processed_job：（可选）使用AI修复OCR伪影和拼写错误。专为人在环验证或代理触发的清理而设计。process_pdf_document：用于单文件处理和即时反馈的轻量级工具。
评估和知识库
evaluate_job：根据提供的量规和上下文材料对学生论文进行评分。add_to_knowledge_base：将参考材料（教科书、量规）摄入当地矢量库。query_knowledge_base：检索特定主题/查询的相关上下文块。
存档和维护
search_past_jobs：按学生姓名、工作名称或论文内容关键字查找过去的评分工作。export_job_archive：生成作业的ZIP存档（证据+报告），用于离线存储或争议。cleanup_old_jobs：删除超过保留期的作业。delete_knowledge_topic：手动删除过时的参考资料。
人在回路检查
该管道将用户控制优先于“黑匣子”自动化。
- OCR暂停（&C）：
batch_process_documents运行繁重的OCR工作负载，但 不 自动进行清理。它返回摘要状态。 - 检查（可选但推荐）： 代理（或用户）可以呼叫
get_job_statistics(job_id)查看结果清单。- 验证： 我们是否按预期找到了15名学生？
- 检查： 是否有任何文章长得可疑（暗示合并错误）或短？
- 继续： 验证后，用户触发
scrub_processed_job在将数据发送到任何外部评估模型之前对其进行消毒。
档案和法律查询
为了支持等级争议和法律诉讼，该系统提供了强大的搜索和导出工具。
- 发现： 使用
search_past_jobs(query="...")找老工作。您可以通过以下方式进行搜索：- 内容： 学生论文中的关键词（例如，“Launcelot”）。
- 元数据： 学生姓名或职位名称。
- 日期： 按日期范围筛选。
- 出口： 呼叫
export_job_archive(job_id)生成一个可下载的ZIP文件，其中包含：- 证据： 原始OCR文本（JSONL）。
- 报告： CSV成绩册。
- 反馈： 个人学生PDF。
- 监管链： 作业处理历史的清单日志。
数据生命周期和维护
为了确保合规性和管理磁盘空间，该系统包括数据清除工具。
保留政策
- 学生数据（工作）： 保留用于 7个月（210天）。这包括一个标准学期加上随后的年级争议期。
- 知识库（主题）： 无限期保留，直到手动删除。
维护工作流程
此服务器不运行后台cron作业。维护是 代理驱动.
推荐时间表： 每周跑步（例如，周日晚上）。
- 代理说明： “运行系统维护。”
- 工具调用：
cleanup_old_jobs(retention_days=210)- 这将删除所有过期作业的数据库记录和物理文件。
- 手动清理： 要删除过时的教科书或量规，请使用
delete_knowledge_topic(topic="Old_Curriculum").
RAG和评估工作流程
该系统支持 检索增强生成（RAG） 为论文评分提供“准时”的背景。
“代理桥”模式
与单片工具不同，我们解耦 检索 从 评估AI Agent充当这两个步骤之间的智能桥梁。
代理设计注意事项（LangGraph/Orchestrator）
代理人如何知道要查询什么？ 代理必须根据讲师的指示或量规本身动态地推导出搜索查询。
推荐工作流程：
- 分析请求： 代理收到提示： “使用《诗歌101》教科书对这些关于弗罗斯特的文章进行评分。”
- 制定查询： 代理人提取关键主题。
- 自我纠正： 如果提示含糊不清（例如“对此进行评分”），代理应向用户询问上下文或评分标准。
- 提取： “搜索‘霜冻主题’、‘修补墙分析’、‘未采取的道路总结’。”
- 检索上下文： 呼叫
query_knowledge_base(query="Frost themes...", topic="Poetry 101"). - 注入上下文： 通过 检索到的文本 进入
context_material论点evaluate_job工具。
为什么要分开？
- 灵活性： Agent可以多次查询知识库，或在评分前优化其搜索。
- 透明度： 用户可以准确地看到代理在用于评分之前检索到的“事实”。
用法
1.环境设置
确保你有 uv 安装。
# Clone and install dependencies
uv sync
# Set your API Keys in a .env file
# QWEN_API_KEY, XAI_API_KEY, etc.
2.安装可选转换工具
对于PDF文本提取（用于量规/参考资料）：
Ubuntu/Debian：
sudo apt-get install poppler-utils
macOS：
brew install poppler
窗户：
- 下载Poppler：https://blog.alivate.com.au/poppler-windows/
注： 此工具是可选的。如果未安装，您可以通过设置使用OCR方法 use_ocr=True 将PDF转换为文本时。代理可以使用以下命令检查可用性 check_conversion_capabilities.
3.开发与检查
使用内置的MCP检查器运行服务器，以交互方式测试工具：
uv run fastmcp dev server.py
这将打开浏览器界面 http://localhost:5173.
4.投产运行
将此服务器连接到您的AI客户端（例如，Claude Desktop、自定义代理）：
uv run python server.py
迁移指南
该项目可作为将传统CLI工具转换为模块化MCP管道的参考。
第一阶段：储存与状态
用结构化数据库（如SQLite）替换文件传递。使用 作业ID 管理状态，并允许工具在特定批次上独立操作。
阶段2：逻辑隔离
将核心逻辑隔离到离散的工具中。确保每个工具都能很好地完成一件事（例如OCR、Scrubbing、Normalization），并主要通过数据库更新进行通信。
第三阶段：代币经济
避免将大数据块返回给代理。返回状态摘要和ID，将“繁重的工作”保留在服务器上。
