Norman Finance MCP Server

Instructions

Update a tax setting. Always generate a preview of the tax report @generate_finanzamt_preview before submitting it to the Finanzamt.

Args:
    setting_id: Public ID of the tax setting to update
    tax_type: Type of tax (e.g. "sales")
    vat_type: VAT type (e.g. "vat_subject")
    vat_percent: VAT percentage
    start_tax_report_date: Start date for tax reporting (YYYY-MM-DD)
    reporting_frequency: Frequency of reporting (e.g. "monthly")
    
Returns:
    Updated tax setting

Implementation Reference

• norman_mcp/tools/taxes.py:214-261 (handler)

  Implementation of the update_tax_setting tool handler. Updates company tax settings by making a PATCH request to the API with the provided parameters.

  async def update_tax_setting(
      ctx: Context,
      setting_id: str = Field(description="Public ID of the tax setting to update"),
      tax_type: Optional[str] = Field(description="Type of tax (e.g. 'sales')"),
      vat_type: Optional[str] = Field(description="VAT type (e.g. 'vat_subject')"),
      vat_percent: Optional[float] = Field(description="VAT percentage"),
      start_tax_report_date: Optional[str] = Field(description="Start date for tax reporting (YYYY-MM-DD)"),
      reporting_frequency: Optional[str] = Field(description="Frequency of reporting (e.g. 'monthly')")
  ) -> Dict[str, Any]:
      """
      Update a tax setting. Always generate a preview of the tax report @generate_finanzamt_preview before submitting it to the Finanzamt.
      
      Args:
          setting_id: Public ID of the tax setting to update
          tax_type: Type of tax (e.g. "sales"); Options: "sales", "trade", "income", "profit_loss"
          vat_type: VAT type (e.g. "vat_subject"), Options: "vat_subject", "kleinunternehmer", "vat_exempt"
          vat_percent: VAT percentage; Options: 0, 7, 19
          start_tax_report_date: Start date for tax reporting (YYYY-MM-DD)
          reporting_frequency: Frequency of reporting (e.g. "monthly"), Options: "monthly", "quarterly", "yearly"
          
      Returns:
          Updated tax setting
      """
      api = ctx.request_context.lifespan_context["api"]
      
      setting_url = urljoin(
          config.api_base_url,
          f"api/v1/taxes/tax-settings/{setting_id}/"
      )
      
      update_data = {}
      if tax_type:
          update_data["taxType"] = tax_type
      if vat_type:
          update_data["vatType"] = vat_type
      if vat_percent is not None:
          update_data["vatPercent"] = vat_percent
      if start_tax_report_date:
          update_data["startTaxReportDate"] = start_tax_report_date
      if reporting_frequency:
          update_data["reportingFrequency"] = reporting_frequency
          
      # Only make request if there are changes
      if update_data:
          return api._make_request("PATCH", setting_url, json_data=update_data)
      else:
          return {"message": "No changes to apply"}

• norman_mcp/server.py:327-336 (registration)

  Top-level registration of tool sets in the MCP server creation, including tax tools which registers the update_tax_setting tool.

  # Register all tools
  register_client_tools(server)
  register_invoice_tools(server)
  register_tax_tools(server)
  register_transaction_tools(server)
  register_document_tools(server)
  register_company_tools(server)
  register_prompts(server)
  register_resources(server)

• norman_mcp/tools/taxes.py:214-222 (schema)

  Pydantic Field definitions providing input schema and descriptions for the tool parameters, including allowed options in docstring.

  async def update_tax_setting(
      ctx: Context,
      setting_id: str = Field(description="Public ID of the tax setting to update"),
      tax_type: Optional[str] = Field(description="Type of tax (e.g. 'sales')"),
      vat_type: Optional[str] = Field(description="VAT type (e.g. 'vat_subject')"),
      vat_percent: Optional[float] = Field(description="VAT percentage"),
      start_tax_report_date: Optional[str] = Field(description="Start date for tax reporting (YYYY-MM-DD)"),
      reporting_frequency: Optional[str] = Field(description="Frequency of reporting (e.g. 'monthly')")
  ) -> Dict[str, Any]: