Norman Finance MCP Server

Instructions

Implementation Reference

• norman_mcp/tools/company.py:47-106 (handler)

  The core handler function for the 'update_company_details' tool. It updates optional company fields by making a PATCH request to the Norman API after fetching current data.

  @mcp.tool()
  async def update_company_details(
      ctx: Context,
      name: Optional[str] = None,
      profession: Optional[str] = None,
      address: Optional[str] = None,
      zip_code: Optional[str] = None,
      city: Optional[str] = None,
      country: Optional[str] = None,
      vat_id: Optional[str] = None,
      tax_id: Optional[str] = None,
      phone: Optional[str] = None,
      tax_state: Optional[str] = None,
      activity_start: Optional[datetime] = None,
  ) -> Dict[str, Any]:
      """Update company information."""
      api = ctx.request_context.lifespan_context["api"]
      company_id = api.company_id
      
      if not company_id:
          return {"error": "No company available. Please authenticate first."}
      
      company_url = urljoin(config.api_base_url, f"api/v1/companies/{company_id}/")
      
      # Get current company data
      current_data = api._make_request("GET", company_url)
      
      # Update only provided fields
      update_data = {}
      
      if name:
          update_data["name"] = name
      if profession:
          update_data["profession"] = profession
      if address:
          update_data["address"] = address
      if zip_code:
          update_data["zipCode"] = zip_code
      if city:
          update_data["city"] = city
      if country:
          update_data["country"] = country
      if vat_id:
          update_data["vatNumber"] = vat_id
      if tax_id:
          update_data["taxNumber"] = tax_id
      if phone:
          update_data["phoneNumber"] = phone
      if tax_state:
          update_data["taxState"] = tax_state
      if activity_start:
          update_data["activityStart"] = activity_start
  
      # If no fields provided, return current data
      if not update_data:
          return {"message": "No fields provided for update.", "company": current_data}
      
      # Update company data
      updated_company = api._make_request("PATCH", company_url, json_data=update_data)
      return {"message": "Company updated successfully", "company": updated_company} 

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

  Main server setup where register_company_tools(server) is called, which in turn registers the update_company_details tool via its @mcp.tool() decorator.

  # 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)