POHODA MCP Server

Instructions

Implementation Reference

• src/tools/invoices.ts:75-165 (handler)

  The implementation of the `pohoda_create_invoice` MCP tool, including its Zod schema definition, XML request builder construction, and result handling.

  server.tool(
    "pohoda_create_invoice",
    "Create a new invoice in POHODA. Requires invoiceType and date. Optional: dateTax, dateDue, dateAccounting, text, partner details, symbols, note, and line items.",
    {
      invoiceType: invoiceTypeEnum.describe("Invoice type (required)"),
      date: z.string().describe("Invoice date (DD.MM.YYYY or YYYY-MM-DD)"),
      dateTax: z.string().optional().describe("Tax date"),
      dateDue: z.string().optional().describe("Due date"),
      dateAccounting: z.string().optional().describe("Accounting date"),
      text: z.string().optional().describe("Invoice text/description"),
      partnerName: z.string().optional().describe("Partner company name"),
      partnerStreet: z.string().optional().describe("Partner street"),
      partnerCity: z.string().optional().describe("Partner city"),
      partnerZip: z.string().optional().describe("Partner ZIP code"),
      partnerIco: z.string().optional().describe("Partner IČO"),
      partnerDic: z.string().optional().describe("Partner DIČ"),
      symVar: z.string().optional().describe("Variable symbol"),
      symConst: z.string().optional().describe("Constant symbol"),
      symSpec: z.string().optional().describe("Specific symbol"),
      note: z.string().optional().describe("Note"),
      intNote: z.string().optional().describe("Internal note"),
      items: z
        .array(invoiceItemSchema)
        .optional()
        .describe("Line items: text, quantity, unitPrice, rateVAT (none|low|high), optional unit, code"),
    },
    async (params) => {
      try {
        const xml = buildImportDoc({ ico: client.ico }, (item) => {
          const inv = item.ele(NS.inv, "inv:invoice").att("version", "2.0");
          const header = inv.ele(NS.inv, "inv:invoiceHeader");
  
          header.ele(NS.inv, "inv:invoiceType").txt(params.invoiceType);
          header.ele(NS.inv, "inv:date").txt(toIsoDate(params.date));
          if (params.dateTax) header.ele(NS.inv, "inv:dateTax").txt(toIsoDate(params.dateTax));
          if (params.dateDue) header.ele(NS.inv, "inv:dateDue").txt(toIsoDate(params.dateDue));
          if (params.dateAccounting)
            header.ele(NS.inv, "inv:dateAccounting").txt(toIsoDate(params.dateAccounting));
          if (params.text) header.ele(NS.inv, "inv:text").txt(params.text);
  
          const hasPartner =
            params.partnerName ??
            params.partnerStreet ??
            params.partnerCity ??
            params.partnerZip ??
            params.partnerIco ??
            params.partnerDic;
          if (hasPartner) {
            const identity = header.ele(NS.inv, "inv:partnerIdentity");
            const typAddr = identity.ele(NS.typ, "typ:address");
            if (params.partnerName) typAddr.ele(NS.typ, "typ:name").txt(params.partnerName);
            if (params.partnerStreet) typAddr.ele(NS.typ, "typ:street").txt(params.partnerStreet);
            if (params.partnerCity) typAddr.ele(NS.typ, "typ:city").txt(params.partnerCity);
            if (params.partnerZip) typAddr.ele(NS.typ, "typ:zip").txt(params.partnerZip);
            if (params.partnerIco) typAddr.ele(NS.typ, "typ:ico").txt(params.partnerIco);
            if (params.partnerDic) typAddr.ele(NS.typ, "typ:dic").txt(params.partnerDic);
          }
  
          if (params.symVar) header.ele(NS.inv, "inv:symVar").txt(params.symVar);
          if (params.symConst) header.ele(NS.inv, "inv:symConst").txt(params.symConst);
          if (params.symSpec) header.ele(NS.inv, "inv:symSpec").txt(params.symSpec);
          if (params.note) header.ele(NS.inv, "inv:note").txt(params.note);
          if (params.intNote) header.ele(NS.inv, "inv:intNote").txt(params.intNote);
  
          if (params.items && params.items.length > 0) {
            const detail = inv.ele(NS.inv, "inv:invoiceDetail");
            for (const it of params.items) {
              const invItem = detail.ele(NS.inv, "inv:invoiceItem");
              invItem.ele(NS.inv, "inv:text").txt(it.text);
              invItem.ele(NS.inv, "inv:quantity").txt(String(it.quantity));
              if (it.unit) invItem.ele(NS.inv, "inv:unit").txt(it.unit);
              invItem.ele(NS.inv, "inv:rateVAT").txt(it.rateVAT);
              invItem.ele(NS.inv, "inv:homeCurrency").ele(NS.typ, "typ:unitPrice").txt(String(it.unitPrice));
              if (it.code) invItem.ele(NS.inv, "inv:code").txt(it.code);
            }
          }
  
          inv.ele(NS.inv, "inv:invoiceSummary");
        });
        const response = await client.sendXml(xml);
        const result = extractImportResult(parseResponse(response));
        return result.success
          ? ok(
              `Invoice created successfully.${result.producedId != null ? ` ID: ${result.producedId}` : ""} ${result.message}`
            )
          : err(result.message);
      } catch (e) {
        return err((e as Error).message);
      }
    }
  );