Maguyva.ai Documentation
MCP API Reference

MCP API Reference

Maguyva.ai provides a comprehensive Model Context Protocol (MCP) API that enables intelligent code search, analysis, and workflow assistance. This reference guide covers all available API methods and their usage.

API Overview

The Maguyva.ai MCP API is organized into four main categories:

  • 🔍 Core Search Tools - Advanced search capabilities across your codebase
  • 📊 Code Analysis Tools - Deep code analysis and relationship mapping
  • 📈 Namespace Management - Organize and monitor your code repositories
  • 🔧 Utility Tools - AI-powered workflow assistance

Core Search Tools

1. code_search

Intelligent Composite Search - Automatically selects the best search strategy based on your query.

mcp__maguyva__code_search(
    query: str | List[float] | int,      # Search query (string/embedding/symbol_id)
    mode: str = "auto",                  # auto|semantic|fuzzy|hybrid|vector|text|graph
    namespace: str = "default",          # Target namespace
    limit: int = 10,                     # Results limit (1-100)
    threshold: float = 0.6,              # Similarity threshold (0.0-1.0)
    include_context: bool = True,        # Include context information
    search_mode: str = "auto",           # fast|balanced|deep|custom
    ef_search: int = None,               # Custom HNSW parameter
    rrf_k: int = 60                      # RRF fusion parameter
)

Parameters:

  • query - Your search input (text, embedding vector, or symbol ID)
  • mode - Search strategy:
    • auto - Automatically selects best mode
    • semantic - Meaning-based search
    • fuzzy - Approximate text matching
    • hybrid - Combines multiple strategies
    • vector - Pure embedding search
    • text - Exact text matching
    • graph - Symbol relationship traversal
  • namespace - Repository or project identifier
  • limit - Maximum number of results (1-100)
  • threshold - Minimum similarity score (0.0-1.0)
  • include_context - Add surrounding code context
  • search_mode - Performance vs accuracy trade-off
  • ef_search - Advanced HNSW tuning parameter
  • rrf_k - Reciprocal Rank Fusion parameter for hybrid search

Example Use Cases:

  • Finding all implementations of a specific function
  • Searching for code similar to a given example
  • Locating all references to a particular API

2. vector_search

Pure Semantic Search - Direct embedding-based similarity search for precise semantic matching.

mcp__maguyva__vector_search(
    query_embedding: bytes | List[int],  # Binary embedding vector
    namespace: str,                      # Namespace UUID
    ef_preset: str = "balanced",         # fast|balanced|deep
    limit: int = 20,                     # Results limit
    similarity_threshold: float = 0.7,   # Min similarity score
    include_metadata: bool = True        # Include result metadata
)

Parameters:

  • query_embedding - Pre-computed embedding vector
  • namespace - Target namespace UUID
  • ef_preset - Search accuracy preset:
    • fast - Quick results, lower accuracy
    • balanced - Good trade-off (default)
    • deep - Higher accuracy, slower
  • limit - Maximum results to return
  • similarity_threshold - Minimum cosine similarity (0.0-1.0)
  • include_metadata - Return additional file/symbol metadata

Example Use Cases:

  • Finding semantically similar code patterns
  • Identifying duplicate or near-duplicate implementations
  • Discovering related functionality across the codebase

3. text_search

Trigram Text Search - Fast text-based search with fuzzy matching capabilities.

mcp__maguyva__text_search(
    query: str,                          # Search text
    namespace: str,                      # Namespace UUID
    mode: str = "fuzzy",                 # fuzzy|exact|regex
    case_sensitive: bool = False,        # Case sensitivity
    language_filter: str = None,         # Filter by language
    limit: int = 15,                     # Results limit
    include_preview: bool = True         # Include content preview
)

Parameters:

  • query - Text to search for
  • namespace - Target namespace UUID
  • mode - Search matching mode:
    • fuzzy - Approximate matching (typo-tolerant)
    • exact - Exact string matching
    • regex - Regular expression search
  • case_sensitive - Enable case-sensitive matching
  • language_filter - Limit to specific programming language
  • limit - Maximum results
  • include_preview - Show code preview snippets

Example Use Cases:

  • Finding specific error messages or log statements
  • Searching for variable or function names
  • Locating comments or documentation strings

4. graph_search

Symbol Relationship Traversal - Navigate code relationships and dependencies.

mcp__maguyva__graph_search(
    start_symbol: int,                   # Starting symbol ID
    namespace: str,                      # Namespace UUID
    relationships: List[str] = ["CALLS", "IMPORTS", "REFERS"],
    direction: str = "out",              # out|in|both
    max_depth: int = 2,                  # Traversal depth (1-5)
    limit: int = 50                      # Max results
)

Parameters:

  • start_symbol - Symbol ID to start traversal from
  • namespace - Target namespace UUID
  • relationships - Types of relationships to follow:
    • CALLS - Function/method calls
    • IMPORTS - Import statements
    • REFERS - References and usages
    • EXTENDS - Inheritance relationships
    • IMPLEMENTS - Interface implementations
  • direction - Traversal direction:
    • out - From symbol to dependencies
    • in - From dependencies to symbol
    • both - Bidirectional traversal
  • max_depth - How many levels to traverse (1-5)
  • limit - Maximum results to return

Example Use Cases:

  • Finding all functions that call a specific method
  • Tracing dependency chains
  • Understanding impact of code changes

Code Analysis Tools

5. find_symbol_comprehensive

Enhanced Symbol Finding - Comprehensive symbol search with reference tracking.

mcp__maguyva__find_symbol_comprehensive(
    symbol_name: str,                    # Symbol to find
    symbol_kind: str = None,             # function|class|variable|method
    namespace: str,                      # Target namespace
    include_references: bool = True,     # Include usage references
    max_references: int = 50,            # Limit references
    include_definitions: bool = True     # Include definitions
)

Parameters:

  • symbol_name - Name of the symbol to find
  • symbol_kind - Type of symbol:
    • function - Standalone functions
    • class - Class definitions
    • variable - Variables and constants
    • method - Class methods
    • interface - Interface definitions
    • enum - Enumeration types
  • namespace - Target namespace
  • include_references - Find where symbol is used
  • max_references - Limit number of references
  • include_definitions - Include symbol definitions

Example Use Cases:

  • Finding all usages of a function or class
  • Refactoring symbol names
  • Understanding symbol scope and visibility

6. analyze_code_relationships

Dependency Analysis - Analyze relationships and dependencies in your code.

mcp__maguyva__analyze_code_relationships(
    target: str,                         # File path or symbol
    analysis_type: str = "dependencies", # dependencies|callers|imports|inheritance
    namespace: str,                      # Target namespace
    max_depth: int = 3,                  # Analysis depth
    include_external: bool = False,      # Include external deps
    include_tests: bool = True           # Include test files
)

Parameters:

  • target - File path or symbol name to analyze
  • analysis_type - Type of analysis:
    • dependencies - What this code depends on
    • callers - What calls this code
    • imports - Import relationships
    • inheritance - Class hierarchy
  • namespace - Target namespace
  • max_depth - How deep to analyze (1-5)
  • include_external - Include external library dependencies
  • include_tests - Include test file relationships

Example Use Cases:

  • Understanding code dependencies before refactoring
  • Identifying potential breaking changes
  • Mapping module relationships

7. get_code_context

Task-Oriented Context - Get relevant code context for specific tasks.

mcp__maguyva__get_code_context(
    task_description: str,               # What you're trying to do
    namespace: str,                      # Target namespace
    max_files: int = 20,                 # Max files to analyze
    include_dependencies: bool = True,   # Include related code
    context_type: str = "implementation",# implementation|debugging|testing
    include_examples: bool = True        # Include usage examples
)

Parameters:

  • task_description - Natural language description of your task
  • namespace - Target namespace
  • max_files - Maximum files to include
  • include_dependencies - Add dependent code
  • context_type - Type of context needed:
    • implementation - For writing new code
    • debugging - For fixing issues
    • testing - For writing tests
    • refactoring - For code improvements
  • include_examples - Include usage examples

Example Use Cases:

  • Getting all relevant code for implementing a feature
  • Understanding code context for debugging
  • Finding examples for writing tests

8. get_file_content

File Retrieval - Retrieve file contents with optional metadata.

mcp__maguyva__get_file_content(
    file_path: str,                      # File to retrieve
    namespace: str,                      # Target namespace
    include_metadata: bool = True,       # Include file metadata
    line_range: List[int] = None,        # [start, end] lines
    syntax_highlight: bool = False       # Apply syntax highlighting
)

Parameters:

  • file_path - Path to the file
  • namespace - Target namespace
  • include_metadata - Return file metadata (size, language, etc.)
  • line_range - Specific lines to retrieve [start, end]
  • syntax_highlight - Apply syntax highlighting to output

Example Use Cases:

  • Retrieving specific file contents
  • Getting code snippets from large files
  • Examining file metadata

Namespace Management Tools

9. list_available_namespaces

Namespace Discovery - List and filter available namespaces.

mcp__maguyva__list_available_namespaces(
    filter_pattern: str = None,          # Filter namespaces
    include_stats: bool = True,          # Include basic stats
    sort_by: str = "name",               # name|size|created_at|updated_at
    limit: int = 100,                    # Max results
    offset: int = 0                      # Pagination offset
)

Parameters:

  • filter_pattern - Regex pattern to filter namespaces
  • include_stats - Include statistics (file count, size, etc.)
  • sort_by - Sort order:
    • name - Alphabetical
    • size - By total size
    • created_at - Creation date
    • updated_at - Last modified
  • limit - Maximum results
  • offset - For pagination

Example Use Cases:

  • Discovering available repositories
  • Finding specific project namespaces
  • Monitoring namespace usage

10. get_namespace_stats

Namespace Statistics - Get detailed statistics for a namespace.

mcp__maguyva__get_namespace_stats(
    namespace: str,                      # Target namespace
    include_health: bool = True,         # Health metrics
    include_search_stats: bool = True,   # Search performance
    include_vector_stats: bool = True,   # Vector index stats
    include_growth_trends: bool = False  # Historical trends
)

Parameters:

  • namespace - Target namespace
  • include_health - System health metrics
  • include_search_stats - Search performance data
  • include_vector_stats - Vector index statistics
  • include_growth_trends - Historical growth data

Returns:

  • File and symbol counts
  • Index health status
  • Search performance metrics
  • Storage utilization
  • Growth trends (if requested)

Example Use Cases:

  • Monitoring namespace health
  • Optimizing search performance
  • Tracking codebase growth

Utility Tools

11. get_workflow_suggestions

AI Workflow Assistance - Get intelligent suggestions for your current task.

mcp__maguyva__get_workflow_suggestions(
    context: str,                        # Current task context
    current_files: List[str] = None,     # Files being worked on
    task_type: str = "development",      # development|debugging|testing|refactoring
    namespace: str,                      # Target namespace
    max_suggestions: int = 5,            # Max suggestions
    include_examples: bool = True        # Include code examples
)

Parameters:

  • context - Description of what you’re working on
  • current_files - Files currently open or being edited
  • task_type - Type of work:
    • development - Writing new features
    • debugging - Fixing bugs
    • testing - Writing tests
    • refactoring - Improving code
  • namespace - Target namespace
  • max_suggestions - Maximum suggestions to return
  • include_examples - Include code examples with suggestions

Returns:

  • Suggested next steps
  • Relevant files to examine
  • Code patterns to follow
  • Potential issues to watch for
  • Example implementations

Example Use Cases:

  • Getting guidance on implementing features
  • Finding relevant examples in the codebase
  • Understanding best practices for the project

Common Usage Patterns

Finding and Understanding Code 

# Find all implementations of a function
results = mcp__maguyva__find_symbol_comprehensive(
    symbol_name="processPayment",
    symbol_kind="function",
    namespace="your-namespace"
)

# Get context for understanding the code
context = mcp__maguyva__get_code_context(
    task_description="understand payment processing flow",
    namespace="your-namespace",
    context_type="debugging"
)

Analyzing Dependencies 

# Analyze what a module depends on
deps = mcp__maguyva__analyze_code_relationships(
    target="src/payments/processor.py",
    analysis_type="dependencies",
    namespace="your-namespace"
)

# Find what calls a specific function
callers = mcp__maguyva__analyze_code_relationships(
    target="processPayment",
    analysis_type="callers",
    namespace="your-namespace"
)

Intelligent Search 

# Semantic search for similar code
results = mcp__maguyva__code_search(
    query="validate user input and sanitize data",
    mode="semantic",
    namespace="your-namespace"
)

# Fast text search with fuzzy matching
results = mcp__maguyva__text_search(
    query="TODO",
    mode="fuzzy",
    namespace="your-namespace"
)

Best Practices

  1. Choose the Right Search Mode: Use auto mode for general searches, but specify a mode when you know exactly what you need.

  2. Optimize Performance: Use fast presets for interactive searches, deep for comprehensive analysis.

  3. Leverage Context: Always include context when available - it significantly improves result relevance.

  4. Use Namespaces: Properly organize your code into namespaces for better performance and organization.

  5. Combine Tools: Use multiple API methods together for comprehensive analysis (e.g., find symbol, then analyze relationships).

Rate Limits and Performance

  • Search operations: Optimized for sub-second response times
  • Analysis operations: May take 1-5 seconds depending on scope
  • File operations: Near-instant for individual files
  • Batch operations: Consider pagination for large result sets

Error Handling

All API methods return structured responses with:

  • success: Boolean indicating operation success
  • data: Result data when successful
  • error: Error message if operation failed
  • metadata: Additional information about the operation

Always check the success field before processing results.

Getting Started

To start using the MCP API:

  1. Connect to your Maguyva.ai instance
  2. Authenticate with your API credentials
  3. Select your target namespace
  4. Begin with simple searches and gradually explore advanced features

For detailed integration instructions, see the MCP installation guide.

Performance BenchmarksCompatibility & Technical Specifications