PingCode MCP Server

Instructions

Implementation Reference

• src/tools/work-items.ts:707-755 (handler)

  Primary handler function for the 'update_work_item_state' tool. Resolves the state name to a state ID by fetching selectable states and calls the API client to update the work item.

  export async function updateWorkItemState(
    workItemId: string,
    stateName: string
  ): Promise<{
    success: boolean;
    data?: string;
    error?: string;
  }> {
    try {
      // 1. 获取可选状态列表
      const states = await pingcodeClient.getSelectableStates(workItemId);
  
      if (states.length === 0) {
        return {
          success: false,
          error: `工作项 ${workItemId} 没有可用的状态选项`,
        };
      }
  
      // 2. 根据状态名称查找状态 ID
      const targetState = states.find((s: any) =>
        s.name === stateName ||
        s.display_name === stateName ||
        s.name?.includes(stateName) ||
        s.display_name?.includes(stateName)
      );
  
      if (!targetState) {
        const availableStates = states.map((s: any) => s.display_name || s.name).join('、');
        return {
          success: false,
          error: `未找到名为 "${stateName}" 的状态。可用状态: ${availableStates}`,
        };
      }
  
      // 3. 更新状态
      await pingcodeClient.updateWorkItemState(workItemId, targetState._id);
  
      return {
        success: true,
        data: `✅ 工作项 ${workItemId} 状态已更新为 "${targetState.display_name || targetState.name}"`,
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.message,
      };
    }
  }

• src/index.ts:138-155 (registration)

  Tool registration in the MCP server's listTools response, defining the tool name, description, and input schema.

  {
    name: 'update_work_item_state',
    description: '更新工作项（缺陷/需求/任务）的状态。通过状态名称指定目标状态。',
    inputSchema: {
      type: 'object',
      properties: {
        work_item_id: {
          type: 'string',
          description: '工作项编号，如 LFY-2527',
        },
        state_name: {
          type: 'string',
          description: '目标状态名称，如 "已完成"、"进行中"、"待处理"',
        },
      },
      required: ['work_item_id', 'state_name'],
    },
  },

• src/index.ts:298-313 (handler)

  Dispatch handler in the CallToolRequestSchema that extracts arguments and invokes the updateWorkItemState function.

  case 'update_work_item_state': {
    const { work_item_id, state_name } = args as {
      work_item_id: string;
      state_name: string;
    };
    const result = await updateWorkItemState(work_item_id, state_name);
    return {
      content: [
        {
          type: 'text',
          text: result.success ? result.data! : `错误: ${result.error}`,
        },
      ],
      isError: !result.success,
    };
  }

• src/api/pingcode-client.ts:448-467 (helper)

  API client method that performs the actual HTTP PUT request to update the work item state on PingCode.

  async updateWorkItemState(workItemId: string, stateId: string): Promise<any> {
    const headers = this.getAuthHeaders();
  
    // 清理编号格式
    const cleanId = workItemId.replace(/^#/, '').trim();
  
    try {
      const response = await this.client.put(
        `/api/agile/work-items/${cleanId}`,
        { state: stateId },
        { headers }
      );
      return response.data?.data?.value || response.data?.value || response.data;
    } catch (error: any) {
      if (error.response?.status === 401) {
        throw new Error('登录已过期，请重新调用 login 工具登录');
      }
      throw error;
    }
  }

• src/api/pingcode-client.ts:422-441 (helper)

  Helper method to fetch the list of selectable states for a work item, used to resolve state name to ID.

  async getSelectableStates(workItemId: string): Promise<any[]> {
    const headers = this.getAuthHeaders();
  
    // 清理编号格式
    const cleanId = workItemId.replace(/^#/, '').trim();
  
    try {
      const response = await this.client.get(
        `/api/agile/work-items/${cleanId}/selectable-states`,
        { headers }
      );
      // API 返回格式: { "data": [...] }
      return response.data?.data || response.data?.value || [];
    } catch (error: any) {
      if (error.response?.status === 401) {
        throw new Error('登录已过期，请重新调用 login 工具登录');
      }
      throw error;
    }
  }