@wallacewen/tapd-mcp-server
Version:
Model Context Protocol server for TAPD (Tencent Agile Product Development) - Provides professional weekly report generation and timesheet analysis
962 lines (889 loc) • 36.8 kB
JavaScript
#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { TAPDClient } from './tapd.js';
import { z } from 'zod';
import dotenv from 'dotenv';
// Load environment variables
dotenv.config();
if (!StdioServerTransport.prototype.connect) {
StdioServerTransport.prototype.connect = async function () {
// Dummy connect method for compatibility with MCP server
return Promise.resolve();
};
}
/**
* Validate required environment variables
*/
function validateEnvironmentVariables() {
const requiredEnvVars = {
TAPD_BASE_URL: process.env.TAPD_BASE_URL,
TAPD_WORKFLOW_API_KEY: process.env.TAPD_WORKFLOW_API_KEY,
TAPD_BUG_WORKFLOW_API_KEY: process.env.TAPD_BUG_WORKFLOW_API_KEY,
TAPD_WORKFLOW_USER_ID: process.env.TAPD_WORKFLOW_USER_ID,
};
const missingVars = Object.entries(requiredEnvVars)
.filter(([key, value]) => !value)
.map(([key]) => key);
if (missingVars.length > 0) {
console.error('❌ Missing required environment variables:');
missingVars.forEach((varName) => {
console.error(` - ${varName}`);
});
console.error('\n💡 Please set these environment variables before starting the server.');
console.error(' You can create a .env file or set them in your environment.');
console.error('\n📚 See ENVIRONMENT_SETUP.md for detailed configuration guide.');
process.exit(1);
}
console.log('✅ All required environment variables are configured');
}
// Validate environment variables on startup
if (process.env.NODE_ENV !== 'test') {
validateEnvironmentVariables();
}
/**
* Helper function to convert null to undefined
* @param value Any value that might be null
* @returns The original value or undefined if null
*/
function nullToUndefined(value) {
return value === null ? undefined : value;
}
// Initialize MCP server
export const mcpServer = new McpServer({
name: 'tapd-mcp-server',
version: '1.2.0',
});
const client = new TAPDClient(process.env.TAPD_BASE_URL);
/**
* Handler for querying TAPD time sheets for weekly report generation
* @param params Parameters for querying time sheets
* @returns Promise with the time sheet query result
*/
export async function handleTAPDQueryTimeSheets(params) {
try {
const queryParams = {
name: params.name,
startDate: params.start_date,
endDate: params.end_date,
};
const result = await client.queryTimeSheets(queryParams);
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: result.success,
message: result.message,
total: result.total,
data: result.data.map((entry) => ({
id: entry.id,
name: entry.name,
date: entry.date,
hours: entry.hours,
project: entry.project,
task: entry.task,
description: entry.description,
...entry,
})),
}, null, 2),
},
],
};
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: false,
message: `Failed to query time sheets: ${errorMessage}`,
total: 0,
data: [],
}, null, 2),
},
],
};
}
}
/**
* Handler for selecting TAPD time sheet data for mantis operation analysis
* @param params Parameters for selecting time sheet data
* @returns Promise with the mantis analysis result
*/
export async function handleTAPDSelectTimeSheet(params) {
try {
const selectParams = {
startDate: params.start_date,
endDate: params.end_date,
};
const result = await client.selectTimeSheet(selectParams);
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: result.success,
message: result.message,
total: result.total,
data: result.data.map((entry) => ({
id: entry.id,
date: entry.date,
hours: entry.hours,
project: entry.project,
task: entry.task,
description: entry.description,
analysisType: entry.analysisType,
severity: entry.severity,
status: entry.status,
...entry,
})),
}, null, 2),
},
],
};
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: false,
message: `Failed to select time sheet: ${errorMessage}`,
total: 0,
data: [],
}, null, 2),
},
],
};
}
}
/**
* Handler for generating weekly report using workflow API
* @param params Parameters for generating weekly report with specific start and end dates
* @returns Promise with the weekly report generation result
*/
export async function handleWorkflowWeeklyReport(params) {
try {
// Get configuration from environment variables
const workflowApiKey = process.env.TAPD_WORKFLOW_API_KEY;
const workflowUserId = process.env.TAPD_WORKFLOW_USER_ID;
const workflowBaseUrl = process.env.TAPD_WORKFLOW_URL || 'https://faq-flow.chinahuanong.com.cn';
const workflowUrl = `${workflowBaseUrl.replace(/\/$/, '')}/v1/workflows/run`;
if (!workflowApiKey || !workflowUserId) {
throw new Error('TAPD_WORKFLOW_API_KEY and TAPD_WORKFLOW_USER_ID environment variables are required for weekly report generation');
}
const reportText = `你是一个项目管理大咖，从专业的角度，帮我生成周报，起始日期：${params.week_start_date}，截止日期：${params.week_end_date}，项目：${params.project_name}。要求：${params.additional_context ? `\n${params.additional_context}` : '\n周报'}`;
const requestBody = {
inputs: {
txt: reportText,
},
user: workflowUserId,
response_mode: 'blocking',
};
const response = await fetch(workflowUrl, {
method: 'POST',
headers: {
Authorization: `Bearer ${workflowApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(requestBody),
});
if (!response.ok) {
throw new Error(`Workflow API request failed: ${response.status} ${response.statusText}`);
}
const result = await response.json();
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: true,
message: 'Weekly report generated successfully',
data: {
project_name: params.project_name,
week_start_date: params.week_start_date,
week_end_date: params.week_end_date,
report_content: result,
generation_time: new Date().toISOString(),
},
}, null, 2),
},
],
};
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: false,
message: `Failed to generate weekly report: ${errorMessage}`,
data: null,
}, null, 2),
},
],
};
}
}
/**
* Handler for running workflow to query TAPD bug list and details
* @param params Parameters for workflow run
* @returns Promise with the workflow run result
*/
export async function handleBugAnalysisWorkflow(params) {
try {
// Get bug workflow configuration from environment variables
const bugWorkflowApiKey = process.env.TAPD_BUG_WORKFLOW_API_KEY;
const workflowUserId = process.env.TAPD_WORKFLOW_USER_ID || 'squ_df9f02baf35492ac997de6155f1b08b38e6f72a2';
const workflowBaseUrl = process.env.TAPD_WORKFLOW_URL || 'https://faq-flow.chinahuanong.com.cn';
const workflowUrl = `${workflowBaseUrl.replace(/\/$/, '')}/v1/workflows/run`;
if (!bugWorkflowApiKey) {
throw new Error('TAPD_BUG_WORKFLOW_API_KEY environment variable is required for bug analysis');
}
// 构建 inputs 对象，参考 POST 请求格式
const inputs = {};
if (params.user_name)
inputs.user_name = params.user_name;
if (params.project_name)
inputs.project_name = params.project_name;
if (params.msg)
inputs.msg = params.msg;
if (params.page_no)
inputs.page_no = params.page_no;
if (params.page_size)
inputs.page_size = params.page_size;
const requestBody = {
inputs,
user: workflowUserId,
response_mode: 'blocking',
};
console.log('发送Bug工作流请求:', {
url: workflowUrl,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${bugWorkflowApiKey}`,
},
data: requestBody,
});
const response = await fetch(workflowUrl, {
method: 'POST',
headers: {
Authorization: `Bearer ${bugWorkflowApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(requestBody),
});
if (!response.ok) {
throw new Error(`Bug workflow API request failed: ${response.status} ${response.statusText}`);
}
const result = await response.json();
console.log('Bug工作流响应:', {
status: response.status,
data: result,
});
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: true,
message: result.data?.error || 'Success',
outputs: result.outputs || result.data?.outputs || {},
}, null, 2),
},
],
};
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
console.error('Bug工作流请求失败:', error);
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: false,
message: `Failed to run bug analysis workflow: ${errorMessage}`,
outputs: {},
}, null, 2),
},
],
};
}
}
// Register TAPD tools for personal professional weekly report summary
mcpServer.tool('personal_weekly_report', 'Generate comprehensive personal professional weekly report summary including work achievements, project progress, task completion, time allocation, and professional development insights. This tool provides detailed weekly work analysis from TAPD data for creating structured professional reports.', {
employee_name: z
.string()
.min(1, 'Employee name is required')
.describe('Name of the employee whose weekly professional report data you want to generate (work achievements, project status, professional development)'),
week_start_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
.describe('Start date of the week (YYYY-MM-DD format, typically Monday) for professional report period'),
week_end_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
.describe('End date of the week (YYYY-MM-DD format, typically Sunday) for professional report period'),
}, async (params) => {
return handleTAPDQueryTimeSheets({
name: params.employee_name,
start_date: params.week_start_date,
end_date: params.week_end_date,
});
});
// Register TAPD tools for project team weekly report summary
mcpServer.tool('project_weekly_report', 'Generate comprehensive project team weekly report summary including team collaboration, project progress, resource allocation, task distribution, and team performance insights. This tool provides detailed team work analysis from TAPD data for creating structured project team reports with precise date ranges.', {
project_name: z
.string()
.min(1, 'Project name is required')
.describe('Name of the project for which you want to generate AI-powered weekly report (e.g., "阿凡达", "Phoenix项目", "移动端开发")'),
week_start_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
.describe('Start date of the week (YYYY-MM-DD format, typically Monday) for project report period'),
week_end_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
.describe('End date of the week (YYYY-MM-DD format, typically Sunday) for project report period'),
additional_context: z
.string()
.optional()
.describe('Additional context or specific requirements for the weekly report (e.g., "重点关注性能优化", "包含风险分析", "突出团队协作亮点")'),
}, async (params) => {
const reportParams = {
project_name: params.project_name,
week_start_date: params.week_start_date,
week_end_date: params.week_end_date,
};
if (params.additional_context) {
reportParams.additional_context = params.additional_context;
}
return handleWorkflowWeeklyReport(reportParams);
});
// Register TAPD tools for mantis operation analysis
mcpServer.tool('mantis_operation_analysis', 'Select and analyze TAPD time sheet data for mantis operation analysis including system maintenance, bug fixes, performance monitoring, and operational tasks. This tool provides detailed mantis operation analysis from TAPD data for creating structured operation reports with precise date ranges.', {
start_date: z
.string()
.regex(/^\d{8}$/, 'Date must be in YYYYMMDD format')
.describe('Start date of the analysis period (YYYYMMDD format, e.g., 20250619) for mantis operation analysis'),
end_date: z
.string()
.regex(/^\d{8}$/, 'Date must be in YYYYMMDD format')
.describe('End date of the analysis period (YYYYMMDD format, e.g., 20250627) for mantis operation analysis'),
}, async (params) => {
return handleTAPDSelectTimeSheet({
start_date: params.start_date,
end_date: params.end_date,
});
});
// Register TAPD tools for bug analysis workflow
mcpServer.tool('tapd_bug_analysis', 'Query TAPD bug information using workflow API. This tool provides comprehensive bug analysis including bug status, assignee, priority, description, and related project information through AI-powered workflow processing. Supports auto pagination - when need_next_page is true, automatically increments page_no.', {
user_name: z
.string()
.optional()
.describe('User name for bug analysis (e.g., "蒋文")'),
project_name: z
.string()
.optional()
.describe('Project name for bug analysis (e.g., "阿凡达")'),
msg: z
.string()
.optional()
.describe('Query message for bug analysis (e.g., "蒋文 阿凡达 本周 待处理的bug")'),
page_no: z
.string()
.optional()
.describe('Page number for pagination (default: "1", auto-increments when need_next_page is true)'),
page_size: z
.string()
.optional()
.describe('Page size for pagination (default: "10")'),
need_next_page: z
.boolean()
.optional()
.describe('Set to true to automatically get next page (page_no + 1). Useful for pagination.'),
}, async (params) => {
let currentPageNo = params.page_no || '1';
// 如果需要翻页，自动将页码 + 1
if (params.need_next_page) {
const pageNum = parseInt(currentPageNo, 10);
currentPageNo = String(pageNum + 1);
}
const workflowParams = {
page_no: currentPageNo,
page_size: params.page_size || '10',
};
if (params.user_name)
workflowParams.user_name = params.user_name;
if (params.project_name)
workflowParams.project_name = params.project_name;
if (params.msg)
workflowParams.msg = params.msg;
console.log(`🔄 翻页信息: 当前页码=${currentPageNo}, 需要翻页=${params.need_next_page || false}`);
return handleBugAnalysisWorkflow(workflowParams);
});
// Register MCP prompts for better AI guidance
mcpServer.prompt('weekly_report_analysis', 'Generate a comprehensive weekly work report analysis based on TAPD data', {
employee_name: z.string().describe('Name of the employee to analyze'),
week_start_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('Start date of the week (YYYY-MM-DD format)'),
week_end_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('End date of the week (YYYY-MM-DD format)'),
analysis_focus: z
.string()
.optional()
.describe('Focus area for analysis (e.g., productivity, project distribution, time allocation)'),
}, async (params) => {
const employee = params.employee_name || '员工';
const startDate = params.week_start_date || '周一';
const endDate = params.week_end_date || '周日';
const focus = params.analysis_focus || '全面分析';
return {
messages: [
{
role: 'user',
content: {
type: 'text',
text: `# ${employee}周报分析提示词
## 分析目标
为${employee}生成${startDate}到${endDate}期间的详细工作报告，重点关注${focus}。
## 分析步骤
1. **获取工作数据**
使用personal_weekly_report工具获取${employee}在指定日期范围内的工作数据
2. **数据分析维度**
- **工作量分析**: 统计总工时、每日工时分布、工作强度
- **项目分布**: 分析参与的项目数量、各项目工时占比
- **任务类型**: 统计不同类型任务的时间分配（开发、测试、文档等）
- **工作效率**: 分析任务完成情况、进度评估
- **专业发展**: 识别技能应用和成长点
3. **报告结构**
- 📊 **工作概览**: 总工时、项目数量、主要成就
- 🎯 **项目详情**: 各项目工作内容、进展状态、时间投入
- ⏰ **时间分配**: 工时分布图表、效率分析
- ✅ **完成情况**: 任务完成率、质量评估
- 🚀 **亮点与建议**: 工作亮点、改进建议、下周规划
## 输出格式
生成结构化的markdown格式周报，包含数据可视化建议和专业分析。`,
},
},
],
};
});
mcpServer.prompt('project_team_analysis', 'Analyze team work distribution and collaboration patterns for a specific project', {
project_name: z.string().describe('Name of the project to analyze'),
team_members: z.string().describe('Comma-separated list of team member names'),
week_start_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('Start date of the analysis period (YYYY-MM-DD format)'),
week_end_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('End date of the analysis period (YYYY-MM-DD format)'),
}, async (params) => {
const project = params.project_name || '项目';
const members = params.team_members || '团队成员';
const startDate = params.week_start_date || '开始日期';
const endDate = params.week_end_date || '结束日期';
return {
messages: [
{
role: 'user',
content: {
type: 'text',
text: `# ${project}项目团队协作分析
## 分析目标
分析${project}项目在${startDate}到${endDate}期间的团队工作分布和协作模式。
## 团队成员: ${members}
## 分析步骤
1. **获取团队数据**
为每个团队成员使用project_weekly_report工具获取工作数据
2. **团队协作分析**
- **人员投入**: 各成员在项目中的工时投入和参与度
- **任务分工**: 不同角色的任务分配和专业化程度
- **协作模式**: 团队合作任务、交接工作、支持关系
- **进度同步**: 各成员工作进度的协调性
- **资源利用**: 团队整体效率和资源配置
3. **输出内容**
- 👥 **团队概览**: 总体工时、参与人数、项目进展
- 📊 **人员分布**: 各成员工时占比、贡献度分析
- 🔄 **协作网络**: 成员间协作关系、沟通模式
- 📈 **效率评估**: 团队生产力、协作效率
- 💡 **优化建议**: 资源调配建议、流程改进方案
## 期望输出
生成详细的团队协作分析报告，包含数据驱动的洞察和可行的改进建议。`,
},
},
],
};
});
mcpServer.prompt('personal_productivity_insights', 'Generate personal productivity insights and recommendations based on work patterns', {
employee_name: z.string().describe('Name of the employee to analyze'),
analysis_period_weeks: z
.string()
.optional()
.describe('Number of weeks to analyze (default: 4)'),
current_date: z.string().optional().describe('Current date for reference (YYYY-MM-DD format)'),
}, async (params) => {
const employee = params.employee_name || '员工';
const weeks = params.analysis_period_weeks || '4';
const currentDate = params.current_date || '今天';
return {
messages: [
{
role: 'user',
content: {
type: 'text',
text: `# ${employee}个人效率分析与优化建议
## 分析范围
基于${currentDate}向前${weeks}周的工作数据，深入分析${employee}的工作模式和效率表现。
## 分析框架
### 1. 工作模式识别
- **时间偏好**: 识别高效工作时段和工作节奏
- **任务类型偏好**: 分析擅长的工作类型和领域
- **项目参与模式**: 单项目深入 vs 多项目并行的适应性
- **工作强度分析**: 工时分布的合理性和可持续性
### 2. 效率指标评估
- **任务完成率**: 计划与实际完成情况对比
- **时间估算准确性**: 预期工时与实际工时的偏差分析
- **专注度评估**: 任务切换频率和深度工作时间
- **质量稳定性**: 不同类型任务的完成质量一致性
### 3. 成长轨迹分析
- **技能发展**: 新技能学习和应用情况
- **挑战应对**: 复杂任务的处理能力变化
- **协作能力**: 团队合作和沟通效率提升
- **自我管理**: 时间管理和优先级把握能力
### 4. 个性化建议
- 🎯 **效率优化**: 基于个人特点的工作方式建议
- 📅 **时间管理**: 个性化的时间分配和任务规划策略
- 🚀 **技能提升**: 针对性的能力发展建议
- ⚖️ **工作平衡**: 工作强度和生活平衡的建议
## 实施步骤
1. 收集多周工作数据进行趋势分析
2. 识别个人工作模式和效率特征
3. 对比行业/团队标准找出优势和改进点
4. 制定个性化的效率提升行动计划
## 期望成果
提供数据驱动的个人效率洞察，帮助${employee}制定科学的工作优化策略。`,
},
},
],
};
});
mcpServer.prompt('ai_workflow_report_guide', 'Guide for using AI workflow weekly report generation with project and specific date ranges', {
project_name: z.string().describe('Project name for the weekly report'),
week_start_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('Week start date in YYYY-MM-DD format'),
week_end_date: z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/)
.describe('Week end date in YYYY-MM-DD format'),
report_type: z
.string()
.optional()
.describe('Type of report focus (e.g., progress, risks, achievements)'),
}, async (params) => {
const project = params.project_name || '项目';
const weekStartDate = params.week_start_date || '2025-06-09';
const weekEndDate = params.week_end_date || '2025-06-15';
const reportType = params.report_type || '综合周报';
return {
messages: [
{
role: 'user',
content: {
type: 'text',
text: `# AI工作流周报生成指南
## 🎯 功能说明
使用AI工作流API为${project}项目生成${weekStartDate}至${weekEndDate}期间的${reportType}，支持按项目和精确日期范围进行智能化周报生成。
## 📋 使用方法
### 基础调用
使用 \`project_weekly_report\` 工具，参数包括：
- **project_name**: 项目名称（如："阿凡达"、"Phoenix项目"）
- **week_start_date**: 周开始日期，格式YYYY-MM-DD（如："2025-06-09"）
- **week_end_date**: 周结束日期，格式YYYY-MM-DD（如："2025-06-15"）
- **additional_context**: 附加要求（可选）
### 示例调用
\`\`\`json
{
"project_name": "阿凡达",
"week_start_date": "2025-06-09",
"week_end_date": "2025-06-15",
"additional_context": "重点关注性能优化和风险分析"
}
\`\`\`
## 🔍 报告特点
### 智能化分析
- **项目维度**: 按项目组织工作内容和进展
- **时间维度**: 以周为单位进行时间段分析
- **AI增强**: 利用先进AI模型提供洞察和建议
### 内容结构
- 📊 **工作概览**: 本周整体工作情况
- 🎯 **项目进展**: 各项目具体进展和里程碑
- ⚠️ **风险识别**: 潜在问题和风险点分析
- 💡 **改进建议**: AI驱动的优化建议
- 📅 **下周规划**: 基于当前进展的下周工作计划
## ⚙️ 高级功能
### 上下文定制
通过 \`additional_context\` 参数可以指定：
- 特定关注点："重点关注技术债务"
- 报告风格："需要详细的数据支撑"
- 特殊要求："包含团队协作分析"
### 集成优势
- 与现有TAPD数据无缝结合
- 支持多项目并行分析
- 提供标准化报告格式
- 自动化减少手工整理时间
## 💡 最佳实践
1. **项目命名**: 使用准确的项目名称以获得最佳结果
2. **日期选择**: 选择有代表性的一周日期
3. **上下文丰富**: 提供具体的分析要求和关注点
4. **定期使用**: 建立周期性报告生成习惯
## 🔄 与其他工具配合
- 结合 \`personal_weekly_report\` 获取个人数据
- 配合 \`project_weekly_report\` 进行团队分析
- 使用 \`tapd_bug_analysis\` 根据bug ID查看具体bug详情
- 配合 \`mantis_operation_analysis\` 进行运维问题的深度分析
- 利用提示词进行深度数据挖掘
这个工具特别适合需要高质量、结构化周报的项目管理和团队协作场景。`,
},
},
],
};
});
mcpServer.prompt('tapd_data_query_guide', 'Guide for effectively using TAPD MCP server to query and analyze work data', {}, async () => {
return {
messages: [
{
role: 'user',
content: {
type: 'text',
text: `# TAPD MCP 服务器使用指南
## 🔧 可用工具
### personal_weekly_report
**功能**: 生成个人专业周报信息总结
### project_weekly_report
**功能**: 生成项目组周报总结
### project_weekly_report
**功能**: 使用AI工作流生成智能化周报（按项目和精确日期范围）
### mantis_operation_analysis
**功能**: 选择和分析TAPD工时数据用于mantis运维分析
### tapd_bug_analysis
**功能**: 运行工作流查询TAPD项目bug问题列表及明细情况，进行修复分析
### tapd_bug_analysis
**功能**: 根据bug ID查询TAPD特定bug的详细信息，进行深度分析
### personal_weekly_report 详细说明
**参数**:
- \`employee_name\`: 员工姓名（必需）
- \`week_start_date\`: 周开始日期，格式YYYY-MM-DD（必需）
- \`week_end_date\`: 周结束日期，格式YYYY-MM-DD（必需）
### mantis_operation_analysis 详细说明
**参数**:
- \`start_date\`: 开始日期，格式YYYYMMDD（必需）
- \`end_date\`: 结束日期，格式YYYYMMDD（必需）
### tapd_bug_analysis 详细说明
**参数**:
- \`msg\`: 查询消息，格式如"项目名 用户名 从日期起 列表"（必需）
**配置**:
- API密钥: 自动使用环境变量 \`TAPD_BUG_WORKFLOW_API_KEY\` 配置
- 用户ID: 自动使用环境变量 \`TAPD_WORKFLOW_USER_ID\` 配置
- 响应模式: 固定为 "blocking"
- 工作流URL: 固定为 https://faq-flow.chinahuanong.com.cn
### tapd_bug_analysis 详细说明
**参数**:
- \`bug_id\`: TAPD bug ID，用于查询具体bug详情（必需）
**功能特点**:
- 自动格式化查询消息为"{bug_id} 详情"
- 获取bug的完整信息包括状态、负责人、优先级、描述等
- 提供解决时间线和项目关联信息
- 支持复杂bug问题的深度分析
**配置**:
- API密钥: 自动使用环境变量 \`TAPD_BUG_WORKFLOW_API_KEY\` 配置
- 用户ID: 自动使用环境变量 \`TAPD_WORKFLOW_USER_ID\` 配置
- 响应模式: 固定为 "blocking"
- 工作流URL: 固定为 https://faq-flow.chinahuanong.com.cn
**返回数据结构**:
\`\`\`json
{
"success": true,
"message": "Success",
"total": 25,
"data": [
{
"id": "analysis_0",
"date": "2025-06-19",
"hours": 4,
"project": "系统运维",
"task": "mantis问题处理",
"description": "处理系统bug和性能问题",
"analysisType": "mantis",
"severity": "中",
"status": "已完成"
}
]
}
\`\`\`
### tapd_bug_analysis 返回数据结构
\`\`\`json
{
"success": true,
"message": "Success",
"outputs": {
"查询列表结果": "项目：保险商城，用户：吕甜颖，在 2025-07-01 至 2025-07-06 期间，未解决BUG数：1 个<br/><br/><ol>\\n<li><a href='https://www.tapd.cn/tapd_fe/60986462/bug/detail/1160986462001026025'>1160986462001026025</a> - 【测试环境】，一个保单数据出现6条埋点轨迹数据， <a href=>解决</a> </li>\\n</ol>"
}
}
\`\`\`
### tapd_bug_analysis 返回数据结构
\`\`\`json
{
"success": true,
"message": "Success",
"outputs": {
"提取明细结果": "缺陷ID： <a href='https://www.tapd.cn/tapd_fe/60986462/bug/detail/1160986462001026025'>1160986462001026025</a><br/><br/>缺陷标题：【测试环境】，一个保单数据出现6条埋点轨迹数据，<br/><br/>报告人：外包_侯明卫<br/><br/>缺陷详情： <div><div><div><span style=\"color: #ff3b30;\">【测试数据】：open_id ='DS112333933697440558';</span></div></div><div><span style=\"color: #ff0000;\">【缺陷描述】<span style=\"color: #000000;\">：测试环境，一个保单数据出现6条埋点轨迹数据，</span></span></div></div> 缺陷图片识别结果：\n1、无法识别<br/><a href='https://file.tapd.cn/tfl/captures/2025-07/tapd_60986462_base64_1751332191_547.png'>源图片地址</a>"
}
}
\`\`\`
**返回数据结构**:
\`\`\`json
{
"success": true,
"message": "Success",
"total": 56,
"data": [
{
"id": "276493_0",
"name": "员工姓名",
"date": "2025-05-23",
"hours": 6,
"project": "项目名称",
"task": "任务标题",
"description": "任务描述",
"storyTitle": "需求标题",
"storyId": "需求ID",
"taskType": "任务类型",
"taskClassify": "任务分类",
"storyStatus": "需求状态",
"storyIteration": "迭代版本",
"totalHours": 28,
"taskCompletion": "100"
}
]
}
\`\`\`
## 🔧 环境变量配置
确保设置以下环境变量：
- \`TAPD_BASE_URL\`: TAPD API 基础URL
- \`TAPD_WORKFLOW_API_KEY\`: 项目周报工作流API密钥
- \`TAPD_BUG_WORKFLOW_API_KEY\`: Bug工作流API密钥
- \`TAPD_WORKFLOW_USER_ID\`: 工作流用户ID
## 📊 常用查询模式
### 1. 单日工作查询
\`\`\`
员工姓名: "张三"
开始日期: "2025-05-23"
结束日期: "2025-05-23"
\`\`\`
### 2. 完整周报查询
\`\`\`
员工姓名: "张三"
开始日期: "2025-05-20" (周一)
结束日期: "2025-05-26" (周日)
\`\`\`
### 3. 自定义时间段
\`\`\`
员工姓名: "张三"
开始日期: "2025-05-01"
结束日期: "2025-05-31"
\`\`\`
### 4. AI工作流周报生成
\`\`\`
项目名称: "阿凡达"
周开始日期: "2025-06-09"
周结束日期: "2025-06-15"
附加要求: "重点关注性能优化"
\`\`\`
### 5. mantis运维分析
\`\`\`
开始日期: "20250619"
结束日期: "20250627"
\`\`\`
### 6. TAPD Bug分析
\`\`\`
查询消息: "吕甜颖 商城从2025-07-01起 列表"
\`\`\`
**更多示例**:
\`\`\`
"张三 阿凡达从2025-06-01起 列表"
"李四 移动端项目从2025-07-10起 列表"
"王五 后台管理系统从2025-07-01起 列表"
\`\`\`
### 7. TAPD Bug分析
\`\`\`
Bug ID: "1160986462001026057"
\`\`\`
**更多示例**:
\`\`\`
"1160986462001026025"
"1160986462001026033"
"1160986462001026041"
\`\`\`
**自动生成的查询消息**:
- 输入: "1160986462001026057"
- 实际查询: "1160986462001026057 详情"
## 🎯 数据分析技巧
### 工时统计
- 使用 \`hours\` 字段计算总工时
- 使用 \`total\` 字段获取系统统计的总工时
- 按 \`project\` 字段分组统计项目工时
### 任务分析
- 使用 \`taskType\` 分析任务类型分布
- 使用 \`taskClassify\` 分析工作分类
- 使用 \`taskCompletion\` 评估完成度
### 项目追踪
- 使用 \`storyTitle\` 和 \`storyId\` 追踪需求
- 使用 \`storyIteration\` 分析版本进度
- 使用 \`storyStatus\` 查看需求状态
## 💡 最佳实践
1. **日期格式**:
- 个人/项目周报: 始终使用YYYY-MM-DD格式
- mantis运维分析: 始终使用YYYYMMDD格式
2. **姓名准确性**: 确保员工姓名与TAPD系统中完全一致
3. **合理时间范围**: 避免查询过长时间段，影响性能
4. **数据验证**: 检查返回的success字段确认查询成功
5. **运维分析**: 使用mantis_operation_analysis专门分析系统运维和bug处理工作
6. **Bug分析**: 使用tapd_bug_analysis工作流查询项目bug列表和修复明细
7. **Bug分析**: 使用tapd_bug_analysis根据具体bug ID获取详细信息，支持深度分析
## ⚠️ 注意事项
- 查询结果依赖TAPD系统中的实际数据录入
- 空数据可能表示该时间段无工作记录或姓名不匹配
- Bug ID必须是有效的TAPD系统中的真实ID
- 系统默认连接地址: http://porsche-tapd-inc.chinahuanong.com.cn`,
},
},
],
};
});
// Only start the server if not in test mode
/* istanbul ignore if */
if (process.env.NODE_ENV !== 'test') {
const transport = new StdioServerTransport();
await transport.connect();
await mcpServer.connect(transport);
}
export { nullToUndefined };
//# sourceMappingURL=index.js.map