inoreader-mcp

Instructions

Implementation Reference

• src/tools/reading.ts:172-211 (handler)

  The handler function that executes get_article_ids logic. Accepts optional stream_id, count, filter, since, and continuation parameters. Makes an API call to /reader/api/0/stream/items/ids and returns article IDs, count, and continuation token.

  async (params) => {
    const streamId = params.stream_id ?? "user/-/state/com.google/reading-list";
    const queryParams: Record<string, string> = {
      output: "json",
      n: String(params.count ?? 1000),
      s: streamId,
    };
  
    if (params.continuation) queryParams.c = params.continuation;
    if (params.since) {
      queryParams.ot = String(Math.floor(new Date(params.since).getTime() / 1000));
    }
    if (params.filter === "unread") {
      queryParams.xt = "user/-/state/com.google/read";
    } else if (params.filter === "starred") {
      queryParams.it = "user/-/state/com.google/starred";
    }
  
    const data = await apiGet<StreamItemIdsResponse>(
      "/reader/api/0/stream/items/ids",
      queryParams
    );
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              ids: data.itemRefs.map((r) => r.id),
              count: data.itemRefs.length,
              continuation: data.continuation ?? null,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/reading.ts:148-171 (schema)

  Zod schema defining input validation for get_article_ids tool. Parameters include stream_id (optional string), count (number 1-10000), filter (enum: all/unread/starred), since (ISO date), and continuation (pagination token).

  {
    stream_id: z
      .string()
      .optional()
      .describe("Stream ID (defaults to all items)"),
    count: z
      .number()
      .min(1)
      .max(10000)
      .optional()
      .describe("Number of IDs to fetch (default 1000, max 10000)"),
    filter: z
      .enum(["all", "unread", "starred"])
      .optional()
      .describe("Filter by status"),
    since: z
      .string()
      .optional()
      .describe("ISO date - only items after this date"),
    continuation: z
      .string()
      .optional()
      .describe("Continuation token for pagination"),
  },

• src/tools/reading.ts:145-212 (registration)

  MCP server.tool() registration for get_article_ids. Registers the tool with name 'get_article_ids', description, schema, and handler function. Uses server.tool() method from @modelcontextprotocol/sdk.

  server.tool(
    "get_article_ids",
    "Lightweight fetch of article IDs from a stream without full content. Useful for counting or batch operations. Costs 1 Zone 1 request.",
    {
      stream_id: z
        .string()
        .optional()
        .describe("Stream ID (defaults to all items)"),
      count: z
        .number()
        .min(1)
        .max(10000)
        .optional()
        .describe("Number of IDs to fetch (default 1000, max 10000)"),
      filter: z
        .enum(["all", "unread", "starred"])
        .optional()
        .describe("Filter by status"),
      since: z
        .string()
        .optional()
        .describe("ISO date - only items after this date"),
      continuation: z
        .string()
        .optional()
        .describe("Continuation token for pagination"),
    },
    async (params) => {
      const streamId = params.stream_id ?? "user/-/state/com.google/reading-list";
      const queryParams: Record<string, string> = {
        output: "json",
        n: String(params.count ?? 1000),
        s: streamId,
      };
  
      if (params.continuation) queryParams.c = params.continuation;
      if (params.since) {
        queryParams.ot = String(Math.floor(new Date(params.since).getTime() / 1000));
      }
      if (params.filter === "unread") {
        queryParams.xt = "user/-/state/com.google/read";
      } else if (params.filter === "starred") {
        queryParams.it = "user/-/state/com.google/starred";
      }
  
      const data = await apiGet<StreamItemIdsResponse>(
        "/reader/api/0/stream/items/ids",
        queryParams
      );
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                ids: data.itemRefs.map((r) => r.id),
                count: data.itemRefs.length,
                continuation: data.continuation ?? null,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/types.ts:60-63 (schema)

  Type definition for StreamItemIdsResponse - the API response type used by get_article_ids. Contains itemRefs array with id and timestampUsec, plus optional continuation token.

  export interface StreamItemIdsResponse {
    itemRefs: Array<{ id: string; timestampUsec: string }>;
    continuation?: string;
  }

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

  Import statement that brings in registerReadingTools function which contains the get_article_ids tool registration. Called on line 63 to register all reading tools with the MCP server.

  import { registerReadingTools } from "./tools/reading.js";