PingCode MCP Server

Instructions

Implementation Reference

• src/tools/work-items.ts:326-477 (handler)

  Core handler function for the 'get_work_item' tool. Fetches work item details from PingCode API, formats the data into a readable string with structured fields, generates AI directives for single-task mode and bug analysis workflow, and returns formatted response.
  export async function getWorkItem(identifier: string): Promise<{ success: boolean; data?: string; workItem?: WorkItemData; aiDirectives?: AiDirectives; nextRequiredAction?: NextRequiredAction; error?: string; }> { try { // 使用增强版 API 获取带成员名称的工作项 const item = await pingcodeClient.getWorkItemWithDetails(identifier); if (!item) { return { success: false, error: `未找到编号为 ${identifier} 的工作项`, }; } const workItem = formatWorkItem(item); // 根据工作项类型推荐 commit type const typeMap: Record<string, string> = { '缺陷': 'fix', '需求': 'feat', '用户故事': 'feat', '任务': 'chore', '史诗': 'feat', }; const suggestedType = typeMap[workItem.type.value] || 'chore'; const suggestedMsg = `#${workItem.id.value} ${suggestedType}: ${workItem.title.value}`; const requiredFirstOutput = `🔒 单任务模式：处理 ${workItem.id.value}，完成后立即询问 commit`; const aiDirectives: AiDirectives = { mode: 'single_task', work_item_id: workItem.id.value, stop_after_fix: true, ask_commit_after_fix: true, wait_user_reply_before_next_item: true, forbidden_actions: [ 'get_other_work_item_before_commit_decision', 'batch_fetch_multiple_work_items_in_parallel', 'modify_multiple_work_items', ], required_first_output: requiredFirstOutput, commit: { suggested_message: suggestedMsg, options: ['use_suggested', 'user_provided', 'skip'], }, }; // 判断是否为缺陷类型 const isBug = workItem.type.value === '缺陷'; // Bug 分析流程提示（仅当类型为缺陷时添加） const bugAnalysisPrompt = isBug ? [ '', '🐛 **[缺陷分析流程 - 强制执行]**', '', '## 核心原则：证据驱动，禁止假设', '', '### 第一步：穷举现象 → 提取搜索词', '从标题/截图/日志/描述/评论中提取**所有**异常（不能只看最明显的）。', '每个现象提取 1-2 个**代码搜索关键词**（函数名、错误信息、变量名等）。', '', '### 第二步：筛选相关现象', '问自己：这个异常**是否会导致**用户最终看到的问题？', '- 如果能建立因果链 → 保留，继续分析', '- 如果只是时间上巧合 → 标记为"疑似无关"，暂时跳过', '- 不确定 → 先分析最明显相关的，再回头验证', '', '### 第三步：定位直接代码', '用筛选后的关键词搜索代码，找到**直接产生**该现象的代码行。', '搜索范围要足够广，不要局限在你假设的位置。', '', '### 第四步：向上追溯调用链', '从第三步的代码向上追溯：谁调用了它？在什么条件下触发？', '直到找到**用户操作**或**外部输入**为止。', '', '### 第五步：验证因果关系', '**关键验证**：这条调用链走到底，是否**真的会产生**用户看到的最终现象？', '- 如果是 → 进入修复', '- 如果不是 → 回到第一步，分析其他现象', '', '### 第六步：确定阻断点并修复', '在调用链中选择**最合适的阻断点**进行修复。', '', '---', '', '## 追踪链强制输出（修复前必须完成）', '', '```', '最终现象：[用户实际看到的问题是什么]', '相关异常：[哪些日志/报错与最终现象有因果关系]', '排除异常：[哪些报错判断为无关，为什么]', '搜索词：[用于代码搜索的关键词]', '直接代码：[file:line - 哪行代码产生了这个现象]', '调用链：[调用者1] → [调用者2] → [直接代码]', '因果验证：[这条链如何导致最终现象]', '阻断点：[在哪里修复，为什么选这里]', '```', '', '⛔ **禁止**：', '- 追踪链未完成就给修复方案', '- 追踪链中出现"可能"、"也许"、"应该是"', '- 跳过搜索直接假设问题位置', '- 把时间上巧合的报错当作原因', '', ].join('\n') : ''; // 给 AI 的提示词（文本兜底：即使客户端不读取 aiDirectives，也尽量让模型遵守） const aiPrompt = [ '---', '🛑🛑🛑 **[AI 强制指令 - 必须首先执行]** 🛑🛑🛑', '', '以下规则是 pingcode-mcp 的交互协议（不是普通备注）。', bugAnalysisPrompt, '**单任务模式已激活，违反以下规则将导致工作流失败：**', '1. **STOP**：完成本工作项的代码修改后，必须立即停止所有操作', '2. **ASK**：停止后必须询问用户是否创建 commit（提供：使用建议 / 用户输入 / 不提交）', '3. **WAIT**：必须等待用户回复后，才能处理下一个工作项', '4. **禁止**：禁止同时修改多个工作项；禁止批量完成后统一询问；禁止在用户回复前获取下一个工作项', '', `**开始前确认**：AI 必须先输出 "${requiredFirstOutput}"`, '', '**内容解析**：描述与评论冲突以评论为准；多条更新按时间倒序；图片可能包含关键信息', '', '**Commit 信息**：', `- 建议 commit：${suggestedMsg}`, '---', '', ].join('\n'); return { success: true, data: aiPrompt + getWorkItemString(workItem), workItem, aiDirectives, nextRequiredAction: { type: 'announce_single_task_mode', blocked_until_user_reply: false, required_output: requiredFirstOutput, }, }; } catch (error: any) { return { success: false, error: error.message, }; } }
• src/index.ts:58-72 (registration)

  Registration of the 'get_work_item' tool in the MCP server's ListTools handler, defining name, description, and input schema.
  { name: 'get_work_item', description: '通过 PingCode 工作项编号获取详情。支持格式：#12345、12345、LFY-123 等。', inputSchema: { type: 'object', properties: { identifier: { type: 'string', description: '工作项编号，如 #12345、12345 或 LFY-123', }, }, required: ['identifier'], }, },
• src/index.ts:209-234 (handler)

  MCP server CallToolRequestSchema dispatch handler for 'get_work_item', extracts identifier argument, calls the implementation getWorkItem, and formats the MCP response with text content and structured data.
  case 'get_work_item': { const identifier = (args as { identifier: string }).identifier; const result = await getWorkItem(identifier); if (!result.success) { return { content: [{ type: 'text', text: `错误: ${result.error}` }], isError: true, }; } return { content: [ { type: 'text', text: result.data!, // 结构化数据：供 MCP 客户端/模型可靠读取 data: { work_item: result.workItem, ai_directives: result.aiDirectives, next_required_action: result.nextRequiredAction, }, }, ] as any, }; }
• src/tools/work-items.ts:54-87 (schema)

  Type definitions for FieldData and WorkItemData used for structured output of the work item details in the tool response.
  export interface FieldData { label: string; value: string; } /** * 工作项格式化后的数据结构 */ export interface WorkItemData { /**编号 */ id: FieldData; /**标题 */ title: FieldData; /** 类型 */ type: FieldData; /** 状态 */ state: FieldData; /** 优先级 */ priority: FieldData; /** 负责人 */ assignee: FieldData; /** 创建人 */ createdBy: FieldData; /** 创建时间 */ createdAt: FieldData; /** 更新时间 */ updatedAt: FieldData; /** 描述 */ description: FieldData; /** 附件列表 */ attachments: Array<{ name: string; url: string }>; /** 评论列表 */ comments: Array<{ author: string; time: string; content: string }>; }
• src/tools/work-items.ts:179-224 (helper)

  Helper function to convert formatted WorkItemData into a human-readable Markdown string for the tool response.
  function getWorkItemString(data: WorkItemData): string { const lines: string[] = [ `## ${data.id.value} - ${data.title.value}`, '', `- **${data.type.label}**: ${data.type.value}`, `- **${data.state.label}**: ${data.state.value}`, `- **${data.priority.label}**: ${data.priority.value}`, `- **${data.assignee.label}**: ${data.assignee.value}`, ]; if (data.createdBy.value) { lines.push(`- **${data.createdBy.label}**: ${data.createdBy.value}`); } if (data.createdAt.value) { lines.push(`- **${data.createdAt.label}**: ${data.createdAt.value}`); } if (data.updatedAt.value) { lines.push(`- **${data.updatedAt.label}**: ${data.updatedAt.value}`); } if (data.description.value) { lines.push('', `### ${data.description.label}`, '', data.description.value); } if (data.attachments.length > 0) { lines.push('', '### 附件', ''); data.attachments.forEach((att) => { if (att.url) { lines.push(`- [${att.name}](${att.url})`); } else { lines.push(`- ${att.name}`); } }); } if (data.comments.length > 0) { lines.push('', `### 评论 (${data.comments.length})`, ''); data.comments.forEach((comment, index) => { lines.push(`**${index + 1}. ${comment.author}** (${comment.time}):`); lines.push(`> ${comment.content}`); lines.push(''); }); } return lines.join('\n'); }