PingCode MCP Server

Instructions

Implementation Reference

• src/tools/work-items.ts:482-565 (handler)

  Core handler function that retrieves work items associated with a release, groups them by type (bugs, stories, others), resolves assignee names using project members, and formats the output as a categorized Markdown list.

  export async function getReleaseItems(
    releaseId: string,
    projectId: string,
    itemType?: 'bug' | 'story' | 'all'
  ): Promise<{
    success: boolean;
    data?: string;
    error?: string;
  }> {
    try {
      const items = await pingcodeClient.getReleaseWorkItems(
        releaseId,
        projectId,
        itemType
      );
  
      if (items.length === 0) {
        return {
          success: true,
          data: '该发布版本没有关联的工作项',
        };
      }
  
      // 获取当前用户和项目成员
      const currentUser = await pingcodeClient.getCurrentUser();
      const currentUserId = currentUser?.id || '';
      const members = await pingcodeClient.getProjectMembers(projectId);
  
      // 按类型分组 (type 是数字: 5=缺陷, 3=用户故事, 等)
      const bugs = items.filter((i: any) => i.type === 5);
      const stories = items.filter((i: any) => i.type === 3 || i.type === 2);
      const others = items.filter((i: any) => i.type !== 5 && i.type !== 3 && i.type !== 2);
  
      const lines: string[] = [`# 发布版本工作项列表`, '', `共 ${items.length} 项`];
  
      // 辅助函数
      const getId = (item: any) => item.whole_identifier || `#${item.identifier}`;
      
      const getState = (item: any) => {
        if (item.state?.display_name || item.state?.name) {
          return item.state.display_name || item.state.name;
        }
        return STATE_TYPE_MAP[item.state_type] || '未知';
      };
      
      const getAssignee = (item: any) => {
        const assigneeId = typeof item.assignee === 'string' 
          ? item.assignee 
          : item.assignee?._id || item.assignee?.id;
        if (!assigneeId) return '未分配';
        const name = members.get(assigneeId) || '未知';
        return assigneeId === currentUserId ? `${name}(我)` : name;
      };
      
      const formatItem = (item: any) => {
        return `- **${getId(item)}** ${item.title} | ${getState(item)} | ${getAssignee(item)}`;
      };
  
      if (bugs.length > 0) {
        lines.push('', `## 缺陷 (${bugs.length})`, '');
        bugs.forEach((item: any) => lines.push(formatItem(item)));
      }
  
      if (stories.length > 0) {
        lines.push('', `## 需求 (${stories.length})`, '');
        stories.forEach((item: any) => lines.push(formatItem(item)));
      }
  
      if (others.length > 0) {
        lines.push('', `## 其他 (${others.length})`, '');
        others.forEach((item: any) => lines.push(formatItem(item)));
      }
  
      return {
        success: true,
        data: lines.join('\n'),
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.message,
      };
    }
  }

• src/index.ts:73-96 (schema)

  Input schema definition for the 'get_release_items' tool, specifying parameters release_id (required), project_id (required), and optional item_type enum.

  {
    name: 'get_release_items',
    description:
      '获取某个发布版本关联的缺陷和需求列表。',
    inputSchema: {
      type: 'object',
      properties: {
        release_id: {
          type: 'string',
          description: '发布版本 ID（可从发布页面 URL 获取）',
        },
        project_id: {
          type: 'string',
          description: '项目标识，如 LFY',
        },
        item_type: {
          type: 'string',
          enum: ['bug', 'story', 'all'],
          description: '筛选工作项类型：bug=缺陷，story=需求，all=全部（默认）',
        },
      },
      required: ['release_id', 'project_id'],
    },
  },

• src/index.ts:236-252 (registration)

  Registration in the tool call handler switch statement, which extracts arguments and invokes the getReleaseItems handler function.

  case 'get_release_items': {
    const { release_id, project_id, item_type } = args as {
      release_id: string;
      project_id: string;
      item_type?: 'bug' | 'story' | 'all';
    };
    const result = await getReleaseItems(release_id, project_id, item_type);
    return {
      content: [
        {
          type: 'text',
          text: result.success ? result.data! : `错误: ${result.error}`,
        },
      ],
      isError: !result.success,
    };
  }

• src/index.ts:10-11 (registration)

  Import statement that brings the getReleaseItems function into the main index file for use in tool handling.

  import { getWorkItem, getReleaseItems, searchWorkItems, listReleases, listProjects, updateWorkItemState } from './tools/work-items.js';