list_documents

Instructions

    List documents from Frappe with filters.
    
    Args:
        doctype: DocType name
        filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues.
        fields: Comma-separated field names (optional). E.g. "name,customer,total"
        limit: Maximum number of records to return (optional). E.g. "20"
        order_by: Field to order by (optional, can include 'desc' like 'creation desc')
    
    Filter Syntax:
        - Simple equality: "field:value" -> {"field": "value"}
        - Operators: "field:operator:value" -> {"field": ["operator", value]}
        - Multiple filters: "field1:value1,field2:operator:value2"
        
    Supported Operators:
        - Equality: = (default), !=
        - Comparison: <, >, <=, >=  
        - Pattern: like, not_like (use % for wildcards)
        - Lists: in, not_in (separate values with |)
        - Null checks: is:null, is:not_null, is_not:null
        - Ranges: between (separate values with |)

    Examples:
        - list_documents("Bank Transaction", "status:Unreconciled") -> List unreconciled transactions
        - list_documents("Task", "status:in:Open|Working", "name,subject", "10") -> List open tasks with specific fields
        - list_documents("User", "name:like:%admin%") -> List users with 'admin' in name
    

Implementation Reference

• src/tools/documents.py:350-416 (handler)

  The core handler function for the 'list_documents' MCP tool. It queries the Frappe REST API (/api/resource/{doctype}) with parsed filters, optional fields, limit, and order_by. Formats results as a count and JSON dump of documents.

  @mcp.tool()
  async def list_documents(
      doctype: str,
      filters: Optional[str] = None,
      fields: Optional[str] = None,
      limit: Optional[str] = None,
      order_by: Optional[str] = None
  ) -> str:
      """
      List documents from Frappe with filters.
      
      Args:
          doctype: DocType name
          filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues.
          fields: Comma-separated field names (optional). E.g. "name,customer,total"
          limit: Maximum number of records to return (optional). E.g. "20"
          order_by: Field to order by (optional, can include 'desc' like 'creation desc')
      
      Filter Syntax:
          - Simple equality: "field:value" -> {"field": "value"}
          - Operators: "field:operator:value" -> {"field": ["operator", value]}
          - Multiple filters: "field1:value1,field2:operator:value2"
          
      Supported Operators:
          - Equality: = (default), !=
          - Comparison: <, >, <=, >=  
          - Pattern: like, not_like (use % for wildcards)
          - Lists: in, not_in (separate values with |)
          - Null checks: is:null, is:not_null, is_not:null
          - Ranges: between (separate values with |)
  
      Examples:
          - list_documents("Bank Transaction", "status:Unreconciled") -> List unreconciled transactions
          - list_documents("Task", "status:in:Open|Working", "name,subject", "10") -> List open tasks with specific fields
          - list_documents("User", "name:like:%admin%") -> List users with 'admin' in name
      """
      try:
          client = get_client()
          
          # Build query parameters
          params = {}
          parsed_filters = format_filters_for_api(filters)
          if parsed_filters:
              params["filters"] = json.dumps(parsed_filters)
          if fields:
              # Convert comma-separated string to list
              field_list = [f.strip() for f in fields.split(',')]
              params["fields"] = json.dumps(field_list)
          if limit:
              # Convert string to integer for API
              params["limit"] = limit
          if order_by:
              params["order_by"] = order_by
          
          # Make API request to list documents
          response = await client.get(f"api/resource/{doctype}", params=params)
          
          if "data" in response:
              documents = response["data"]
              count = len(documents)
              return f"Found {count} {doctype} documents:\n\n" + json.dumps(documents, indent=2)
          else:
              return json.dumps(response, indent=2)
              
      except Exception as error:
          return _format_error_response(error, "list_documents")

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

  Top-level registration call in the MCP server setup that invokes documents.register_tools(mcp), which defines and registers the list_documents tool among other document tools.

  documents.register_tools(mcp)

• src/tools/documents.py:81-81 (registration)

  The register_tools function in documents.py that defines all document-related MCP tools using @mcp.tool() decorators, including the list_documents handler. This function is called from src/server.py.

  def register_tools(mcp: Any) -> None:

• src/tools/documents.py:351-357 (schema)

  Input schema defined by function parameters with type hints: doctype (required str), optional filters/fields/limit/order_by (str), returns formatted str response. Detailed usage in docstring.

  async def list_documents(
      doctype: str,
      filters: Optional[str] = None,
      fields: Optional[str] = None,
      limit: Optional[str] = None,
      order_by: Optional[str] = None
  ) -> str:

• src/tools/documents.py:13-13 (helper)

  Imports format_filters_for_api helper from filter_parser.py, used at line 391 to parse custom filter strings into Frappe API filter JSON.

  from .filter_parser import format_filters_for_api, FILTER_SYNTAX_DOCS