nparashuram/meta-spatial-samples-mcp

#MetaSpatial SDK Code Samples MCP

A code search system that uses AST analysis, semantic relationships, and vector embeddings to help Claude find and understand code examples from the Meta Spatial SDK samples.

MCP Tools

• search_code_snippets - Find 10-15 line code examples
• smart_code_search - Intelligent search with pattern detection
• explore_ecs_system - Entity Component System exploration and usage patterns
• explore_panels - Panel entity creation, Android integration, and interactions
• explore_metaspatial_scenes - MetaSpatial scene files, materials, and entity hierarchies
• find_related_files - Cross-file relationship discovery
• get_codebase_overview - High-level structure analysis
• execute_prebuilt_query - MetaSpatial development task queries

Quick Start

1. Ingest the Code Samples

cd code
python run_full_ingestion.py /path/to/Meta-Spatial-SDK-Samples

This will:

• Parse all .kt, .java, .xml, .metaspatial, .scene, and build.gradle* files
• Extract AST relationships, Android patterns, and ECS components
• Generate semantic embeddings with relationship context
• Store everything in a vector database

2. Start the MCP Server

cd code
python start_mcp_server.py

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "code-search": {
      "command": "python",
      "args": [
        "/path/to/your/codegraph/code/start_mcp_server.py",
        "--db-path",
        "/path/to/your/codegraph/code/enhanced_chroma_db"
      ]
    }
  }
}

AI Generated Section

🏗️ System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude MCP    │────│  Query Interface │────│ Vector Database │
│     Client      │    │                  │    │   (ChromaDB)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                       ┌────────┴─────────┐
                       │                  │
            ┌──────────▼──────────┐  ┌────▼─────────────┐
            │ Semantic Search     │  │ Relationship     │
            │ Engine              │  │ Graph            │
            └─────────────────────┘  └──────────────────┘
                       │
            ┌──────────▼──────────┐
            │ AST Parser          │
            │ (Kotlin/Java/XML)   │
            └─────────────────────┘

📁 Project Structure

code/
├── ingestion/              # Code parsing & embedding
│   ├── code_parser.py      # Basic AST parsing
│   ├── enhanced_parser.py  # Advanced relationship extraction + ECS
│   ├── metaspatial_parser.py  # MetaSpatial/Scene file parser
│   ├── enhanced_embedder.py   # Context-aware embedding generation
│   └── ingest.py          # Main ingestion pipeline
├── storage/               # Vector database interface
│   └── vector_db.py       # ChromaDB wrapper with metadata
├── inference/             # Query & search logic
│   └── query_interface.py       # Enhanced search API with relationship analysis
├── mcp_server/            # MCP server implementation
│   └── code_search_server.py    # MCP protocol handler
├── run_full_ingestion.py  # Complete ingestion pipeline
└── start_mcp_server.py    # Launch MCP server

🧩 Key Components

AST Parser (ingestion/enhanced_parser.py)

• Extracts semantic relationships from code structure
• Tracks function calls, inheritance, method overrides
• Maps Android resource usage (R.id., R.layout.)
• Analyzes file hierarchy and module relationships
• ECS pattern detection for MetaSpatial entities, components, and systems

MetaSpatial Parser (ingestion/metaspatial_parser.py)

• Parses .metaspatial and .scene files (YAML-based entity definitions)
• Extracts ECS entity structures with components and properties
• Detects usage patterns for Panel entities, Physics, Draggable components
• Maps entity references between MetaSpatial files and Kotlin code

Enhanced Query Interface (inference/query_interface.py)

• Unified API for all search capabilities with relationship analysis
• ECS-aware search patterns for MetaSpatial development
• Smart pattern detection (draggable, panels, physics, etc.)
• Cross-file relationship traversal using ingested metadata
• MetaSpatial-specific queries for scene files and entity definitions
• Intelligent suggestions based on detected patterns and results

MCP Server (mcp_server/code_search_server.py)

• Protocol-compliant MCP server
• Tool definitions for Claude integration
• Async request handling
• Structured result formatting

🎯 Supported Query Types

1. Natural Language Queries

• "How to create a button click handler"
• "Activity lifecycle methods"
• "Network request examples"
• "Permission handling code"

2. Android Component Queries

• Find Activities and their layouts
• Explore Fragment implementations
• Discover resource definitions and usage
• Analyze manifest configurations

3. Relationship Queries

• Files in same folder/module
• Cross-file dependencies
• Resource definition → usage chains
• Import/export relationships

4. Pattern-Based Queries

• Lifecycle patterns (onCreate, onResume, etc.)
• UI interaction patterns (onClick, touch)
• Navigation patterns (intents, fragments)
• Data binding patterns
• Network/API patterns

5. ECS and MetaSpatial Queries

• Panel entity creation and usage patterns
• Component attachment and manipulation (Physics, Draggable, etc.)
• Entity-Component-System relationships
• Scene file entity definitions
• Cross-reference between MetaSpatial files and Kotlin implementations