zeph_list

Instructions

Implementation Reference

• src/tools/list.ts:30-44 (handler)

  The handler function that executes the 'zeph_list' tool logic. It calls client.listPushes({limit, type}) and returns a summary array of pushes (pushId, type, title, body truncated to 100 chars, createdAt) along with total count and pagination status.

  async ({ limit, type }) => {
    try {
      const result = await client.listPushes({ limit, type });
      const summary = result.data.map((p) => ({
        pushId: p.pushId,
        type: p.type,
        title: p.title,
        body: p.body?.slice(0, 100),
        createdAt: p.createdAt,
      }));
      return textResult({ pushes: summary, total: summary.length, hasMore: result.pagination.hasMore });
    } catch (err) {
      return formatToolError(err);
    }
  },

• src/tools/list.ts:9-29 (schema)

  Input schema definition for 'zeph_list'. Defines a 'limit' param (number, 1-20, default 5) and optional 'type' param (enum: note/link/file/clipboard/hook). Includes annotations (readOnlyHint: true).

  {
    description:
      'List recent push notifications. Use this to check notification history, avoid duplicates, or reference previous messages.',
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
    inputSchema: {
      limit: z
        .number()
        .min(1)
        .max(20)
        .default(5)
        .describe('Number of pushes to return (default: 5, max: 20)'),
      type: z
        .enum(['note', 'link', 'file', 'clipboard', 'hook'])
        .optional()
        .describe('Filter by push type'),
    },
  },

• src/tools/list.ts:6-46 (registration)

  The registerListTool function that registers the 'zeph_list' tool on the MCP server via server.registerTool('zeph_list', ...).

  export const registerListTool = (server: McpServer, client: ZephApiClient) => {
    server.registerTool(
      'zeph_list',
      {
        description:
          'List recent push notifications. Use this to check notification history, avoid duplicates, or reference previous messages.',
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          openWorldHint: true,
        },
        inputSchema: {
          limit: z
            .number()
            .min(1)
            .max(20)
            .default(5)
            .describe('Number of pushes to return (default: 5, max: 20)'),
          type: z
            .enum(['note', 'link', 'file', 'clipboard', 'hook'])
            .optional()
            .describe('Filter by push type'),
        },
      },
      async ({ limit, type }) => {
        try {
          const result = await client.listPushes({ limit, type });
          const summary = result.data.map((p) => ({
            pushId: p.pushId,
            type: p.type,
            title: p.title,
            body: p.body?.slice(0, 100),
            createdAt: p.createdAt,
          }));
          return textResult({ pushes: summary, total: summary.length, hasMore: result.pagination.hasMore });
        } catch (err) {
          return formatToolError(err);
        }
      },
    );
  };

• src/index.ts:62-62 (registration)

  Registration call site: registerListTool(server, client) is invoked during server setup in the main entry point.

  registerListTool(server, client);

• src/api-client.ts:73-78 (helper)

  The listPushes method on ZephApiClient that makes the GET /pushes HTTP request with optional query params (limit, type). Returns PushListResponse.

  async listPushes(params?: { limit?: number; type?: string }): Promise<PushListResponse> {
    const query = new URLSearchParams();
    if (params?.limit) query.set('limit', String(params.limit));
    if (params?.type) query.set('type', params.type);
    const qs = query.toString();
    return this.request<PushListResponse>('GET', `/pushes${qs ? `?${qs}` : ''}`);