1. 项目概述一个专为Jira Tempo设计的MCP服务器如果你和我一样每天都要在Jira里手动填写Tempo工时然后对着那些重复的、琐碎的操作感到厌倦那么这个项目可能就是你的“救星”。ivelin-web/tempo-mcp-server是一个基于Model Context ProtocolMCP的服务器它的核心目标就一个让你能通过像Claude、Cursor这类支持MCP的AI助手用自然语言来管理你的Jira Tempo工时记录。想象一下你只需要在聊天窗口里说“把我昨天在PROJ-123上花的3.5小时记上备注是修复登录bug”AI助手就能帮你自动创建好工单这比在网页上点点点要高效太多了。这个项目本质上是一个桥梁它把Tempo和Jira的API封装成一套标准的MCP工具然后暴露给MCP客户端。这样一来任何兼容MCP的AI应用都能调用这些工具实现工时的查询、创建、编辑和删除。对于开发者、项目经理或者任何需要频繁与Jira Tempo打交道的团队成员来说这不仅仅是自动化更是一种工作流的革新。你不用离开你正在编码的IDE比如Cursor或者正在聊天的AI界面就能无缝完成工时上报把上下文切换的成本降到最低。2. 核心设计思路与技术选型解析2.1 为什么选择MCPModel Context ProtocolMCP是Anthropic推出的一套协议旨在为AI模型提供一个标准化的方式来发现、调用外部工具和资源。你可以把它理解成AI世界的“USB协议”或者“插件标准”。在MCP出现之前如果你想给AI助手比如Claude增加自定义功能往往需要依赖特定平台提供的、封闭的插件系统开发流程复杂且不通用。选择基于MCP来构建这个Tempo工具服务器主要基于以下几点考量一次开发多处使用这是最大的优势。我只需要按照MCP规范实现一套工具Tools任何兼容MCP的客户端如Claude Desktop、Cursor、Windsurf等都能直接使用。我不需要为每个客户端单独开发适配插件极大地减少了开发和维护成本。协议标准化未来可期MCP正在成为AI工具集成领域的事实标准。基于标准协议开发意味着项目的生命周期和兼容性更有保障不会被某个单一平台绑定。开发体验友好MCP提供了清晰的服务器-客户端通信模型、标准的工具定义格式基于JSON Schema和丰富的SDK如modelcontextprotocol/sdk让开发者可以更专注于业务逻辑而不是通信细节。2.2 技术栈深度剖析TypeScript Node.js项目采用TypeScript编写运行在Node.js 18环境这是一个非常成熟且合理的技术选型组合。TypeScript的价值对于涉及多个API调用Jira API, Tempo API和数据结构转换的项目类型安全至关重要。TypeScript的静态类型检查能在编译阶段就捕获大量潜在错误比如参数类型不匹配、对象属性缺失等。这在处理复杂的工时记录对象包含issueKey, timeSpent, date, description等多个字段时能极大提升代码的健壮性和开发效率。src/types.ts文件的存在就是为了集中定义这些数据结构契约。Node.js 18 LTS的考量选择LTS长期支持版本是为了保证运行环境的稳定性。Node.js内置的fetchAPI从v18开始稳定被广泛用于HTTP请求这使得我们在进行Jira和Tempo的API调用时无需额外引入像axios或node-fetch这样的第三方HTTP客户端库保持了依赖的简洁性。项目中的src/jira.ts和工具实现文件大概率就是基于原生的fetch或一个轻量级封装进行网络通信。项目结构设计从提供的结构看项目采用了清晰的分层设计。config.ts处理环境变量和配置jira.ts专注与Jira/Tempo API的交互封装认证和请求细节tools.ts是核心实现了MCP协议规定的各个工具函数index.ts作为入口初始化服务器并注册工具。这种分离关注点的设计让代码易于阅读、测试和维护。2.3 认证策略的双重支持Basic vs Bearer Token项目支持两种Jira API认证方式这个设计考虑到了不同团队的安全策略和基础设施差异。Basic认证默认这是最传统的方式使用邮箱和API Token。其原理是将邮箱:API Token进行Base64编码放在HTTP请求的Authorization头中。这种方式配置简单适用于大部分使用API Token的场景。在代码中config.ts会读取JIRA_EMAIL和JIRA_API_TOKEN然后在jira.ts中构建认证头。// 伪代码示例Basic认证头构建 const authString Buffer.from(${email}:${apiToken}).toString(base64); const headers { Authorization: Basic ${authString} };Bearer Token认证OAuth 2.0这是更现代、更安全的方式通常用于OAuth 2.0流程。直接使用访问令牌Access Token无需邮箱。这对于已经部署了统一OAuth授权服务的企业尤其有用可以实现更细粒度的权限控制和令牌生命周期管理。当设置JIRA_AUTH_TYPEbearer时服务器会构建Authorization: Bearer token这样的请求头。注意使用Bearer Token时务必确保你的Token拥有操作Tempo工时所需的正确作用域Scopes例如write:jira-work和read:jira-work。否则API调用会返回403权限错误。3. 环境配置与实操部署指南3.1 获取并配置核心密钥API Tokens这是项目运行的前提也是最容易出错的一步。你需要两个TokenJira API Token获取路径登录你的Atlassian账户访问 https://id.atlassian.com/manage-profile/security/api-tokens 注意此链接仅为说明实际操作请登录你的Atlassian管理后台。操作点击“Create API token”给它起个名字例如“Tempo MCP Server”然后复制生成的一长串字符。这个Token只会显示一次务必立即妥善保存。权限这个Token代表了你的账户身份因此它天然拥有该账户在Jira和Tempo中的所有权限。无需额外配置。Tempo API Token获取路径进入你的Jira实例在顶部导航栏找到“Tempo”并进入。然后进入“Settings”设置- “API Integration”API集成。操作你应该能看到“API tokens”区域点击“Generate new token”。同样命名并保存好生成的Token。关键点Tempo API Token是独立于Jira API Token的它是专门用于授权访问Tempo工时数据接口的凭证。即使你有Jira权限没有有效的Tempo Token也无法操作工时。3.2 两种运行模式详解与配置项目提供了两种使用方式适用于不同场景的用户。3.2.1 NPX直接运行模式推荐给绝大多数用户这是最简单、最“无痛”的方式。NPX允许你直接运行npm包中的命令而无需在本地永久安装这个包。这对于只想使用功能、不想关心源码的用户来说是最佳选择。配置Claude Desktop的详细步骤定位配置文件macOS文件路径是~/Library/Application Support/Claude/claude_desktop_config.json。你可以打开终端输入open ~/Library/Application\ Support/Claude快速进入该目录。Windows文件路径是%APPDATA%\Claude\claude_desktop_config.json。你可以在文件资源管理器的地址栏直接输入%APPDATA%\Claude来定位。编辑配置文件用任何文本编辑器如VS Code、Notepad打开这个JSON文件。如果文件不存在就创建一个。注入MCP服务器配置你需要将Tempo MCP服务器的配置添加到mcpServers对象中。重要如果mcpServers已存在其他配置请在其内部追加而不是覆盖。{ // ... 可能已存在的其他配置如系统提示词等 mcpServers: { // 其他MCP服务器配置... Jira_Tempo: { command: npx, args: [-y, ivelin-web/tempo-mcp-server], env: { TEMPO_API_TOKEN: 你的_tempo_token_替换这里, JIRA_API_TOKEN: 你的_jira_token_替换这里, JIRA_EMAIL: 你的邮箱公司.com, JIRA_BASE_URL: https://你的公司.atlassian.net, // 可选如果你的Tempo需要关联账户 // JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID: customfield_10010 } } } }Jira_Tempo这是你给这个服务器实例起的名字在Claude中会以此名称引用工具。command: npx告诉Claude使用npx来启动。args: [-y, ivelin-web/tempo-mcp-server]-y参数表示对任何提示都自动回答“yes”ivelin-web/tempo-mcp-server是要运行的npm包名。env这里就是填入你上一步获取的所有密钥和信息的字典。请务必用你自己的真实信息替换示例值。重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop应用程序。这是必须的因为MCP服务器配置只在启动时被加载。3.2.2 本地克隆开发模式适合开发者、需要定制功能、或希望深入理解代码的用户。克隆与初始化git clone https://github.com/ivelin-web/tempo-mcp-server.git cd tempo-mcp-server npm install环境变量配置与NPX模式不同本地运行通常通过.env文件或系统环境变量来配置。推荐创建.env文件在项目根目录TEMPO_API_TOKEN你的_tempo_token JIRA_API_TOKEN你的_jira_token JIRA_EMAIL你的邮箱公司.com JIRA_BASE_URLhttps://你的公司.atlassian.net注意.env文件包含敏感信息务必将其添加到.gitignore中避免意外提交到代码仓库。构建与运行项目是用TypeScript写的需要编译成JavaScript才能被Node执行。npm run build # 编译生成build目录 npm run inspect # 使用MCP Inspector运行用于调试 # 或者直接运行编译后的文件 node build/index.js配置Claude Desktop本地模式此时配置文件的command和args需要指向你本地编译好的JS文件。{ mcpServers: { Jira_Tempo_Dev: { command: node, args: [/Users/你的用户名/Projects/tempo-mcp-server/build/index.js], env: { // ... 环境变量同上也可以选择在.env文件中配置 } } } }关键点args中的路径必须是绝对路径。在macOS/Linux上你可以用pwd命令获取当前目录的绝对路径。3.3 关于Tempo账户自定义字段的特别说明JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID是一个可选但重要的配置。在很多使用Tempo的团队中工时需要关联到某个特定的“账户”Account可能代表客户、项目、成本中心等。这个关联关系在Jira里是通过一个自定义字段来维护的。如何查找这个字段ID以管理员身份登录Jira。进入“设置” - “问题” - “自定义字段”。在列表中找到用于Tempo账户的字段名称可能类似“Tempo Account”、“客户账户”等。点击该字段进入配置页面查看浏览器地址栏的URL。通常ID会以idxxxxx或customFieldIdxxxxx的形式出现。或者在字段配置页面的某个地方也会直接显示ID。这个ID通常是一个数字如10010。何时需要配置如果你的团队在记录Tempo工时时系统强制要求或你个人需要选择账户那么就必须配置这个字段ID。否则创建的工时可能会失败或无法关联到正确的成本单元。在工具调用中的体现当这个环境变量被设置后服务器在调用Tempo API创建或编辑工时时会自动将这个账户信息作为参数的一部分提交。4. 核心工具使用详解与实战案例配置好之后你就可以在Claude或Cursor中直接使用这些工具了。下面我们深入每个工具看看它们具体怎么用以及在实际工作中会遇到哪些场景。4.1retrieveWorklogs工时查询与周报生成这个工具用于获取指定日期范围内的所有工时记录。它是你进行工时回顾、生成周报或核对时间的利器。参数解析startDate和endDate格式必须是YYYY-MM-DD。例如2024-01-15。注意日期范围是闭区间即包含开始和结束日期当天的记录。实战对话示例你“嘿Claude帮我查一下我这周1月15号到1月19号在Jira上记录的所有工时。”Claude调用retrieveWorklogs工具参数为startDate: “2024-01-15”, endDate: “2024-01-19”Claude“这是你2024-01-15到2024-01-19的工时记录”PROJ-456(2024-01-15): 2小时 - “团队站会与项目规划”DEV-789(2024-01-15): 3.5小时 - “实现用户认证模块API”PROJ-456(2024-01-16): 1小时 - “与设计评审UI方案”DEV-790(2024-01-17): 6小时 - “调试支付接口异步回调问题” ...列表继续“总计37.5小时。需要我帮你总结成周报格式吗”内部运作原理工具函数会向Tempo API的/worklogs端点发起GET请求传入from、to以及授权用户等参数。返回的数据会经过处理以清晰易读的格式呈现给你。4.2createWorklog快速记录单条工时这是最常用的工具用于为某个Jira问题记录所花费的时间。参数深度解析issueKeyJira问题的关键键如PROJECT-123。必须确保你有权限向该问题记录工时。timeSpentHours花费的小时数是一个正数。支持小数如1.5代表1小时30分钟。注意Tempo API底层可能以秒或分钟为单位工具内部会帮你做单位转换小时转秒。date工时发生的日期格式YYYY-MM-DD。可以记录过去或未来的日期如果允许。description工时描述。强烈建议填写这是你未来回顾工作的关键上下文。可以是简单的“开发功能X”也可以是详细的日志。startTime开始时间格式HH:MM24小时制如09:30。这是可选参数但填写后能让工时分布更精确。实战对话示例你“我昨天在BUG-101上花了2.5小时做根本原因分析下午2点开始的。”Claude调用createWorklog工具参数为issueKey: “BUG-101”, timeSpentHours: 2.5, date: “2024-01-18”, description: “根本原因分析定位到数据库连接池泄漏”, startTime: “14:00”Claude“✅ 已成功为 BUG-101 创建工时记录2.5小时日期2024-01-18开始时间14:00描述‘根本原因分析定位到数据库连接池泄漏’。工时ID为123456789。”实操心得描述是黄金养成写清晰描述的习惯。几个月后当你需要回溯某个功能花了多少时间或者向领导展示工作细节时这些描述 invaluable。即时记录利用AI助手想到就记。比每天下班前凭记忆批量填写要准确得多。时间格式如果你说“花了两个半小时”AI可能会理解成2.5。直接说数字最稳妥。4.3bulkCreateWorklogs批量导入与快速补录当你需要补录多天、多个任务的工时或者从其他时间追踪工具迁移数据时这个工具能节省大量时间。参数解析worklogEntries是一个数组数组中的每个对象都和createWorklog的参数结构一致。实战场景你周末加班处理了三个紧急问题周一早上需要一并补录。你“帮我批量记录一下周末的工时周六在EMERG-001上花了4小时修复线上告警周日在EMERG-002上花了3小时写修复方案在EMERG-003上花了2小时做部署验证。”Claude调用bulkCreateWorklogs参数为一个包含三个对象的数组Claude“✅ 批量创建成功3条工时记录已提交。详情如下”EMERG-001 (2024-01-20): 4小时 - “修复线上告警”EMERG-002 (2024-01-21): 3小时 - “编写修复方案文档”EMERG-003 (2024-01-21): 2小时 - “部署验证” “总计9小时。”技术细节与避坑API限制Tempo API对批量操作可能有频率或数量限制。工具内部可能会实现顺序请求或简单的错误处理但一次传入几十上百条记录仍需谨慎建议分批进行。错误处理在批量操作中如果其中一条记录失败如issueKey不存在、时间冲突整个操作是全部回滚还是部分成功取决于服务端的实现。理想情况下工具应该提供详细的每项结果反馈。你需要关注AI返回的信息确认所有条目都成功。4.4editWorklog与deleteWorklog工时的修正与清理人难免出错这两个工具提供了修正的途径。editWorklogworklogId这是最关键参数。它是每条工时记录在Tempo系统中的唯一标识符通常是一串数字。你可以在retrieveWorklogs的返回结果中找到它或者在Jira的Tempo工时界面通过浏览器开发者工具查看网络请求也能找到。其他参数timeSpentHours,description,date,startTime都是可选的只传入需要修改的字段即可。场景你发现昨天记录的3小时描述写得太简略或者时间记错了实际是2.5小时。你“把工时ID为987654321的那条记录描述改成‘与后端联调用户API解决数据序列化不一致问题’时间改成2.5小时。”deleteWorklog只需要worklogId。操作不可逆请谨慎使用。场景不小心为错误的任务记录了工时或者重复创建了记录。你“我重复创建了一条工时ID是555555555请删除它。”重要注意事项权限你通常只能修改或删除自己创建的工时记录。审计追踪在有些严格的公司修改或删除工时记录可能会在审计日志中留下痕迹。对于重要的工时修正最好在描述中注明修改原因。获取worklogId这是编辑和删除操作的门槛。最方便的方式就是先通过retrieveWorklogs查询到相关记录复制其ID。未来如果MCP工具能支持更智能的“通过日期和任务查找工时ID”的功能体验会更好。5. 高级集成在Cursor IDE中的“Vibe Coding”体验对于开发者而言在Cursor IDE中使用这个MCP服务器能实现真正的“上下文无缝切换”和“Vibe Coding”沉浸式编码。5.1 Cursor的一键安装与配置项目提供了针对Cursor的“一键安装”深链接这大大简化了配置流程。点击安装按钮在项目的README中有一个深色模式的按钮链接指向一个特殊的cursor://URL。这个URL包含了预配置的服务器信息。Cursor自动处理点击后Cursor会启动并弹出一个确认对话框询问你是否要添加这个MCP服务器。自动配置一旦确认Cursor会自动将服务器的配置命令、参数、环境变量模板写入其内部的MCP配置文件。你通常可以在Cursor的设置 - MCP Servers 部分看到它。填入你的密钥最关键的一步你需要在Cursor的MCP服务器配置界面找到新添加的“Jira Tempo”服务器将TEMPO_API_TOKEN、JIRA_API_TOKEN等环境变量的值从模板替换成你自己的实际密钥。5.2 沉浸式开发工作流实战配置完成后你可以在不离开代码编辑器的情况下完成所有工时相关操作。场景一编码中途记录打断时间你正在写一个功能模块产品经理突然过来和你讨论了15分钟的需求细节。传统做法是切到浏览器打开Jira找到任务填写0.25小时……现在你只需要在Cursor里唤出AI聊天面板通常是Cmd/Ctrl K。输入“刚和产品讨论了PROJ-567的需求细节花了大概15分钟记一下。”Claude通过MCP会调用createWorklog工具自动完成记录。你甚至不需要知道任务的确切键值AI可以根据对话上下文猜测“你刚才在编辑PROJ-567相关的代码文件”。场景二基于提交历史自动生成工时描述你完成了一个功能的开发并提交了Git。在Cursor中你可以让AI分析你最近的Git提交记录。然后指令它“根据我过去4小时在feature/auth分支上的提交commit hash: a1b2c3d为任务DEV-888生成一条详细的工时描述并记录3.5小时。”AI会分析提交信息生成如“实现了OAuth2.0的PKCE流程修复了token刷新逻辑更新了相关API文档”这样的描述并调用工具记录工时。场景三每日Stand-up准备每天站会前你可以在Cursor中快速查询“显示我昨天所有的工时记录并按项目分组计算每个项目的总耗时。” AI会调用retrieveWorklogs获取数据后不仅展示列表还能进行简单的数据聚合和分析让你对一天的工作一目了然。5.3 安全与最佳实践提醒环境变量安全永远不要将包含真实API Token的配置文件提交到Git仓库。对于NPX模式密钥只存在于本地的Claude/Cursor配置文件中。对于本地开发模式务必使用.env文件并加入.gitignore。Token权限最小化虽然Jira API Token拥有你账户的所有权限但从安全角度可以考虑创建一个专门用于自动化工具的“服务账户”并只赋予其必要的最小权限如仅能读写自己的工作日志。网络考虑如果你的Jira实例部署在内网或需要VPN访问请确保运行MCP服务器的机器你的本地电脑能够访问JIRA_BASE_URL指定的地址。错误排查如果工具调用失败首先检查Claude或Cursor的聊天窗口是否有错误信息。更详细的日志需要查看MCP服务器的输出。对于NPX模式你可能需要配置MCP客户端输出日志到控制台对于本地运行模式直接运行npm run inspect会在终端看到详细的请求和响应日志这是调试的利器。6. 常见问题排查与故障解决实录在实际部署和使用过程中你可能会遇到一些问题。下面是我在测试和使用中遇到的一些典型情况及其解决方法。6.1 认证失败类错误这是最常见的问题通常表现为401 Unauthorized或403 Forbidden。错误现象可能原因排查步骤与解决方案“Authentication failed for Jira API”1. Jira API Token错误或已失效。2.JIRA_EMAIL填写错误Basic认证时。3.JIRA_BASE_URL格式错误或无法访问。1.检查Token重新生成Jira API Token并更新配置。Token一旦生成只显示一次忘了只能重创。2.核对邮箱确认JIRA_EMAIL是你登录Jira时使用的邮箱地址区分大小写。3.验证URL确保JIRA_BASE_URL是完整的、正确的实例地址如https://your-company.atlassian.net。在浏览器中打开此URL确认能正常登录。“Tempo API authentication error”1. Tempo API Token错误或已失效。2. Token没有所需权限。1.重新生成Tempo Token进入Tempo Settings - API Integration生成新Token替换。2.确认权限确保生成Token的账户有读写工作日志的权限。通常个人Token拥有自己的全部权限如果是服务账户需额外检查。操作成功但工时未关联账户JIRA_TEMPO_ACCOUNT_CUSTOM_FIELD_ID未设置或设置错误。1.确认是否需要尝试在Jira网页上手动创建一个工时看是否强制要求选择账户。如果是则必须配置此字段。2.查找正确ID按前文所述在Jira管理后台的“自定义字段”页面找到确切的字段ID。ID通常是customfield_100xx或纯数字格式。6.2 网络与连接类错误错误现象可能原因排查步骤与解决方案“Failed to connect to Jira instance” 或超时1. 网络问题无法访问Jira实例。2. 公司防火墙或代理限制。3.JIRA_BASE_URL使用了错误的协议http vs https。1.基础连通性测试在终端使用curl -I https://your-company.atlassian.net测试是否能访问。2.检查代理如果你在公司网络中使用代理可能需要为Node.js或全局系统配置代理。对于NPX方式配置比较麻烦本地运行模式可以在代码中或通过环境变量HTTP_PROXY/HTTPS_PROXY配置。3.强制HTTPS确保URL以https://开头。MCP服务器启动失败提示命令未找到1. Node.js未安装或版本过低。2. NPX命令不可用。3. 本地模式下node路径或项目路径错误。1.检查Node.js在终端运行node --version确保版本 ≥ 18。2.NPX问题运行npx --version确认。NPX通常随npm一起安装。3.检查路径在本地模式配置中args里的JS文件路径必须是绝对路径。使用pwdLinux/macOS或cdWindows命令获取项目build/index.js的完整路径。6.3 数据与操作类错误错误现象可能原因排查步骤与解决方案“Issue key PROJECT-123 not found”1. 任务键值拼写错误。2. 你无权访问该项目或该任务。3. 任务已被删除或归档。1.仔细核对确认PROJECT-123完全正确包括大小写和连字符。2.检查权限在Jira网页上确认你能看到这个任务。3.确认任务状态任务是否处于活跃状态。创建/编辑工时返回验证错误1.timeSpentHours为负数或零。2.date格式错误或为非法日期。3.startTime格式错误。4. 工时与已有记录冲突同一时间点重复记录。1.检查参数格式确保时间、日期格式严格符合YYYY-MM-DD和HH:MM。2.检查时间值timeSpentHours必须是正数。3.避免冲突Tempo通常不允许在同一时间段内为同一用户记录多条工时。如果需要在同一天同一时间记录多个任务确保startTime错开或者只记录一个总工时到某个主任务上。bulkCreateWorklogs部分失败传入的数组中有个别条目参数错误或权限不足。1.查看详细错误MCP工具应返回具体的错误信息指出哪一条失败了以及原因。2.分批重试将大批量操作拆分成小批次如每次5-10条逐一执行方便定位问题条目。3.单独验证将失败的条目参数单独用createWorklog测试以精确排查问题。6.4 客户端集成问题错误现象可能原因排查步骤与解决方案Claude/Cursor中看不到Tempo工具1. MCP配置文件未正确加载。2. 配置文件语法错误JSON格式错误。3. MCP服务器启动失败客户端将其禁用。1.重启客户端修改MCP配置后必须完全重启Claude Desktop或Cursor。2.验证JSON使用在线JSON校验工具检查你的claude_desktop_config.json文件是否有语法错误如多余的逗号。3.查看客户端日志Claude Desktop和Cursor通常有输出日志的地方如系统控制台、日志文件查看其中是否有MCP服务器加载失败的错误信息。工具调用无响应或超时1. MCP服务器进程卡死或崩溃。2. 网络请求缓慢。3. 客户端与服务器通信故障。1.检查服务器进程如果是本地运行查看终端是否有错误输出。如果是NPX运行尝试在终端手动运行npx -y ivelin-web/tempo-mcp-server看能否正常启动会提示缺少环境变量但至少证明命令有效。2.简化测试尝试使用最基本的retrieveWorklogs查询最近一天的记录看是否是最简单的功能也有问题。最后的建议当遇到任何问题时启用“检查模式”npm run inspect是最强大的调试手段。它会启动一个带有MCP Inspector的服务器你可以看到所有进出的原始请求和响应精准定位是参数问题、网络问题还是API返回的业务逻辑问题。养成“遇事不决看日志”的习惯能解决90%以上的技术问题。