XMLTV MCP Server

Instructions

Implementation Reference

• src/index.ts:149-177 (handler)

  The core handler function that implements the get_schedule tool logic: fetches XMLTV data, filters and sorts programmes for the specified channel within the given hours ahead, and maps to the output format.

  async function getSchedule(channelId: string, hoursAhead: number = 24) {
    const data = await getXmltvData();
    const now = new Date();
    const endTime = new Date(now.getTime() + hoursAhead * 60 * 60 * 1000);
  
    const schedule = data.tv.programme
      .filter(prog => {
        if (prog.channel !== channelId) return false;
        const start = parseXmltvDate(prog.start);
        return start >= now && start <= endTime;
      })
      .sort((a, b) => a.start.localeCompare(b.start))
      .map(prog => ({
        title: prog.title,
        subtitle: prog["sub-title"],
        description: prog.desc,
        start: prog.start,
        stop: prog.stop,
        episodeNum: Array.isArray(prog["episode-num"])
          ? prog["episode-num"][0]
          : prog["episode-num"],
        rating: Array.isArray(prog.rating)
          ? prog.rating[0]?.value
          : prog.rating?.value,
        date: prog.date,
      }));
  
    return schedule;
  }

• src/index.ts:283-296 (schema)

  Input schema for the get_schedule tool, defining required channel_id and optional hours_ahead parameters.

  inputSchema: {
    type: "object",
    properties: {
      channel_id: {
        type: "string",
        description: "Channel ID (e.g., C1.49.tunarr.com)",
      },
      hours_ahead: {
        type: "number",
        description: "Number of hours to look ahead (default: 24)",
      },
    },
    required: ["channel_id"],
  },

• src/index.ts:280-297 (registration)

  Tool registration entry in the tools array, which is returned by ListToolsRequest handler.

  {
    name: "get_schedule",
    description: "Get upcoming schedule for a specific channel",
    inputSchema: {
      type: "object",
      properties: {
        channel_id: {
          type: "string",
          description: "Channel ID (e.g., C1.49.tunarr.com)",
        },
        hours_ahead: {
          type: "number",
          description: "Number of hours to look ahead (default: 24)",
        },
      },
      required: ["channel_id"],
    },
  },

• src/index.ts:363-377 (handler)

  MCP protocol handler case that extracts arguments, calls the getSchedule function, and formats the response for CallToolRequest.

  case "get_schedule": {
    const { channel_id, hours_ahead } = request.params.arguments as {
      channel_id: string;
      hours_ahead?: number;
    };
    const schedule = await getSchedule(channel_id, hours_ahead);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(schedule, null, 2),
        },
      ],
    };
  }