1. 项目概述一个连接时间追踪与AI助手的桥梁最近在折腾AI Agent和自动化工作流发现一个痛点很多AI助手比如Claude Desktop、Cursor的AI功能虽然能帮你写代码、分析文档但它们对“你正在做什么”这件事一无所知。它们不知道你花了两小时调试一个API也不知道你刚开了个半小时的站会。这就导致AI给出的建议有时会脱离上下文不够精准。这时候一个能把我日常的时间追踪数据“喂”给AI助手的工具就显得格外有价值。我发现的这个项目——frifster/timedoctor-mcp正是为了解决这个问题而生。简单来说它是一个Model Context ProtocolMCP服务器专门用于将Time Doctor一款流行的员工时间追踪与生产力分析软件的数据安全、结构化地暴露给你本地的AI助手。如果你是Time Doctor的用户同时又重度依赖Claude、Cursor或其他兼容MCP协议的AI工具那么这个项目能让你体验到“上下文感知”的AI协作。AI可以知道你今天的任务分布、在各个项目上的耗时甚至是你最近的活跃时段从而提供更贴合你工作节奏的建议比如“看你今天在‘用户认证模块’上花了三小时需要我帮你梳理一下相关的代码逻辑吗” 或者 “根据你过去一周的会议记录明天下午2点到4点是你通常的深度工作时间建议把那个复杂的需求评审会挪个时间。”2. MCP协议与Time Doctor集成核心解析2.1 什么是MCP为什么它是关键MCP全称Model Context Protocol是由Anthropic提出的一套开放协议。它的核心目标是标准化AI模型与外部工具、数据源之间的通信方式。你可以把它想象成AI世界的“USB协议”或者“插件标准”。在MCP出现之前每个AI应用如Claude Desktop如果想接入某个外部服务如Notion、GitHub、Time Doctor都需要自己单独开发一套集成逻辑。这导致了大量重复劳动且集成质量参差不齐。MCP协议定义了一套统一的规范服务器Server像timedoctor-mcp这样的项目它扮演数据提供者的角色负责与Time Doctor的API通信获取数据并按照MCP规定的格式打包。客户端Client如Claude Desktop、Cursor等AI应用它们内置了MCP客户端知道如何按照协议去发现、连接并调用不同的MCP服务器。协议Protocol规定了客户端如何发现服务器、如何请求资源Resources、如何调用工具Tools、以及数据交换的格式通常是JSON。frifster/timedoctor-mcp作为一个MCP服务器它的价值就在于封装了所有与Time Doctor API交互的复杂性并以一种AI助手能直接理解的标准方式提供时间追踪数据。你不需要教Claude怎么去调用Time Doctor的OAuth、怎么解析分页响应你只需要告诉Claude“去问timedoctor-mcp服务器要我今天的工作报告。”2.2 Time Doctor数据模型与MCP资源映射要理解这个项目做了什么得先看看Time Doctor那边有什么。Time Doctor的核心数据模型围绕“时间”展开用户User使用Time Doctor的团队成员。项目Project任务Task用于对工作进行分类。例如项目是“产品开发”任务可能是“前端UI重构”、“API接口调试”。时间记录Time Entry最核心的数据单元。记录了一个用户在某个任务上从何时开始到何时结束耗时多久。可能还包含手动添加的备注Note。工作报告Worklogs/Reports基于时间记录的聚合数据比如每日/每周/每月的总工时、各项目耗时分布、活跃时段图表等。截图Screenshots活动记录ActivityTime Doctor的“监控”功能部分记录用户的活动级别和随机截图如果启用。timedoctor-mcp项目需要做的就是将这些实体和查询能力映射成MCP协议中的“资源Resources”和“工具Tools”。资源Resources通常是只读的数据视图。例如td://users/me代表当前已认证用户的信息。td://projects代表可访问的项目列表。td://worklogs/today代表今天的工作日志汇总。这些资源有唯一的URIAI客户端可以通过read_resource请求来获取它们的内容通常是JSON。工具Tools允许执行操作或提交数据。例如create_time_entry创建一个新的时间记录。update_time_entry_note为某个时间记录添加或更新备注。get_daily_report获取指定日期的详细报告。AI客户端通过call_tool来触发这些操作并传入所需参数。项目的核心工作就是实现这些资源和工具对应的后端逻辑调用真实的Time Doctor API处理认证、错误、数据转换然后返回给MCP客户端。3. 项目部署与配置实操指南3.1 环境准备与依赖安装这个项目是一个Node.js应用所以第一步是确保你的开发环境就绪。# 1. 克隆项目代码 git clone https://github.com/frifster/timedoctor-mcp.git cd timedoctor-mcp # 2. 检查Node.js版本建议使用LTS版本如18.x或20.x node --version # 3. 安装项目依赖 npm install这里有个关键点项目根目录下的package.json文件。除了常见的依赖你需要特别关注它是否定义了MCP服务器所需的特定入口点。一个标准的MCP服务器package.json通常会包含类似这样的配置{ name: timedoctor-mcp, version: 1.0.0, type: module, // 注意是ES模块还是CommonJS bin: { timedoctor-mcp: ./build/index.js // 或 ./src/index.js }, scripts: { start: node ./src/index.js, build: tsc // 如果是TypeScript项目 } }如果项目是用TypeScript写的你还需要执行npm run build来编译代码。在安装依赖时如果遇到网络问题可以尝试配置npm镜像源但这是基础操作不展开。3.2 获取Time Doctor API凭证这是整个配置中最关键也最容易出错的一步。你需要在Time Doctor的企业管理后台创建API集成。登录Time Doctor以管理员或具有相应权限的账户登录你的Time Doctor公司账户。进入设置通常导航路径是Settings-Company Settings-API或Integrations-API。创建新的API密钥点击“Create New Key”或类似按钮。你需要提供密钥的名称如“My MCP Server”并仔细选择权限范围Scopes/Permissions。权限最小化原则至关重要。对于timedoctor-mcp的基本功能读取时间记录、项目创建记录你通常需要勾选以下权限read:user读取用户信息用于识别当前用户。read:project读取项目和任务列表。read:worklog读取工作时间记录和报告。write:worklog创建或编辑时间记录如果你需要AI帮你记录时间。务必不要勾选不必要的权限尤其是read:screenshot读取截图这类敏感权限除非你的MCP服务器明确需要并提供相应安全保障。保存凭证创建成功后Time Doctor会生成一对密钥Client ID和Client Secret。Client Secret 只会显示一次务必立即复制并安全保存例如存入密码管理器。丢失后只能重新生成。重要提示Time Doctor的API可能使用OAuth 2.0授权码流程Authorization Code Grant或简单的令牌Token机制。timedoctor-mcp的配置需要你仔细阅读其README.md或源码看它期望哪种认证方式。如果是OAuth 2.0你可能还需要配置回调地址Redirect URI这通常在运行MCP服务器的本地地址如http://localhost:3000/callback。3.3 配置MCP服务器并连接客户端假设timedoctor-mcp使用环境变量进行配置你需要创建一个.env文件在项目根目录# .env 文件示例 TIMEDOCTOR_CLIENT_IDyour_client_id_here TIMEDOCTOR_CLIENT_SECRETyour_client_secret_here TIMEDOCTOR_REDIRECT_URIhttp://localhost:3000/callback # 如果使用OAuth TIMEDOCTOR_ACCESS_TOKENyour_personal_access_token_if_applicable # 如果是Token方式 PORT3000 # MCP服务器监听的端口接下来启动服务器npm start # 或如果定义了脚本node src/index.js如果一切正常终端会输出服务器已启动在http://localhost:3000或类似信息。现在需要配置你的AI客户端以Claude Desktop为例来发现并使用这个MCP服务器。MCP服务器的配置方式因客户端而异但通常有两种标准MCP配置在客户端的配置文件中如Claude Desktop的claude_desktop_config.json添加一个指向该服务器的配置项。通过stdio通信许多MCP服务器设计为通过标准输入输出与客户端通信。客户端配置中会直接指定启动该服务器程序的命令。你需要查阅timedoctor-mcp项目的README找到它推荐的客户端配置方式。一个Claude Desktop的配置示例如下假设服务器通过stdio通信// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) { mcpServers: { timedoctor: { command: node, args: [ /absolute/path/to/timedoctor-mcp/build/index.js ], env: { TIMEDOCTOR_CLIENT_ID: your_id, TIMEDOCTOR_CLIENT_SECRET: your_secret } } } }保存配置并重启Claude Desktop后你应该能在与Claude的对话中发现它多出了一些可用的“工具”或能力比如“获取我的今日工时”。4. 核心功能实现与使用场景深度剖析4.1 数据查询让AI了解你的工作全景配置成功后最直接的功能就是查询。你可以在AI对话中进行自然语言查询“我本周在‘项目Alpha’上花了多少时间”AI背后会调用get_weekly_report工具过滤项目名为“项目Alpha”的数据并计算总和然后以清晰的口吻回复你。“把我昨天的工作记录按时间顺序列出来。”AI会读取td://worklogs/yesterday资源或调用相应工具获取时间条目列表并格式化成易读的摘要。“我下午通常哪个时段效率最高”这需要更复杂的分析。AI可能会获取你过去几周的每日活动数据如果服务器暴露了此类资源进行简单的聚合分析找出下午活跃度最高的时段。实现细节在服务器端当AI请求td://worklogs/today资源时对应的处理函数会使用配置的API凭证向https://api.timedoctor.com/v1.1/...发起认证请求。构造查询参数如start_date2023-10-27end_date2023-10-27user_ids...。处理Time Doctor API的响应该响应可能包含分页。需要循环获取所有页的数据。将原始的Time Doctor数据格式转换、清洗成MCP资源定义的标准JSON格式。例如将秒数转换为“小时:分钟”的易读格式合并任务和项目名称。将最终的结构化数据返回给AI客户端。这个过程对用户是完全透明的你只需要用自然语言提问。4.2 时间记录创建与编辑无缝的工时补录这是更具交互性的功能。当你专注于编码或会议忘记启动Time Doctor计时器时可以事后让AI帮你补录。场景你刚结束一个和客户关于需求变更的紧急电话会议持续了45分钟。你对AI说“帮我把刚才45分钟记录到‘客户沟通’任务下备注写‘与XX公司讨论Y需求变更’。”AI操作它会调用create_time_entry工具传入参数project_id或project_name: “客户沟通”start_time: “2023-10-27T14:00:00Z”AI可能需要你确认或它根据上下文推断duration: 2700 (45分钟对应的秒数)note: “与XX公司讨论Y需求变更”结果一条新的时间记录被创建到Time Doctor中无需你手动打开Time Doctor应用或网页。注意事项时区处理这是最容易出错的点。Time Doctor API通常使用UTC时间。你的AI客户端、MCP服务器、以及你口头表达的时间三者之间的时区必须协调一致。最佳实践是让MCP服务器统一使用UTC并在与用户交互时明确说明或进行转换。任务识别如果通过任务名称而非ID来指定服务器需要有一个“查找任务ID”的步骤。如果名称不唯一可能需要AI与你进行二次确认。权限验证确保创建时间记录的API调用使用的是有相应write:worklog权限的令牌并且只能记录到当前用户自身或其有权限管理的项目下。4.3 智能分析与建议基于上下文的效率提升当AI掌握了你的时间数据流它可以扮演一个被动的数据分析师角色提供主动建议。每日站会助手每天早上AI可以自动生成你昨天的工作摘要“昨天你总共工作了7.5小时其中4小时在‘支付模块开发’2小时在‘团队会议’1.5小时在‘代码审查’。今天在‘支付模块’上计划推进哪些任务”打断恢复提醒如果你在一天中有多次短时间15分钟记录到“即时通讯”或“邮件”任务AI可以在你重新开始深度工作前提醒“检测到你今天上午被沟通打断了6次累计1小时。接下来需要我帮你屏蔽一段免打扰时间专注于‘API设计文档’吗”项目进度预估对于长期项目AI可以分析历史耗时数据“过去两周你在‘数据库迁移’任务上平均每天投入3小时。以当前速率预计还需要5个工作日完成。需要调整优先级吗”这些高级场景的实现依赖于MCP服务器是否提供了更聚合、更分析性的“工具”或“资源”或者依赖于AI客户端自身利用基础数据进行的简单分析。目前timedoctor-mcp项目可能更侧重于基础的数据打通但这是一个充满可能性的方向。5. 安全、隐私考量与最佳实践将时间追踪数据接入AI安全与隐私是重中之重。Time Doctor数据非常敏感可能包含员工活动截图、详细的网站和应用程序使用记录。5.1 数据流与安全边界你必须清晰理解数据流向[Time Doctor 云端数据] --(HTTPS API)-- [你的本地机器: timedoctor-mcp 服务器] --(本地进程间通信/stdio)-- [你的本地AI客户端 (如Claude Desktop)]关键的安全边界在于API凭证安全TIMEDOCTOR_CLIENT_SECRET必须妥善保管在本地环境变量或加密配置文件中绝不能提交到公开的代码仓库。本地通信安全MCP协议在本地通过stdio或网络端口通信。确保服务器只绑定在本地回环地址127.0.0.1不对外网开放。权限最小化如前所述在Time Doctor后台创建API密钥时只授予必要的只读或写入权限。绝对避免授予admin或read:screenshot等宽泛或敏感的权限。AI客户端可信度你使用的AI客户端如Claude Desktop必须是来自可信开发者的官方版本。理论上配置了MCP服务器后该客户端就能访问服务器提供的所有数据。5.2 隐私保护配置建议敏感数据过滤在timedoctor-mcp服务器的代码层面可以考虑对返回给AI的数据进行过滤。例如即使你有权限也选择不暴露screenshot截图或activity具体应用名称这类高度敏感的资源。可以在代码中注释掉或删除相关API的调用和资源映射。匿名化聚合对于分析性查询服务器可以只返回聚合后的数据如总工时、项目分布百分比而不返回具体每个时间条目的详细开始结束时间和备注。用户确认机制对于创建、修改或删除数据的“工具”操作可以在MCP服务器层面设计一个简单的确认机制例如需要用户在终端输入一个确认码但这会破坏自动化流程的流畅性需要权衡。5.3 生产环境部署考量目前这个项目更适合技术爱好者个人使用。如果考虑在团队中小范围试用或部署需要额外考虑多用户支持当前的实现很可能只支持配置一个Time Doctor账户即运行服务器的你的账户。要支持团队需要设计更复杂的多用户认证和会话管理机制确保用户A的数据只能被用户A的AI访问。服务器化部署可以将MCP服务器部署在一台内部服务器上团队成员通过配置他们的AI客户端连接到这个内部服务器地址。但这大大增加了安全复杂性需要处理网络认证、用户隔离等问题。审计日志记录所有通过MCP服务器发起的API请求便于追踪和审计。对于绝大多数个人用户坚持在本地个人电脑上运行使用个人API令牌并严格限制权限是目前最安全、最可行的使用方式。6. 常见问题排查与进阶调试在实际搭建和使用过程中你可能会遇到以下问题。6.1 连接与认证失败问题现象可能原因排查步骤AI客户端提示“无法连接MCP服务器”或“服务器未响应”。1.timedoctor-mcp服务器进程未启动。2. 客户端配置的命令或路径错误。3. 端口冲突。1. 在终端运行npm start检查服务器是否成功启动有无报错。2. 仔细核对claude_desktop_config.json中的command和args确保是绝对路径且可执行。3. 检查服务器启动日志看是否提示端口被占用尝试修改PORT环境变量。服务器启动报错提示Invalid client credentials或Unauthorized。1. Time Doctor的CLIENT_ID或CLIENT_SECRET填写错误。2. API密钥权限不足。3. 令牌Token已过期。1. 重新从Time Doctor后台复制粘贴凭证注意不要有多余空格。2. 登录Time Doctor后台检查该API密钥的权限范围是否包含所需操作。3. 如果使用OAuth可能需要重新进行授权流程获取新的刷新令牌。检查服务器代码中令牌的刷新逻辑。AI可以连接服务器但查询数据时返回空或错误。1. 查询的时间范围不对。2. 当前认证的用户无权访问某些项目数据。3. Time Doctor API本身返回错误。1. 打开浏览器开发者工具或使用curl/Postman直接用你的API凭证调用Time Doctor的对应接口验证数据是否存在。2. 在服务器代码中添加更详细的日志打印出请求的URL、参数和完整的API响应便于定位问题。6.2 数据不一致与功能异常问题AI创建的时间记录在Time Doctor网页上看不到或者时间不对。排查时区问题这是首要怀疑对象。确认服务器发送给Time Doctor API的start_time和end_time是UTC格式并且与你所在时区换算正确。可以在服务器代码里将发送的数据和本地时间对比打印出来。用户上下文确认API调用使用的是正确的user_id。如果是为“自己”记录通常可以使用me或从认证信息中获取的自己的用户ID。项目/任务状态确认你指定的项目或任务在Time Doctor中是活跃Active状态而非已归档Archived。问题AI无法理解我口头说的项目名称总是创建失败。解决这需要增强服务器的“模糊匹配”能力。可以在create_time_entry工具的实现中加入一个步骤先调用Time Doctor的“列出项目”接口获取所有项目列表然后在本地进行字符串相似度匹配例如使用Levenshtein距离算法找到最匹配的项目ID。对于匹配度不高的可以让AI通过对话向用户请求确认。6.3 性能优化与自定义扩展缓存策略像“项目列表”这类不常变化的数据可以在MCP服务器内存中缓存一段时间例如5分钟避免每次查询都调用API提升响应速度。增加新工具如果你发现某个分析功能很常用可以尝试自己修改timedoctor-mcp的源代码增加一个新的“工具”。例如添加一个get_focus_time工具用于计算过去7天中单次持续时间大于30分钟的时间块的总和作为“深度工作时间”的度量。与其他MCP服务器联动MCP的威力在于组合。你可以同时运行timedoctor-mcp和github-mcp-server。然后向AI提问“帮我总结一下我昨天在‘项目X’上写的代码并结合我的时间记录看看效率如何” AI可以同时从两个服务器获取数据进行关联分析。这个项目的价值在于它打开了一扇门将严谨的时间数据与灵活的AI对话能力结合。它目前可能还是一个略显粗糙的工具但清晰地展示了未来个人生产力工具的一个进化方向数据孤岛的连接器。通过MCP这样的开放协议各种垂直领域的专业工具时间管理、代码托管、文档编辑都能将其核心能力以标准接口暴露出来最终在AI这个智能枢纽的调度下形成真正围绕用户、理解上下文的工作流。