create_purchase_voucher

Instructions

Implementation Reference

• src/tallyprime_mcp/tools/vouchers.py:72-108 (handler)

  MCP tool handler for 'create_purchase_voucher'. Defined as an async function inside the `register()` closure, decorated with @mcp.tool(). Accepts date, party_ledger, purchase_ledger, amount, narration, tax_ledger, tax_amount. Calls `client.create_purchase_voucher(...)` and returns a formatted success/error string.

  @mcp.tool()
  async def create_purchase_voucher(
      date: str,
      party_ledger: str,
      purchase_ledger: str,
      amount: float,
      narration: str = "",
      tax_ledger: str = "",
      tax_amount: float = 0.0,
  ) -> str:
      """
      Create a purchase invoice in TallyPrime.
  
      Args:
          date: Voucher date YYYYMMDD.
          party_ledger: Supplier ledger name.
          purchase_ledger: Purchase account ledger name.
          amount: Invoice amount excluding tax.
          narration: Optional description.
          tax_ledger: GST or tax ledger name (optional).
          tax_amount: Tax amount (optional, default 0).
      """
      try:
          result = await client.create_purchase_voucher(
              date=date, party_ledger=party_ledger, purchase_ledger=purchase_ledger,
              amount=amount, narration=narration, tax_ledger=tax_ledger, tax_amount=tax_amount,
          )
          if result["success"]:
              total = amount + tax_amount
              msg = f"Purchase voucher created. Supplier: {party_ledger}, Amount: {amount:.2f}"
              if tax_amount:
                  msg += f" + Tax: {tax_amount:.2f}"
              msg += f", Total: {total:.2f}, Date: {date}"
              return msg
          return f"Failed: {result['message']}"
      except TallyError as e:
          return f"Error: {e}"

• src/tallyprime_mcp/tools/vouchers.py:82-93 (schema)

  Docstring/input schema for create_purchase_voucher. Defines the expected parameters: date (YYYYMMDD), party_ledger (supplier), purchase_ledger, amount, narration, tax_ledger (optional), tax_amount (optional).

  """
  Create a purchase invoice in TallyPrime.
  
  Args:
      date: Voucher date YYYYMMDD.
      party_ledger: Supplier ledger name.
      purchase_ledger: Purchase account ledger name.
      amount: Invoice amount excluding tax.
      narration: Optional description.
      tax_ledger: GST or tax ledger name (optional).
      tax_amount: Tax amount (optional, default 0).
  """

• src/tallyprime_mcp/tools/__init__.py:7-12 (registration)

  Registration entry point. `register_all()` in tools/__init__.py calls `vouchers.register(mcp, client)`, which internally creates the 'create_purchase_voucher' tool via the @mcp.tool() decorator in vouchers.py.

  def register_all(mcp: FastMCP, client: TallyClient):
      company.register(mcp, client)
      ledgers.register(mcp, client)
      vouchers.register(mcp, client)
      reports.register(mcp, client)

• src/tallyprime_mcp/tally_client.py:121-123 (helper)

  TallyClient method that bridges the MCP handler to the XML builder. Calls `create_purchase_voucher_xml(**kwargs)` to build the XML, sends it via `send_xml`, parses the response, and checks the import result.

  async def create_purchase_voucher(self, **kwargs) -> dict:
      from .xml_builder import create_purchase_voucher_xml
      return self._check_import_result(self._parse(await self.send_xml(create_purchase_voucher_xml(**kwargs))))

• src/tallyprime_mcp/xml_builder.py:253-287 (helper)

  XML builder for purchase vouchers. Constructs a TDL XML request string with VCHTYPE='Purchase'. Creates ledger entries: party_ledger (cr, positive total), purchase_ledger (dr, negative amount), and optional tax_ledger entry. Wraps in `_voucher_import_envelope`.

  def create_purchase_voucher_xml(
      date: str,
      party_ledger: str,
      purchase_ledger: str,
      amount: float,
      narration: str = "",
      tax_ledger: str = "",
      tax_amount: float = 0.0,
  ) -> str:
      total = amount + tax_amount
      tax_entry = ""
      if tax_ledger and tax_amount:
          tax_entry = f"""<ALLLEDGERENTRIES.LIST>
              <LEDGERNAME>{tax_ledger}</LEDGERNAME>
              <ISDEEMEDPOSITIVE>Yes</ISDEEMEDPOSITIVE>
              <AMOUNT>-{tax_amount}</AMOUNT>
            </ALLLEDGERENTRIES.LIST>"""
  
      voucher = f"""<VOUCHER ACTION="Create" VCHTYPE="Purchase">
            <DATE>{date}</DATE>
            <VOUCHERTYPENAME>Purchase</VOUCHERTYPENAME>
            <NARRATION>{narration}</NARRATION>
            <ALLLEDGERENTRIES.LIST>
              <LEDGERNAME>{party_ledger}</LEDGERNAME>
              <ISDEEMEDPOSITIVE>No</ISDEEMEDPOSITIVE>
              <AMOUNT>{total}</AMOUNT>
            </ALLLEDGERENTRIES.LIST>
            <ALLLEDGERENTRIES.LIST>
              <LEDGERNAME>{purchase_ledger}</LEDGERNAME>
              <ISDEEMEDPOSITIVE>Yes</ISDEEMEDPOSITIVE>
              <AMOUNT>-{amount}</AMOUNT>
            </ALLLEDGERENTRIES.LIST>
            {tax_entry}
          </VOUCHER>"""
      return _voucher_import_envelope(voucher)