Frihet MCP Server

Instructions

Implementation Reference

• src/tools/expenses.ts:94-103 (handler)

  The async handler function that executes the create_expense tool logic. It receives validated input, calls the client's createExpense method to make the API request, and returns the formatted response or handles errors.

  async (input) => {
    try {
      const result = await client.createExpense(input);
      return {
        content: [{ type: "text", text: formatRecord("Expense created", result) }],
      };
    } catch (error) {
      return handleToolError(error);
    }
  },

• src/tools/expenses.ts:76-92 (schema)

  Input schema definition for create_expense using Zod. Defines required fields (description, amount) and optional fields (category, date, vendor, taxDeductible) with validation rules and bilingual descriptions.

  inputSchema: {
    description: z.string().describe("Expense description / Descripcion del gasto"),
    amount: z.number().describe("Amount in EUR / Importe en EUR"),
    category: z
      .string()
      .optional()
      .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
    date: z
      .string()
      .optional()
      .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
    vendor: z.string().optional().describe("Vendor/supplier name / Nombre del proveedor"),
    taxDeductible: z
      .boolean()
      .optional()
      .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
  },

• src/tools/expenses.ts:66-104 (registration)

  Complete tool registration for create_expense with the MCP server. Includes tool name, title, description, annotations (CREATE_ANNOTATIONS), input schema, and the handler function.

  server.registerTool(
    "create_expense",
    {
      title: "Create Expense",
      description:
        "Record a new expense. Requires a description and amount. " +
        "Useful for tracking business costs, deductible expenses, and vendor payments. " +
        "/ Registra un nuevo gasto. Requiere descripcion e importe. " +
        "Util para seguimiento de costes, gastos deducibles y pagos a proveedores.",
      annotations: CREATE_ANNOTATIONS,
      inputSchema: {
        description: z.string().describe("Expense description / Descripcion del gasto"),
        amount: z.number().describe("Amount in EUR / Importe en EUR"),
        category: z
          .string()
          .optional()
          .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
        date: z
          .string()
          .optional()
          .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
        vendor: z.string().optional().describe("Vendor/supplier name / Nombre del proveedor"),
        taxDeductible: z
          .boolean()
          .optional()
          .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
      },
    },
    async (input) => {
      try {
        const result = await client.createExpense(input);
        return {
          content: [{ type: "text", text: formatRecord("Expense created", result) }],
        };
      } catch (error) {
        return handleToolError(error);
      }
    },
  );

• src/client.ts:229-231 (helper)

  The FrihetClient method that performs the actual HTTP POST request to /expenses endpoint to create an expense in the Frihet ERP API.

  async createExpense(data: Record<string, unknown>): Promise<Record<string, unknown>> {
    return this.request("POST", "/expenses", data);
  }

• src/types.ts:75-76 (schema)

  TypeScript type definition for CreateExpenseInput, which requires description and amount fields and optionally allows category, date, vendor, and taxDeductible fields.

  export type CreateExpenseInput = Pick<Expense, "description" | "amount"> &
    Partial<Pick<Expense, "category" | "date" | "vendor" | "taxDeductible">>;