AEAT MCP Server

Instructions

Implementation Reference

• src/tools/get_irpf_brackets.ts:40-83 (handler)

  The async handler function that executes the logic for the get_irpf_brackets tool, including data loading, error handling, and result formatting.

  async ({ year, type }) => {
    const data = loadData(year);
    if (!data) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              error: "no_data",
              message: `No IRPF data available for year ${year}. Available years: 2025.`,
            }),
          },
        ],
      };
    }
  
    const brackets =
      type === "savings"
        ? data.savings_brackets
        : data.general_brackets;
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              year,
              type,
              level: "state",
              note: "These are state-level rates only (approximately half of total IRPF). Regional (CCAA) rates are added on top.",
              brackets: brackets.state,
              source: brackets.source,
              verified_date: data.verified_date,
              disclaimer:
                "Informational only. Does not constitute tax advice.",
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/get_irpf_brackets.ts:27-39 (schema)

  The Zod schema defining the input parameters (year and type) for the tool.

  {
    year: z
      .number()
      .int()
      .min(2024)
      .max(2026)
      .describe("Fiscal year (2024-2026)"),
    type: z
      .enum(["general", "savings"])
      .optional()
      .default("general")
      .describe("Bracket type: 'general' (work income) or 'savings' (capital gains)"),
  },

• src/tools/get_irpf_brackets.ts:18-85 (registration)

  The registration function that defines the MCP tool using the McpServer instance.

  export function registerIrpfBracketsTool(server: McpServer) {
    server.tool(
      "get_irpf_brackets",
      "Returns Spanish IRPF (income tax) brackets for a given fiscal year. " +
        "type='general' returns the base general (work/business income) brackets. " +
        "type='savings' returns the base del ahorro (capital gains/dividends) brackets. " +
        "These are STATE-level rates only (roughly half of the total rate). " +
        "The other half comes from the CCAA regional scale. " +
        "Source: Ley 35/2006, arts. 63 and 66.",
      {
        year: z
          .number()
          .int()
          .min(2024)
          .max(2026)
          .describe("Fiscal year (2024-2026)"),
        type: z
          .enum(["general", "savings"])
          .optional()
          .default("general")
          .describe("Bracket type: 'general' (work income) or 'savings' (capital gains)"),
      },
      async ({ year, type }) => {
        const data = loadData(year);
        if (!data) {
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  error: "no_data",
                  message: `No IRPF data available for year ${year}. Available years: 2025.`,
                }),
              },
            ],
          };
        }
  
        const brackets =
          type === "savings"
            ? data.savings_brackets
            : data.general_brackets;
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  year,
                  type,
                  level: "state",
                  note: "These are state-level rates only (approximately half of total IRPF). Regional (CCAA) rates are added on top.",
                  brackets: brackets.state,
                  source: brackets.source,
                  verified_date: data.verified_date,
                  disclaimer:
                    "Informational only. Does not constitute tax advice.",
                },
                null,
                2
              ),
            },
          ],
        };
      }
    );
  }