Readur MCP 服务器

关键词

文档管理OCR全文检索标签管理API 集成

使用说明（Markdown格式）

  • 项目简介

    • 该项目实现了一个 MCP 服务器，核心职责是以标准化的 JSON-RPC 方式向 MCP 客户端提供与 Readur 文档库相关的资源、工具和提示模板的访问能力。服务器通过一个 Readur REST API 客户端对接 Readur 实例，注册一组工具（如列出文档、获取文档、上传文档、OCR 文本、搜索、标签管理、系统状态等），并将工具的执行结果以 MCP 规定的文本内容形式返回给客户端。
    • 支持的传输方式：当前实现使用 stdio 传输（通过父进程的标准输入输出进行 JSON-RPC 消息传递，默认行为）。若将来增加 SSE 传输将会在代码中提示并可切换。
    • 认证方式：支持通过 JWT 令牌（TOKEN）或基于用户名/密码的登录方式自动获取令牌。服务器端会通过 Readur API 进行鉴权并在必要时自动重试。

  • 主要功能点

    • MCP 核心接口：
      • ListTools：返回所有可用工具的定义，供客户端了解支持的操作。
      • CallTool：根据工具名称执行对应的处理逻辑，并返回文本内容或错误信息。
    • 工具集合（跨文档管理、搜索、标签、状态等）：
      • 文档相关：list_documents、get_document、get_document_ocr_text、upload_document、delete_document、retry_document_ocr
      • 搜索相关：search_documents、enhanced_search、get_search_facets
      • 标签相关：list_labels、create_label、get_document_labels、add_document_label、remove_document_label
      • 状态相关：whoami、get_settings、get_queue_stats、get_ocr_languages
    • 与 Readur REST API 的交互：通过 ReadurClient 封装的 HTTP 请求实现，包含分页、排序、过滤、错误处理等。

  • 安装步骤

      1. 将代码克隆到本地或服务器：
      • 需要 Node.js 版本为 24.x 或以上。
      1. 安装依赖并构建：
      • 运行 npm install
      • 运行 npm run build
      1. 启动服务器：
      • 运行 npm run start（会启动 dist/index.js）或直接 node dist/index.js
      • 启动时可通过环境变量、命令行参数或配置文件提供配置（Readur 服务器地址、认证信息、传输方式等）

  • 服务器配置（MCP 客户端需要此信息来连接 MCP 服务器） 说明：MCP 客户端在连接服务器时需要至少提供服务器的启动命令与参数等信息。下面给出一个示例配置的描述，方便你在 Claude 等客户端进行注册与连接。实际使用时，请将示例中的路径、URL、令牌等替换为你自己的实际值。 示例（JSON 结构，供 MCP 客户端使用；请按需调整注释后直接填入配置项中）: { "server": "readur-mcp", "command": "node", "args": ["/absolute/path/to/readur-mcp/dist/index.js"], "env": { "READUR_URL": "https://readur.example.com", "READUR_TOKEN": "your-jwt-token" // 若使用凭证登录，请仅提供 URL 与 TOKEN；如使用用户名/密码，请改为以下两行并确保 ReadurClient 会在首次请求时自动登录 // "READUR_USERNAME": "your-username", // "READUR_PASSWORD": "your-password" }, "transport": "stdio" // 服务器与客户端通信的传输方式，当前实现默认为 stdio }

  • 基本使用方法

    • 在 Claude、Claude Desktop 或其他 MCP 客户端中注册该 MCP 服务器，提供上述服务器启动信息（命令、参数、环境变量等）。
    • 验证服务器是否注册成功：在 MCP 客户端执行列表查看，确认服务器名称和提供的工具皆可见。
    • 逐步使用工具：
      • 使用 list_documents、get_document 等工具浏览文档库元数据
      • 使用 search_documents、enhanced_search 进行全文检索
      • 使用 upload_document 上传新文档并获得返回的文档信息
      • 使用 get_document_ocr_text、retry_document_ocr 查看或重新获取 OCR 内容
      • 使用 label 相关工具管理标签并将标签分配到文档
      • 使用 whoami、get_settings、get_queue_stats、get_ocr_languages 查看系统状态信息
    • 如遇到鉴权问题，请检查 TOKEN 是否过期，或用户名/密码是否正确；依照 Readur API 失败信息进行排错。

  • 运行与调试提示

    • 若遇到 SSE 传输未实现的警告，服务器会回退到 stdio 传输并继续工作。
    • MCP Inspector 可以用于开发阶段的交互测试，帮助你快速验证工具的可用性和返回格式。

  • 重要说明

    • 该实现将 Readur 的 REST API 封装为 MCP 工具，所有工具输出以文本块形式呈现，便于直接被 LLM 处理和展示。
    • 服务器以 JSON-RPC 的标准格式接收请求并返回响应，错误信息经过统一格式化，便于客户端理解并显示。

服务器信息

访问项目