Norman Finance MCP Server

Instructions

Submit a tax report to the Finanzamt.

Args:
    report_id: Public ID of the tax report to submit
    
Returns:
    Response from the submission request and a link to the tax report from reportFile to download.
    If response status is 403, it means a paid subscription is required to file the report.

Implementation Reference

• norman_mcp/tools/taxes.py:152-184 (handler)

  The core handler function for the 'submit_tax_report' tool. It performs a POST request to the API endpoint to submit the tax report for the given report_id. Includes inline schema validation via Pydantic Field and docstring. Handles 403 errors by returning a subscription required message. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def submit_tax_report(
      ctx: Context,
      report_id: str = Field(description="Public ID of the tax report to submit")
  ) -> Dict[str, Any]:
      """
      Submit a tax report to the Finanzamt.
      
      Args:
          report_id: Public ID of the tax report to submit
          
      Returns:
          Response from the submission request and a link to the tax report from reportFile to download.
          If response status is 403, it means a paid subscription is required to file the report.
      """
      api = ctx.request_context.lifespan_context["api"]
      
      submit_url = urljoin(
          config.api_base_url,
          f"api/v1/taxes/reports/{report_id}/submit-report/"
      )
      
      try:
          return api._make_request("POST", submit_url)
      except requests.exceptions.HTTPError as e:
          if e.response.status_code == 403:
              return {
                  "error": "Subscription required",
                  "message": "You need a paid subscription to file tax reports. Please subscribe before submitting.",
                  "status_code": 403
              }
          raise

• norman_mcp/server.py:330-330 (registration)

  The registration of tax tools (including submit_tax_report) by calling register_tax_tools(server) in the create_app function. This imports and invokes the registration function from taxes.py which defines and registers the tool using @mcp.tool() decorators.

  register_tax_tools(server)

• norman_mcp/server.py:18-18 (registration)

  Import of register_tax_tools from taxes.py, enabling the registration of the submit_tax_report tool.

  from norman_mcp.tools.taxes import register_tax_tools