graphiti/.serena/memories/mcp_server_tools.md

MCP Server Tools Documentation

Overview

The Graphiti MCP Server exposes Graphiti functionality through the Model Context Protocol (MCP) for AI assistants (like those in LibreChat). Each tool is decorated with @mcp.tool() and provides a specific capability.

Tool Naming Convention

All tools follow MCP best practices:

• snake_case naming: All lowercase with underscores
• Action-oriented: Start with verbs (add, search, get, compare, delete)
• Concise descriptions: First line describes core action
• Clear parameters: Descriptions specify format and provide examples

Reference: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Recent Changes

2025-11-09 - Backward Compatibility Wrappers Added

Problem: External code review found tool surface mismatches between server and clients/tests:

• Tests expected search_memory_nodes but server only had search_nodes
• Tests called tools with singular group_id (string) but server expected group_ids (list)
• Tests used last_n parameter but server expected max_episodes

Solution: Added backward compatibility without breaking changes:

1. Created search_memory_nodes wrapper that delegates to search_nodes
2. Updated get_episodes to accept both group_id/group_ids and last_n/max_episodes
3. Updated clear_graph to accept both group_id (singular) and group_ids (plural)

Impact: All existing clients, tests, and documentation examples now work without modification.

2025-11-08 - UUID Parameter Documentation Enhanced

Problem: LLMs were attempting to generate and provide UUIDs when adding NEW memories, which should never happen - UUIDs must be auto-generated for new episodes.

Solution: Enhanced the uuid parameter documentation in add_memory to be very explicit: "NEVER provide a UUID for new episodes - UUIDs are auto-generated. This parameter can ONLY be used for updating an existing episode by providing its existing UUID."

Impact: Clear guidance for LLMs to prevent them from trying to generate UUIDs for new memories while preserving the ability to update existing episodes.

Tool List

Core Memory Management

1. add_memory - Add episodes to the knowledge graph ✨ IMPROVED DOCS
2. clear_graph - Clear all data for specified group IDs ✨ BACKWARD COMPATIBLE
3. get_status - Get server and database connection status

Search and Retrieval Tools

4. search_nodes - Search for nodes/entities using semantic search
5. search_memory_nodes - ⭐ NEW Alias for search_nodes (backward compatibility)
6. search_memory_facts - Search for facts/relationships using semantic search
7. get_entities_by_type - Retrieve entities by their type classification
8. compare_facts_over_time - Compare facts between two time periods

Entity and Episode Management

9. get_entity_edge - Retrieve a specific entity edge by UUID
10. delete_entity_edge - Delete an entity edge from the graph
11. get_episodes - Retrieve episodes from the graph ✨ BACKWARD COMPATIBLE
12. delete_episode - Delete an episode from the graph

Tool Details

search_memory_nodes (NEW - Backward Compatibility Wrapper)

Added: 2025-11-09 Purpose: Backward compatibility alias for search_nodes

MCP-Compliant Description: "Search for nodes in the graph memory (compatibility wrapper)."

Parameters:

• query: str - The search query
• group_id: Optional[str] - Single group ID (backward compatibility)
• group_ids: Optional[List[str]] - List of group IDs (preferred)
• max_nodes: int = 10 - Maximum number of nodes to return
• entity_types: Optional[List[str]] - Entity types to filter by

Implementation Notes:

• Converts singular group_id to [group_id] list if provided
• Delegates to search_nodes for actual implementation
• Maintains backward compatibility with existing clients

Location: After search_nodes in mcp_server/src/graphiti_mcp_server.py

get_episodes (Updated - Backward Compatible)

Updated: 2025-11-09 Purpose: Get episodes from the graph memory

Parameters (now accepts both old and new formats):

• group_id: Optional[str] - Single group ID (backward compatibility)
• group_ids: Optional[List[str]] - List of group IDs (preferred)
• last_n: Optional[int] - Max episodes to return (backward compatibility)
• max_episodes: int = 10 - Max episodes to return (preferred)

Backward Compatibility:

• Old: get_episodes(group_id="test", last_n=5) ✅ Works
• New: get_episodes(group_ids=["test"], max_episodes=5) ✅ Works
• Both parameters provided: group_ids and max_episodes take precedence

clear_graph (Updated - Backward Compatible)

Updated: 2025-11-09 Purpose: Clear all data from the graph for specified group IDs

Parameters (now accepts both old and new formats):

• group_id: Optional[str] - Single group ID (backward compatibility)
• group_ids: Optional[List[str]] - List of group IDs (preferred)

Backward Compatibility:

• Old: clear_graph(group_id="test") ✅ Works
• New: clear_graph(group_ids=["test1", "test2"]) ✅ Works
• Both provided: group_ids takes precedence

add_memory (Updated Documentation)

Purpose: Add episodes to the knowledge graph

MCP-Compliant Description: "Add an episode to memory. This is the primary way to add information to the graph."

Parameters:

• name: str - Name of the episode
• episode_body: str - Content to persist (JSON string for source='json')
• group_id: Optional[str] - Group ID for this graph (uses default if not provided)
• source: str = 'text' - Source type ('text', 'json', or 'message')
• source_description: str = '' - Optional description of the source
• uuid: Optional[str] = None - NEVER provide for NEW episodes. Can ONLY be used to update an existing episode by providing its UUID.

UUID Parameter Behavior:

• For NEW episodes: Do NOT provide - auto-generated
• For UPDATING episodes: Provide the existing episode's UUID to replace/update it
• Other uses: Idempotent operations or external system integration (advanced)

Implementation Notes:

• Returns immediately, processes in background
• Episodes for same group_id processed sequentially
• Providing a UUID updates the episode with that UUID if it exists

get_entities_by_type

Added: 2025-11-08 Purpose: Essential for PKM (Personal Knowledge Management) - enables browsing entities by their type classification

MCP-Compliant Description: "Retrieve entities by their type classification."

Parameters:

• entity_types: List[str] - Entity types to retrieve (e.g., ["Pattern", "Insight", "Preference"])
• group_ids: Optional[List[str]] - Filter by group IDs
• max_entities: int = 20 - Maximum entities to return
• query: Optional[str] - Optional search query to filter entities

Implementation Notes:

• Uses SearchFilters(node_labels=entity_types) from graphiti_core
• Uses NODE_HYBRID_SEARCH_RRF search config
• When query is provided: semantic search with type filter
• When query is empty: uses space (' ') as generic query to retrieve all of the type
• Returns NodeSearchResponse (same format as search_nodes)

Use Cases:

• "Show me all my Preferences"
• "List Patterns I've identified"
• "Get Insights about productivity"
• "Find all documented Procedures"

compare_facts_over_time

Added: 2025-11-08 Purpose: Track how knowledge/understanding evolved over time - critical for seeing how Patterns, Insights, and understanding changed

MCP-Compliant Description: "Compare facts between two time periods."

Parameters:

• query: str - Search query for facts to compare
• start_time: str - ISO 8601 timestamp (e.g., "2024-01-01" or "2024-01-01T10:30:00Z")
• end_time: str - ISO 8601 timestamp
• group_ids: Optional[List[str]] - Filter by group IDs
• max_facts_per_period: int = 10 - Max facts per time category

Returns: Dictionary with:

• facts_from_start: Facts valid at start_time
• facts_at_end: Facts valid at end_time
• facts_invalidated: Facts that were invalidated between start and end
• facts_added: Facts that became valid between start and end
• summary: Count statistics

Implementation Constraints

Safe Design Principles

All tools follow strict constraints to maintain upstream compatibility:

1. Only use public Graphiti APIs - No custom Cypher queries, no internal methods
2. MCP server only changes - No modifications to graphiti_core/
3. Existing patterns - Follow same structure as existing tools
4. Standard imports - Only use imports already in the file or from stable public APIs
5. MCP compliance - Follow MCP specification for tool naming and descriptions
6. LLM-friendly documentation - Clear guidance to prevent LLM confusion (e.g., UUID usage)
7. Backward compatibility - New parameters don't break existing clients

Dependencies

All required imports are either:

• Already present in the file (SearchFilters, format_fact_result)
• From stable public APIs (DateFilter, ComparisonOperator, search configs)

No new dependencies added to pyproject.toml.

Validation Tests

Automated Tests Passed (2025-11-09)

• ✅ Python syntax check (py_compile)
• ✅ Ruff formatting (auto-formatted)
• ✅ Ruff linting (all checks passed)
• ✅ No custom Cypher or internal APIs used
• ✅ Follows project code style conventions
• ✅ MCP specification compliance verified
• ✅ UUID documentation enhanced to prevent LLM misuse
• ✅ Backward compatibility maintained

Manual Testing Required

Before production use, test:

1. search_memory_nodes with both group_id and group_ids parameters
2. get_episodes with old format (group_id, last_n) and new format (group_ids, max_episodes)
3. clear_graph with both group_id and group_ids parameters
4. add_memory without LLM trying to provide UUIDs for NEW episodes
5. add_memory with UUID for UPDATING existing episodes
6. get_entities_by_type with various entity type combinations
7. compare_facts_over_time with various date ranges

File Location

mcp_server/src/graphiti_mcp_server.py

Current tool locations (after 2025-11-09 updates):

• add_memory: lines 320-403
• search_nodes: lines 406-483
• search_memory_nodes: After line 483 (new wrapper)
• get_entities_by_type: lines 486-583
• search_memory_facts: lines 587-640
• compare_facts_over_time: lines 641-829
• delete_entity_edge: lines 832-856
• delete_episode: lines 858-882
• get_entity_edge: lines 884-908
• get_episodes: lines 939-1004 (updated for backward compat)
• clear_graph: lines 1018-1050 (updated for backward compat)
• get_status: lines 1014-1089