feat(mcp): accept training-data-friendly parameter aliases

Models reach for common parameter names from training data (offset/limit
instead of page/page_size, find/old_text instead of find_text, etc.) on
first use of MCP tools. Pydantic validation errors fire, the model loses
trust in the tool, and falls back to filesystem reads — bypassing the
knowledge graph entirely.

Use Pydantic v2 AliasChoices on tool parameters so the canonical names
are still the only thing advertised in the JSON schema, but common
alternatives are silently accepted at validation time.

Aliases added across 12 tools:
  - pagination: page←offset/page_number, page_size←limit/per_page
  - search:     query←q/search/text, after_date←since/after/from_date,
                min_similarity←threshold/similarity_threshold,
                note_types←note_type/types
  - time:       timeframe←since/time_range/lookback
  - paths:      directory←folder/dir/path, dir_name←directory/folder/...,
                path←file_path/filepath/file
  - move:       destination_path←to/dest_path/new_path/destination
  - edit:       find_text←find/old_text/old_content/search,
                content←new_content/replacement/replace_with,
                section←section_heading/heading
  - flags:      overwrite←force/replace, is_directory←is_dir
  - context:    url←uri/memory_url, max_related←max_results

Closes #690

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/tools/build_context.py

@@ -1,10 +1,11 @@
 """Build context tool for Basic Memory MCP server."""
 
-from typing import Optional, Literal
+from typing import Annotated, Optional, Literal
 
 import logfire
 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import (
@@ -133,14 +134,35 @@ def _format_context_markdown(graph: GraphContext, project: str) -> str:
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def build_context(
-    url: MemoryUrl,
+    url: Annotated[
+        MemoryUrl,
+        Field(validation_alias=AliasChoices("url", "uri", "memory_url")),
+    ],
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     depth: str | int | None = 1,
-    timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(
+            default="7d",
+            validation_alias=AliasChoices("timeframe", "since", "time_range", "lookback"),
+        ),
+    ] = "7d",
+    page: Annotated[
+        int,
+        Field(default=1, validation_alias=AliasChoices("page", "offset", "page_number")),
+    ] = 1,
+    page_size: Annotated[
+        int,
+        Field(default=10, validation_alias=AliasChoices("page_size", "limit", "per_page")),
+    ] = 10,
+    max_related: Annotated[
+        int,
+        Field(
+            default=10,
+            validation_alias=AliasChoices("max_related", "max_results", "limit_related"),
+        ),
+    ] = 10,
     output_format: Literal["json", "text"] = "json",
     context: Context | None = None,
 ) -> dict | str:

src/basic_memory/mcp/tools/canvas.py

@@ -8,7 +8,7 @@
 
 from loguru import logger
 from fastmcp import Context
-from pydantic import BeforeValidator
+from pydantic import AliasChoices, BeforeValidator, Field
 
 from basic_memory.mcp.project_context import get_project_client
 from basic_memory.utils import coerce_list
@@ -24,7 +24,10 @@ async def canvas(
     nodes: Annotated[List[Dict[str, Any]], BeforeValidator(coerce_list)],
     edges: Annotated[List[Dict[str, Any]], BeforeValidator(coerce_list)],
     title: str,
-    directory: str,
+    directory: Annotated[
+        str,
+        Field(validation_alias=AliasChoices("directory", "folder", "dir", "path")),
+    ],
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     context: Context | None = None,

src/basic_memory/mcp/tools/delete_note.py

@@ -1,9 +1,10 @@
 from textwrap import dedent
-from typing import Optional, Literal
+from typing import Annotated, Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
 from mcp.server.fastmcp.exceptions import ToolError
+from pydantic import AliasChoices, Field
 
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import detect_project_from_url_prefix, get_project_client
@@ -153,7 +154,10 @@ def _format_delete_error_response(project: str, error_message: str, identifier:
 )
 async def delete_note(
     identifier: str,
-    is_directory: bool = False,
+    is_directory: Annotated[
+        bool,
+        Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
+    ] = False,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",

src/basic_memory/mcp/tools/edit_note.py

@@ -1,10 +1,11 @@
 """Edit note tool for Basic Memory MCP server."""
 
-from typing import Optional, Literal
+from typing import Annotated, Optional, Literal
 
 import logfire
 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import (
@@ -170,11 +171,37 @@ def _format_error_response(
 async def edit_note(
     identifier: str,
     operation: str,
-    content: str,
+    # Accept common replacement-content aliases. Models trained on diff/patch
+    # APIs reach for new_content/replacement/replace_with on first try.
+    content: Annotated[
+        str,
+        Field(
+            validation_alias=AliasChoices(
+                "content", "new_content", "replacement", "replace_with"
+            )
+        ),
+    ],
     project: Optional[str] = None,
     workspace: Optional[str] = None,
-    section: Optional[str] = None,
-    find_text: Optional[str] = None,
+    # Section/heading naming varies across tools; accept the descriptive forms.
+    section: Annotated[
+        Optional[str],
+        Field(
+            default=None,
+            validation_alias=AliasChoices("section", "section_heading", "heading"),
+        ),
+    ] = None,
+    # find_text is the highest-frequency miss per the issue: models reach for
+    # find/old_text/old_content/search before find_text every time.
+    find_text: Annotated[
+        Optional[str],
+        Field(
+            default=None,
+            validation_alias=AliasChoices(
+                "find_text", "find", "old_text", "old_content", "search"
+            ),
+        ),
+    ] = None,
     expected_replacements: Optional[int] = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,

src/basic_memory/mcp/tools/list_directory.py

@@ -1,9 +1,10 @@
 """List directory tool for Basic Memory MCP server."""
 
-from typing import Optional
+from typing import Annotated, Optional
 
 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 
 from basic_memory.mcp.project_context import get_project_client
 from basic_memory.mcp.server import mcp
@@ -14,9 +15,22 @@
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def list_directory(
-    dir_name: str = "/",
+    # `dir_name` is unusual; models reach for directory/folder/path/dir.
+    dir_name: Annotated[
+        str,
+        Field(
+            default="/",
+            validation_alias=AliasChoices("dir_name", "directory", "folder", "path", "dir"),
+        ),
+    ] = "/",
     depth: int = 1,
-    file_name_glob: Optional[str] = None,
+    file_name_glob: Annotated[
+        Optional[str],
+        Field(
+            default=None,
+            validation_alias=AliasChoices("file_name_glob", "glob", "pattern", "filter"),
+        ),
+    ] = None,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     context: Context | None = None,

src/basic_memory/mcp/tools/move_note.py

@@ -2,11 +2,12 @@
 
 from pathlib import Path, PureWindowsPath
 from textwrap import dedent
-from typing import Optional, Literal
+from typing import Annotated, Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
 from mcp.server.fastmcp.exceptions import ToolError
+from pydantic import AliasChoices, Field
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.project_context import get_project_client
@@ -348,9 +349,27 @@ def _format_move_error_response(error_message: str, identifier: str, destination
 )
 async def move_note(
     identifier: str,
-    destination_path: str = "",
-    destination_folder: Optional[str] = None,
-    is_directory: bool = False,
+    # Move/rename APIs across the ecosystem use `to`/`destination`/`new_path`.
+    destination_path: Annotated[
+        str,
+        Field(
+            default="",
+            validation_alias=AliasChoices(
+                "destination_path", "dest_path", "new_path", "to", "destination"
+            ),
+        ),
+    ] = "",
+    destination_folder: Annotated[
+        Optional[str],
+        Field(
+            default=None,
+            validation_alias=AliasChoices("destination_folder", "dest_folder", "to_folder"),
+        ),
+    ] = None,
+    is_directory: Annotated[
+        bool,
+        Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
+    ] = False,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",

src/basic_memory/mcp/tools/read_content.py

@@ -8,11 +8,12 @@
 import base64
 import io
 
-from typing import Optional
+from typing import Annotated, Optional
 
 from loguru import logger
 from PIL import Image as PILImage
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 from mcp.server.fastmcp.exceptions import ToolError
 
 from basic_memory.config import ConfigManager
@@ -158,7 +159,10 @@ def optimize_image(img, content_length, max_output_bytes=350000):
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def read_content(
-    path: str,
+    path: Annotated[
+        str,
+        Field(validation_alias=AliasChoices("path", "file_path", "filepath", "file")),
+    ],
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     context: Context | None = None,

src/basic_memory/mcp/tools/read_note.py

@@ -1,13 +1,14 @@
 """Read note tool for Basic Memory MCP server."""
 
 from textwrap import dedent
-from typing import Optional, Literal, cast
+from typing import Annotated, Optional, Literal, cast
 
 import logfire
 import yaml
 
 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import (
@@ -71,8 +72,17 @@ async def read_note(
     identifier: str,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
-    page: int = 1,
-    page_size: int = 10,
+    # Accept common pagination aliases models reach for from training data
+    # (offset/limit/page_number/per_page). Schema still advertises only the
+    # canonical names; aliases are silently mapped at validation time.
+    page: Annotated[
+        int,
+        Field(default=1, validation_alias=AliasChoices("page", "offset", "page_number")),
+    ] = 1,
+    page_size: Annotated[
+        int,
+        Field(default=10, validation_alias=AliasChoices("page_size", "limit", "per_page")),
+    ] = 10,
     output_format: Literal["text", "json"] = "text",
     include_frontmatter: bool = False,
     context: Context | None = None,

src/basic_memory/mcp/tools/recent_activity.py

@@ -2,10 +2,11 @@
 
 from datetime import timezone
 from pathlib import PurePosixPath
-from typing import List, Union, Optional, Literal
+from typing import Annotated, List, Union, Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field
 
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.project_context import (
@@ -38,11 +39,26 @@
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def recent_activity(
-    type: Union[str, List[str]] = "",
+    type: Annotated[
+        Union[str, List[str]],
+        Field(default="", validation_alias=AliasChoices("type", "types", "kind")),
+    ] = "",
     depth: int = 1,
-    timeframe: TimeFrame = "7d",
-    page: int = 1,
-    page_size: int = 10,
+    timeframe: Annotated[
+        TimeFrame,
+        Field(
+            default="7d",
+            validation_alias=AliasChoices("timeframe", "since", "time_range", "lookback"),
+        ),
+    ] = "7d",
+    page: Annotated[
+        int,
+        Field(default=1, validation_alias=AliasChoices("page", "offset", "page_number")),
+    ] = 1,
+    page_size: Annotated[
+        int,
+        Field(default=10, validation_alias=AliasChoices("page_size", "limit", "per_page")),
+    ] = 10,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",