[BUG] Bug Report (via AI Assistant): search_notes Tool Unusable Due to Conflicting Query Parameter Definition

[azuma520]

Bug Description
The search_notes tool within the Basic Memory MCP server has conflicting definitions for its query parameter between its API schema (used by clients like AI assistants) and its actual source code implementation. The API schema expects query as an object (McpBasicMemorySearchNotesQuery), while the source code expects query as a string (str). This conflict makes the tool unusable via the API, as calls fail regardless of whether the parameter is sent as an object or a string.
Steps To Reproduce
Steps to reproduce the behavior:
Interact with the Basic Memory MCP server via an API client that adheres to the provided tool schema (e.g., an AI assistant like Gemini/Claude connected via the API).
Attempt to call the mcp_basic_memory_search_notes tool (or its equivalent API endpoint /search/) with the query parameter formatted as an object according to the schema (e.g., query={"title": "Some Title"} or query={"text": "Some Text"}).
Observe an error related to parameter type mismatch (e.g., Error calling tool: Parameter 'query' must be of type undefined, got object). The exact error might vary depending on internal handling, but it fails.
Attempt to call the same tool with the query parameter formatted as a string, matching the source code signature (e.g., query="Some Title", potentially with search_type="title").
Observe a different parameter type mismatch error, indicating the call violates the API schema (e.g., Error calling tool: Parameter 'query' must be of type undefined, got string).
(Refer to the source code snippet below in Additional Context which confirms query: str)
Expected Behavior
The search_notes tool should be callable via its API according to a consistent definition. Either:
A) The API schema should accurately reflect the source code, defining query as a string (str), and calls with a string query should succeed.
B) The source code should be updated to accept the object type defined in the API schema (McpBasicMemorySearchNotesQuery), and calls with the object query should succeed.
Actual Behavior
Attempts to call the search_notes tool via the API consistently fail with parameter type errors due to the conflict between the API schema and the code implementation.
Sending query as an object results in errors like: Parameter 'query' must be of type undefined, got object.
Sending query as a string results in errors like: Parameter 'query' must be of type undefined, got string.
The tool is effectively unusable through the documented API schema.
Environment
OS: Windows 11 (win32 10.0.22631)
Python version: 3.12.7
Basic Memory version: 0.11.0
Installation method: uv
Interaction Method: Via AI Assistant API (Gemini Pro in Cursor) utilizing the provided MCP tool schema.
Additional Context
The API schema provided to the AI assistant defines the query parameter for mcp_basic_memory_search_notes as requiring an object of type McpBasicMemorySearchNotesQuery.
The relevant source code snippet provided by the user shows the function signature expects a string:
Apply
Possible Solution
Align the API schema definition (provided to clients like AI assistants) with the actual function signature in the source code. The most straightforward fix appears to be updating the API schema to define the query parameter as a string (str) and remove the requirement for the McpBasicMemorySearchNotesQuery object structure for this specific parameter in the API call definition. Alternatively, update the function code to correctly parse the McpBasicMemorySearchNotesQuery object passed via the API.

[phernandez]

claude: what do we need to change in the tool docs for search_notes?

[github-actions]

Claude Code Analysis

Based on my analysis, I've identified the issue and potential solutions:

Issue Analysis:

1. Parameter Type Mismatch:

   • The MCP tool function search_notes expects query as a string parameter: query: str
   • However, the API schema provided to AI assistants appears to define query as a complex object (McpBasicMemorySearchNotesQuery)

2. Missing Schema Definition:

   • Interestingly, I couldn't find any definition for McpBasicMemorySearchNotesQuery in the codebase
   • The actual search implementation uses a SearchQuery object internally, but expects a string from the MCP tool

3. Implementation Details:

   • In search.py, the tool takes a simple string query, then builds a SearchQuery object internally
   • The function then determines how to use that string based on the search_type parameter

Potential Solutions:

Solution 1: Update the MCP API Schema (Recommended)

The simplest fix would be to update the MCP API schema to reflect the actual implementation:

1. Files to Modify:

   • Any file defining the API schema for MCP tools (likely in MCP configurations or generated schema files)
   • Update the schema to define query as a string type, not an object type

2. Code Change:

   # Change from:
   "parameters": {
     "query": {
       "type": "object",
       "description": "...",
       "$ref": "#/components/schemas/McpBasicMemorySearchNotesQuery"
     },
     # other parameters...
   }
   
   # Change to:
   "parameters": {
     "query": {
       "type": "string",
       "description": "The search query string"
     },
     # other parameters...
   }

Solution 2: Update the Tool Implementation

Alternatively, update the search_notes tool to accept an object:

1. Files to Modify:

   • /home/runner/work/basic-memory/basic-memory/src/basic_memory/mcp/tools/search.py

2. Code Change:

   @mcp.tool(
       description="Search across all content in the knowledge base.",
   )
   async def search_notes(
       query: Union[str, SearchQuery],  # Accept either string or SearchQuery
       page: int = 1,
       page_size: int = 10,
       search_type: str = "text",
       types: Optional[List[str]] = None,
       entity_types: Optional[List[str]] = None,
       after_date: Optional[str] = None,
   ) -> SearchResponse:
       """Search across all content in the knowledge base."""
       # Create a SearchQuery object based on the parameters
       if isinstance(query, str):
           search_query = SearchQuery()
           
           # Set the appropriate search field based on search_type
           if search_type == "text":
               search_query.text = query
           elif search_type == "title":
               search_query.title = query
           # ... rest of existing implementation
       else:
           # If query is already a SearchQuery object, use it directly
           search_query = query
           
       # ... rest of implementation remains the same

Recommendation:

I recommend Solution 1 (updating the API schema) because:

1. It's less invasive - doesn't require changing the tool's implementation
2. It aligns with the current implementation's intent
3. It maintains a cleaner interface for AI assistants

The API schema should accurately reflect the implementation. Since the tool is designed to take a string and has existing documentation/examples using string queries, updating the schema to match this design is the most appropriate fix.

---

🤖 Generated with Claude Code GitHub Action

[phernandez]

claude-fix: can you make a PR to fix the search_notes tool docs?

[phernandez]

This was fixed in #78.

@azuma520 you can upgrade to the latest version by running

uv tool upgrade basic-memory