使用说明

• 项目简介

  • Officetracker 通过内置的 MCP 服务器，将日历型出勤数据、工具接口以及提示模板暴露给外部的 AI 助手/LLM 客户端。客户端可通过 MCP 的 JSON-RPC 方式进行数据读取、工具调用与获取模板等操作，从而实现对用户数据的智能分析与交互。

• 主要功能点

  • 完整的 MCP 服务器实现：实现对 MCP 请求的处理，提供文本内容和结构化数据的响应。
  • 内置工具：get_month、set_day，用于查询与修改用户某月日历的出勤状态。
  • 数据模型与状态支持：支持多种工作状态（未跟踪、远程工作、在办公室、其他；以及计划/调度状态）。
  • 集成模式与独立模式：可在集成模式（需要数据库/认证等外部组件）或独立模式（本地 SQLite，简化部署）下运行。
  • 多传输/接口能力：通过 MCP 服务器实现，默认在 /mcp/v1/ 提供接口，便于与 LLM/AI 客户端对接。
  • 安全与会话：结合现有的鉴权机制（SSO/Secret/Excluded）实现对 MCP 调用的访问控制。

• 安装步骤

  1. 获取源码：将仓库克隆至本地或服务器。
  2. 构建模式选择
     • 独立模式（Standalone）：用于本地开发与个人使用，需本地 SQLite 数据库，无需外部认证。
     • 集成模式（Integrated）：连接外部数据库（PostgreSQL）、Redis、GitHub/Auth0 等，以多用户、认证为基础的场景使用。
  3. 构建与运行
     • Standalone 构建与运行示例：
       • go 构建带标签 standalone 的二进制 officetacker
       • 运行 ./officetracker，默认监听端口 8080，数据库为 officetracker.db
     • Integrated 构建与运行需要正确配置环境变量/配置文件，启动后同样暴露 /mcp/v1/ 端点供 MCP 客户端连接。
  4. 连接 MCP 客户端
     • MCP 客户端应通过 HTTP 请求访问服务器的 /mcp/v1/ 路径，使用 JSON-RPC 进行调用。

• 服务器配置（MCP 客户端需要的最小信息） 说明：MCP 客户端通常需要知晓服务器的启动命令与参数，用于在需要时启动与连接。下面给出一个符合仓库信息的示例配置，展示服务器的名称、启动命令与参数。实际使用中，请结合要部署的环境选择合适的参数。 { "server_name": "officetracker", "command": "officetracker", "args": [ "-port", "8080", "-database", "officetracker.db" ] } 注释：

  • server_name：在 MCP 客户端中用于标识该 MCP 服务的名称，便于管理与显示。
  • command：启动 MCP 服务的可执行文件名。若使用独立模式，默认二进制名为 officetracker。
  • args：启动参数，包含网络端口与数据库路径等。独立模式默认使用端口 8080、数据库 officetracker.db，集成模式请按实际环境替换。

• 基本使用方法

  • 启动服务器后，MCP 客户端通过 /mcp/v1/ 进行请求。
  • 使用 get_month 工具读取指定用户在某年某月的出勤数据；使用 set_day 工具更新指定日期的状态。
  • MCP 返回内容分为两部分：一部分是文本内容（如“Officetracker state successfully fetched/updated”），另一部分是结构化数据（包含实际的月数据或日数据），客户端可据此展示给用户或用于后续推理。
  • 如需在本地进行开发调试，可以将服务器置于 Standalone 模式，避免外部依赖；如需与前端系统/LLM 集成，请切换到 Integrated 模式并正确配置数据库、认证等依赖。

• 注意事项

  • 服务器端已实现的工具包括 get_month 与 set_day，映射到后端数据库的相应读写操作。
  • MCP 相关的路由在 /mcp/v1/ 下，服务器会依据鉴权中间件对不同鉴权方法进行访问控制。
  • 在生产环境中，建议使用集成模式并通过 HTTPS/证书等强化安全性。