使用说明（Markdown 格式）

项目简介
- 这是一个基于 MCP 协议的后端服务器，专注于 Toggl Track 的时间跟踪、报表生成与数据 hydration。服务器实现了 MCP 的核心能力：托管并管理资源、注册执行工具、定义并渲染提示模板，以及通过 JSON-RPC 与客户端进行通信，支持会话管理与多种传输方式（如标准输入输出、SSE、WebSocket 等）。
主要功能点
- 时间跟踪工具：读取时间条目、获取当前正在运行的计时器、开启和停止计时器。
- 报表工具：日、周报及按工作区/项目的汇总，支持 JSON 与文本输出格式。
- 缓存与 hydration：智能缓存工作区/项目/客户端等信息，hydrating 时间条目以包含名称而非纯 ID，提升性能并减少 API 调用。
- 资源管理与查询：列出工作区、项目、客户端、标签等，提供缓存状态与清理能力。
- 开发与部署友好：提供开发模式、构建、测试以及与 Automation Hub 等工作流的对接能力。
- 安全与鲁棒性：对 Toggl API 的鉴权、速率限制处理、错误归一化提示，支持重试与回退。
安装步骤
- 准备环境
  - 需要 Node.js 环境（推荐 LTS 版本）。
- 安装与构建
  - 通过 npx 直接使用（推荐用法，无需本地克隆）：npx @verygoodplugins/mcp-toggl@latest
  - 或本地安装后构建：
    - npm install
    - npm run build
- 配置 Toggl API Key
  - 从 Toggl Track 获取 API Key，并通过环境变量传入：TOGGL_API_KEY（优先，亦支持 TOGGL_API_TOKEN、TOGGL_TOKEN）
  - 可选配置包括：TOGGL_DEFAULT_WORKSPACE_ID、TOGGL_CACHE_TTL、TOGGL_CACHE_SIZE
- 运行与启动
  - 使用 MCP 客户端启动（如 Claude Desktop、Cursor 等），客户端需要提供服务器启动命令及参数（见下方“服务器配置”示例）。
  - 启动后，服务器会暴露一组工具接口供 MCP 客户端调用，所有调用均通过 JSON-RPC 风格的消息交互。
服务器配置（供 MCP 客户端使用的启动信息示例，JSON 格式）说明：MCP 客户端需要知道启动命令、参数以及必要的环境变量来连接到 MCP 服务器。本示例展示基于仓库信息的准确配置字段与含义，请据实际环境替换其中的具体值。 { "server_name": "mcp-toggl", "command": "npx", "args": ["@verygoodplugins/mcp-toggl@latest"], "env": { "TOGGL_API_KEY": "your_api_key_here", "TOGGL_DEFAULT_WORKSPACE_ID": "123456", "TOGGL_CACHE_TTL": "3600000", "TOGGL_CACHE_SIZE": "1000" }, "备注": "若使用本地构建版本，可将 command 与 args 修改为 node/dist/index.js 等实际启动路径；请确保 dist/index.js 与构建产物一致。" }
基本使用方法
- 连接与授权
  - 启动 MCP 服务器后，确保环境变量正确设置（TOGGL_API_KEY 等）。
  - 通过 MCP 客户端测试连接，如进行身份校验、获取工作区列表等。
- 常用工具使用
  - toggl_check_auth：检查 Toggl API 连通性与鉴权是否有效。
  - toggl_get_time_entries：按日期区间、工作区或项目筛选时间条目，返回 hydrated 的条目信息。
  - toggl_get_current_entry：获取当前正在运行的计时器。
  - toggl_start_timer / toggl_stop_timer：启动与停止计时器。
  - toggl_daily_report / toggl_weekly_report / toggl_project_summary / toggl_workspace_summary：生成日/周报及汇总。
  - toggl_list_workspaces / toggl_list_projects / toggl_list_clients：列出工作区、项目、客户等。
  - toggl_warm_cache / toggl_cache_stats / toggl_clear_cache：缓存管理与状态查询。
- 显示与输出
  - 日报、周报可选择 JSON 输出，或使用文本格式以便直接粘贴到 Automation Hub 或日志中。
重要注意事项
- MCP 服务器作为后端服务，客户端负责通过配置启动命令来连接；请确保 API Key 的保密性，避免明文暴露在公有环境。
- 缓存策略可通过 TOGGL_CACHE_TTL、TOGGL_CACHE_SIZE 调整，默认配置在 README 和代码中给出，便于快速上手。
运行与调试
- 运行模式包括开发模式（npm run dev）和生产构建后的运行方式，测试用例与工具链在仓库中提供。
- 如遇 API 限流，服务会自动重试并遵循指数退避策略，尽量将调用放在缓存命中路径以提升性能。

关键词

信息