Factorial MCP Server

关键词

企业自动化OAuth2JSON-RPC外部API集成工具暴露

使用说明内容（Markdown格式）

  • 项目简介

    • 该项目实现一个 MCP 服务端，允许 AI 客户端通过标准化的 JSON-RPC 调用来读取资源、执行工具、渲染与获取提示模板等能力，从而在本地或容器中与 Factorial HR API 集成，完成如请假申请、信息查询等任务的自动化对话流程。

  • 主要功能点

    • MCP 兼容：提供使用 MCP 工具的端点，支持客户端初始化、工具列表查询、工具调用等标准流程。
    • 资源与工具暴露：实现若干 MCP 工具，涵盖授权、员工信息、时间休假管理等场景。
    • OAuth2 授权：通过 OAuth2 完成对 Factorial API 的安全验证，并持久化令牌。
    • Factorial API 集成：对 Factorial 公共 API 进行 GET/POST/PUT/DELETE 请求，带令牌鉴权、缓存等优化。
    • 会话与授权管理：维护访问令牌状态、回调处理、状态校验等，支持 Interative Authorization 流程。
    • 本地化与扩展性：提供本地化的 HTTP 回调服务器（OAuthHttpServer）及可扩展的工具/权限模型。
    • 测试覆盖：包含多种集成与单元测试，验证工具注册与调用、授权流程、HTTP 回调等。

  • 安装步骤

    • 需要的运行环境：Java 17+、Docker（用于 MCP 客户端示例集成）以及本地或容器化部署环境。
    • 构建与打包：在项目根目录执行构建命令（如使用 Just 进行构建与运行的教程所示），构建完成后会生成可用于 Docker 的镜像 GHCR.io/ratek-20/factorial-mcp-server。
    • 运行依赖：在运行前需要配置环境变量，如 OAUTH2_APPLICATION_ID、OAUTH2_APPLICATION_SECRET、Factorial API 的重定向 URI、主机名等，以及可能的数据库/缓存卷等（文档中有详细说明）。
    • 啟动示例（通常通过 MCP 客户端进行连接，示例中以 STDIO 传输为主）：
      • 将服务器镜像通过 Docker 运行，并暴露端口 7000，数据卷挂载到 /app/data，同时传入 OAuth 应用凭据与传输协议参数。具体参数请参考仓库提供的示例配置。

  • 服务器配置（MCP 客户端需要的配置信息，示例以 JSON 表示，实际为文本配置，非代码）

    • serverName: "factorial-mcp-server"
    • command: "docker"
    • args: [ "run", "-i", "--rm", "-p", "7000:7000", "-v", "factorial-mcp-server_cache:/app/data", "-e", "EXIT_ON_EOF=true", "-e", "OAUTH2_APPLICATION_ID", "-e", "OAUTH2_APPLICATION_SECRET", "ghcr.io/ratek-20/factorial-mcp-server:latest", "--transport", "stdio" ]
    • 说明：该配置表示通过 Docker 运行服务器镜像，开启交互式输入输出（stdio）传输，端口暴露给 MCP 客户端，数据缓存保存在 Docker 的命名卷中，且注入 OAuth 应用凭据以完成授权流程。

  • 基本使用方法

    • 启动后，通过 MCP 客户端（如 Claude Code、Gemini CLI、Copilot CLI 等）建立与服务器的连接，使用 initialize 握手、获取工具列表、调用具体工具等。
    • 使用 OAuth2 授权流程首次使用时会在浏览器中完成授权，授权成功后服务器将缓存并使用访问令牌进行后续 API 调用。
    • 常用工具示例包括：
      • get_current_employee、get_employee（查询员工信息）
      • get_available_vacation_days、get_leave_types、read_time_offs、request_time_off、approve_time_off、update_time_off、delete_time_off（时间休假管理相关操作）
    • 如遇令牌失效，系统会尝试刷新令牌，刷新失败时需重新授权。

服务器信息

访问项目