manage_dlq

Instructions

Implementation Reference

• src/tools/manage-dlq.ts:16-90 (handler)

  The handler function `manageDlq` processes the 'list' and 'replay' actions for managing the Upstash QStash dead letter queue.

  export async function manageDlq(input: ManageDlqInput) {
    const controls = createTernControls({
      token: input.qstashToken,
    })
  
    if (input.action === 'list') {
      try {
        const failed = await controls.dlq()
        if (!failed.length) {
          return {
            action: 'list',
            count: 0,
            message: '✓ Dead letter queue is empty. No failed events.',
            events: [],
          }
        }
  
        return {
          action: 'list',
          count: failed.length,
          message: `${failed.length} failed event${failed.length === 1 ? '' : 's'} in dead letter queue`,
          events: failed.map((event: any) => ({
            dlqId: event.dlqId,
            messageId: event.messageId,
            url: event.url,
            createdAt: event.createdAt,
            responseStatus: event.responseStatus,
            responseBody: event.responseBody,
            retried: event.retried,
          })),
          nextStep: 'Use action: replay with a dlqId to replay a specific event',
        }
      } catch (error) {
        return {
          action: 'list',
          error: (error as Error).message,
          tip: 'Check your QSTASH_TOKEN is correct and Upstash account is active',
        }
      }
    }
  
    if (input.action === 'replay') {
      if (!input.dlqId) {
        return {
          action: 'replay',
          error: 'dlqId is required for replay action',
          tip: 'Run list action first to get the dlqId of the event you want to replay',
        }
      }
  
      try {
        const result = await controls.replay(input.dlqId)
        return {
          action: 'replay',
          success: true,
          dlqId: input.dlqId,
          message: `✓ Event ${input.dlqId} replayed successfully`,
          result,
        }
      } catch (error) {
        return {
          action: 'replay',
          success: false,
          dlqId: input.dlqId,
          error: (error as Error).message,
          tip: 'Check the dlqId is correct and the event still exists in the DLQ',
        }
      }
    }
  
    return {
      action: input.action,
      error: 'Unsupported action',
    }
  }

• src/tools/manage-dlq.ts:4-12 (schema)

  Zod schema defining the input requirements for the `manage_dlq` tool.

  export const manageDlqSchema = z.object({
    action: z.enum(['list', 'replay'])
      .describe('Action to perform: list DLQ events or replay a failed event'),
    qstashToken: z.string()
      .describe('Your Upstash QStash token from environment'),
    dlqId: z.string()
      .optional()
      .describe('DLQ event ID to replay — required for replay action'),
  })

• src/index.ts:78-89 (registration)

  Tool registration in the MCP server's `ListToolsRequestSchema` handler.

    name: 'manage_dlq',
    description: 'Manage your Tern dead letter queue — list all failed webhook events or replay a specific failed event. Powered by Upstash QStash.',
    inputSchema: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['list', 'replay'], description: 'list — show all failed events, replay — retry a specific event' },
        qstashToken: { type: 'string', description: 'Upstash QStash token — use process.env.QSTASH_TOKEN' },
        dlqId: { type: 'string', description: 'DLQ event ID — required for replay action' },
      },
      required: ['action', 'qstashToken'],
    },
  },

• src/index.ts:105-107 (handler)

  Tool execution logic in the MCP server's `CallToolRequestSchema` handler, where the `manage_dlq` tool is called.

  } else if (name === 'manage_dlq') {
    const input = manageDlqSchema.parse(args)
    result = await manageDlq(input)