Frappe MCP Server

Instructions

    Get metadata for a specific report including columns and filters.
    
    Args:
        report_name: Name of the report to get metadata for
    

Implementation Reference

• src/tools/reports.py:92-126 (handler)

  The main handler function for the 'get_report_meta' tool. It fetches the Report document metadata from the Frappe API using the provided report_name, formats key fields into a metadata dictionary, and returns it as indented JSON. Includes error handling with _format_error_response.

  async def get_report_meta(report_name: str) -> str:
      """
      Get metadata for a specific report including columns and filters.
      
      Args:
          report_name: Name of the report to get metadata for
      """
      try:
          client = get_client()
          
          # Get report document
          response = await client.get(f"api/resource/Report/{report_name}")
          
          if "data" in response:
              report_data = response["data"]
              
              # Format metadata
              metadata = {
                  "report_name": report_name,
                  "report_type": report_data.get("report_type"),
                  "module": report_data.get("module"),
                  "is_standard": report_data.get("is_standard"),
                  "ref_doctype": report_data.get("ref_doctype"),
                  "query": report_data.get("query"),
                  "columns": report_data.get("columns", []),
                  "filters": report_data.get("filters", [])
              }
              
              return json.dumps(metadata, indent=2)
          else:
              return json.dumps(response, indent=2)
              
      except Exception as error:
          return _format_error_response(error, "get_report_meta")

• src/server.py:42-42 (registration)

  The registration call for the reports module, which includes the get_report_meta tool via its register_tools function decorated with @mcp.tool() decorators.

  reports.register_tools(mcp)

• src/tools/reports.py:16-35 (helper)

  Helper function used by get_report_meta (and other tools) to format error responses, handling authentication checks, Frappe API errors, and general exceptions with operation-specific messages.

  def _format_error_response(error: Exception, operation: str) -> str:
      """Format error response with detailed information."""
      credentials_check = validate_api_credentials()
      
      # Check for missing credentials first
      if not credentials_check["valid"]:
          error_msg = f"Authentication failed: {credentials_check['message']}. "
          error_msg += "API key/secret is the only supported authentication method."
          return error_msg
      
      # Handle FrappeApiError
      if isinstance(error, FrappeApiError):
          error_msg = f"Frappe API error: {error}"
          if error.status_code in (401, 403):
              error_msg += " Please check your API key and secret."
          return error_msg
      
      # Default error handling
      return f"Error in {operation}: {str(error)}"