{"id":29118813,"url":"https://github.com/djfaizp/il2cpp-dump-analyzer","last_synced_at":"2025-06-29T13:05:05.244Z","repository":{"id":295232325,"uuid":"989485787","full_name":"djfaizp/il2cpp-dump-analyzer","owner":"djfaizp","description":"Agentic RAG system for analyzing IL2CPP dump.cs files from Unity games","archived":false,"fork":false,"pushed_at":"2025-05-28T19:14:34.000Z","size":27344,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T07:41:33.003Z","etag":null,"topics":["il2cpp","mcp","mcp-client","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djfaizp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-24T07:34:19.000Z","updated_at":"2025-05-28T19:14:37.000Z","dependencies_parsed_at":"2025-05-24T11:36:53.649Z","dependency_job_id":null,"html_url":"https://github.com/djfaizp/il2cpp-dump-analyzer","commit_stats":null,"previous_names":["djfaizp/il2cpp-dump-analyzer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/djfaizp/il2cpp-dump-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djfaizp%2Fil2cpp-dump-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djfaizp%2Fil2cpp-dump-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djfaizp%2Fil2cpp-dump-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djfaizp%2Fil2cpp-dump-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djfaizp","download_url":"https://codeload.github.com/djfaizp/il2cpp-dump-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djfaizp%2Fil2cpp-dump-analyzer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262598176,"owners_count":23334670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["il2cpp","mcp","mcp-client","mcp-server"],"created_at":"2025-06-29T13:05:04.358Z","updated_at":"2025-06-29T13:05:05.232Z","avatar_url":"https://github.com/djfaizp.png","language":"C#","readme":"# IL2CPP Dump Analyzer Agentic RAG MCP System\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue)](https://www.typescriptlang.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io/)\n[![Docker Support](https://img.shields.io/badge/Docker-Supported-blue)](https://www.docker.com/)\n\nA cutting-edge **Agentic Retrieval-Augmented Generation (RAG)** system for analyzing IL2CPP dump.cs files from Unity games. This system implements the Model Context Protocol (MCP) server specification with **intelligent agentic capabilities** that provide automated task orchestration, context-aware analysis, and enhanced workflow execution within the MCP framework.\n\n## 🚀 Key Features\n\n### 🤖 Agentic Intelligence Layer\n- **Intelligent MCP Tool Orchestration**: Automatically selects and chains MCP tools for complex analysis tasks\n- **Context-Aware Processing**: Preserves analysis context and results across multiple MCP tool calls\n- **Smart Task Decomposition**: Breaks complex IL2CPP analysis requests into manageable subtasks\n- **Result Synthesis**: Intelligently aggregates and correlates results from multiple MCP tools\n- **Adaptive Caching**: Implements smart caching strategies that learn from usage patterns\n- **Performance Optimization**: Monitors and optimizes agentic workflows for speed and efficiency\n\n### 🔍 Advanced IL2CPP Analysis\n- **Semantic Code Processing**: Specialized IL2CPPCodeChunker preserves code context and meaning\n- **Vector-Powered Search**: Uses Xenova's Transformers.js with all-MiniLM-L6-v2 model (384-dimensional embeddings)\n- **Supabase Vector Database**: High-performance vector search with pgvector extension\n- **Hash-based Change Detection**: Intelligent change detection to avoid reprocessing unchanged files\n- **Metadata Extraction**: Comprehensive assembly metadata, version tracking, and compilation analysis\n\n### 🛠️ Comprehensive Tool Suite (21 MCP Tools)\n- **Search Tools (3)**: Semantic code search, metadata search, and advanced querying\n- **Analysis Tools (15)**: MonoBehaviour discovery, class hierarchies, design patterns, dependencies, and asset analysis\n- **Generation Tools (3)**: C# wrapper generation, method stubs, and Unity MonoBehaviour templates\n\n### 🔌 MCP Integration Excellence\n- **Official MCP SDK**: Full compliance with Model Context Protocol specification v1.12.0\n- **Multiple Transports**: Stdio, HTTP, and Server-Sent Events (SSE) support\n- **Robust Validation**: Zod schemas ensure comprehensive parameter validation\n- **Advanced Error Handling**: Intelligent error recovery with detailed logging and retry mechanisms\n- **Resource Management**: Efficient memory usage and connection pooling\n\n## Prerequisites\n\n- **Node.js 18.x or higher**\n- **TypeScript** (for development)\n- **Supabase account** (required for vector database storage)\n- **IL2CPP dump.cs file** from a Unity game\n\n## Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/yourusername/il2cpp-dump-analyzer-mcp.git\n   cd il2cpp-dump-analyzer-mcp\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Set up Supabase database:**\n   - Create a new Supabase project at [supabase.com](https://supabase.com)\n   - Run the SQL commands in `supabase-setup.sql` in the Supabase SQL editor\n   - This creates the required tables with pgvector extension for vector storage\n\n4. **Configure environment variables:**\n   ```bash\n   cp simple.env .env\n   ```\n\n   Update the `.env` file with your configuration:\n   ```env\n   # Core Configuration\n   NODE_ENV=production\n   DUMP_FILE_PATH=./dump.cs\n   EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2\n   LOG_LEVEL=info\n\n   # Supabase Configuration (Required)\n   SUPABASE_URL=your_supabase_project_url\n   SUPABASE_KEY=your_supabase_anon_key\n   SUPABASE_TABLE_NAME=il2cpp_documents\n\n   # MCP Server Configuration\n   MCP_SERVER_PORT=3000\n   MCP_SERVER_HOST=0.0.0.0\n   ```\n\n5. **Build the project:**\n   ```bash\n   npm run build\n   ```\n\n## Usage\n### Environment Variables\n\nAll available environment variables including agentic configuration:\n\n```env\n# Core Configuration\nNODE_ENV=production|development|test\nDUMP_FILE_PATH=./dump.cs\nEMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2\nLOG_LEVEL=error|warn|info|debug\n\n# Supabase Configuration\nSUPABASE_URL=your_supabase_project_url\nSUPABASE_KEY=your_supabase_anon_or_service_key\nSUPABASE_TABLE_NAME=il2cpp_documents\n\n# MCP Server Configuration\nMCP_SERVER_PORT=3000\nMCP_SERVER_HOST=0.0.0.0\n\n# Agentic Configuration\nAGENTIC_MODE=true                    # Enable intelligent tool orchestration\nCONTEXT_CACHE_SIZE=1000             # Maximum cached contexts\nTOOL_CHAIN_MAX_DEPTH=5              # Maximum tool chaining depth\nINTELLIGENT_CACHING=true            # Enable smart result caching\nCONTEXT_PERSISTENCE=true            # Enable context persistence across calls\nPERFORMANCE_OPTIMIZATION=true      # Enable performance learning and optimization\nADAPTIVE_BATCHING=true              # Enable adaptive request batching\n```\n\n### Quick Start\n\n1. **Place your IL2CPP dump.cs file** in the root directory (or specify path in `.env`)\n\n2. **Start the MCP server:**\n   ```bash\n   npm start\n   ```\n\n3. **The server will automatically:**\n   - Parse the IL2CPP dump.cs file\n   - Extract classes, methods, enums, and interfaces\n   - Generate semantic embeddings using Xenova Transformers.js\n   - Store vectors in Supabase with hash-based change detection\n   - Start the MCP server with stdio transport\n\n4. **Connect with MCP clients:**\n   - **Claude Desktop**: Add to MCP configuration\n   - **Other MCP clients**: Use stdio transport connection\n\n### MCP Client Configuration\n\n#### Claude Desktop Configuration\n\nAdd to your Claude Desktop MCP configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"il2cpp-analyzer\": {\n      \"command\": \"node\",\n      \"args\": [\"./bin/il2cpp-mcp-stdio.js\"],\n      \"cwd\": \"/path/to/il2cpp-dump-analyzer-mcp\"\n    }\n  }\n}\n```\n\n#### Alternative: Direct Node.js Execution\n\n```bash\n# Run the MCP server directly\nnode ./bin/il2cpp-mcp-stdio.js\n\n# Or use npm script\nnpm run mcp:stdio\n```\n\n## 🛠️ MCP Tools and Resources\n\nThe server provides **21 comprehensive MCP tools** organized into three categories for IL2CPP analysis and code generation:\n\n### 🔍 Search Tools (3 tools)\n\n#### 1. `search_code` - Semantic Code Search\nAdvanced semantic search through IL2CPP code with intelligent filtering.\n\n**Parameters:**\n- `query` (string, required): The search query\n- `filter_type` (string, optional): Filter by entity type (`class`, `method`, `enum`, `interface`)\n- `filter_namespace` (string, optional): Filter by namespace\n- `filter_monobehaviour` (boolean, optional): Filter to only MonoBehaviour classes\n- `top_k` (number, optional, default: 5): Number of results to return\n\n**Example:**\n```typescript\n// Find all Player-related classes with semantic search\nsearch_code({ query: \"Player movement controller\", filter_type: \"class\", top_k: 10 })\n```\n\n#### 2. `search_metadata` - Metadata Search\nSearch through extracted metadata with flexible filtering and advanced options.\n\n**Parameters:**\n- `query` (string, required): Search query\n- `search_type` (string, optional): Type of search (`assembly`, `type`, `method`, `field`)\n- `assembly_name` (string, optional): Filter by assembly name\n- `unity_version` (string, optional): Filter by Unity version\n- `use_regex` (boolean, optional): Enable regex pattern matching\n- `max_results` (number, optional): Maximum results to return\n\n#### 3. `query_metadata` - Advanced Metadata Querying\nComplex metadata queries with aggregations and cross-references.\n\n**Parameters:**\n- `filters` (object, optional): Complex filtering criteria\n- `aggregations` (array, optional): Aggregation operations (`count`, `group_by`, `statistics`)\n- `cross_reference` (object, optional): Cross-reference analysis configuration\n\n### 🔬 Analysis Tools (15 tools)\n\n#### 4. `find_monobehaviours` - Unity Component Discovery\nFind and analyze MonoBehaviour classes for Unity component analysis.\n\n**Parameters:**\n- `query` (string, optional): Optional search query to filter MonoBehaviours\n- `top_k` (number, optional, default: 10): Number of results to return\n\n#### 5. `find_class_hierarchy` - Class Inheritance Analysis\nAnalyze class inheritance relationships and structure with detailed metadata.\n\n**Parameters:**\n- `class_name` (string, required): The name of the class to analyze\n- `include_methods` (boolean, optional, default: true): Include methods in the output\n\n#### 6. `find_enum_values` - Enum Definition Extraction\nExtract enum definitions and their values with type information.\n\n**Parameters:**\n- `enum_name` (string, required): The name of the enum to find values for\n\n#### 7. `analyze_dependencies` - Dependency Mapping\nComprehensive dependency analysis with circular dependency detection.\n\n**Parameters:**\n- `class_name` (string, required): Target class to analyze dependencies for\n- `analysis_type` (enum, optional): Type of analysis (`incoming`, `outgoing`, `bidirectional`, `circular`)\n- `depth` (number, optional, default: 3): How deep to traverse dependency chains (1-5)\n- `include_system_types` (boolean, optional): Include Unity/System dependencies\n\n#### 8. `find_cross_references` - Cross-Reference Analysis\nFind all references to specific code entities across the codebase.\n\n**Parameters:**\n- `target_name` (string, required): Name of the target entity\n- `target_type` (enum, required): Type of entity (`class`, `method`, `field`, `property`, `event`)\n- `reference_type` (enum, optional): Type of references (`usage`, `inheritance`, `implementation`)\n- `max_results` (number, optional): Maximum number of references to return\n\n#### 9. `find_design_patterns` - Design Pattern Detection\nDetect common design patterns with confidence scoring and examples.\n\n**Parameters:**\n- `pattern_types` (array, required): Array of patterns to detect (`singleton`, `observer`, `factory`, `strategy`, etc.)\n- `confidence_threshold` (number, optional): Minimum confidence level (0.1-1.0)\n- `include_partial_matches` (boolean, optional): Include partial pattern implementations\n\n#### 10. `extract_metadata` - Assembly Metadata Extraction\nExtract comprehensive assembly metadata, version information, and compilation flags.\n\n**Parameters:**\n- `content` (string, optional): IL2CPP dump content\n- `file_path` (string, optional): Path to IL2CPP dump file\n- `include_generic_instantiations` (boolean, optional): Include generic type instantiations\n- `validate_structure` (boolean, optional): Validate extracted metadata structure\n\n#### 11. `analyze_type_hierarchies` - Type System Analysis\nAnalyze complex type hierarchies including generics and constraints.\n\n**Parameters:**\n- `type_name` (string, required): Target type to analyze\n- `include_constraints` (boolean, optional): Include generic constraints\n- `max_depth` (number, optional): Maximum hierarchy depth to analyze\n\n#### 12. `analyze_generic_types` - Generic Type Analysis\nSpecialized analysis of generic types and their instantiations.\n\n**Parameters:**\n- `type_name` (string, required): Generic type to analyze\n- `include_instantiations` (boolean, optional): Include all instantiations\n- `constraint_analysis` (boolean, optional): Analyze type constraints\n\n#### 13. `analyze_type_dependencies` - Type Dependency Analysis\nAnalyze dependencies between types with detailed relationship mapping.\n\n**Parameters:**\n- `type_name` (string, required): Target type for dependency analysis\n- `dependency_type` (enum, optional): Type of dependencies to analyze\n- `include_indirect` (boolean, optional): Include indirect dependencies\n\n#### 14. `analyze_type_compatibility` - Type Compatibility Analysis\nAnalyze type compatibility and conversion possibilities.\n\n**Parameters:**\n- `source_type` (string, required): Source type name\n- `target_type` (string, required): Target type name\n- `include_implicit_conversions` (boolean, optional): Include implicit conversions\n\n#### 15. `track_assembly_metadata` - Assembly Version Tracking\nTrack assembly metadata changes and version comparisons.\n\n**Parameters:**\n- `tracking_id` (string, required): Unique tracking identifier\n- `comparison_mode` (enum, optional): Comparison mode (`full`, `incremental`, `diff`)\n- `include_dependencies` (boolean, optional): Include dependency tracking\n\n#### 16. `analyze_asset_references` - Asset Reference Analysis\nAnalyze asset references and dependencies within IL2CPP code.\n\n**Parameters:**\n- `asset_type` (string, optional): Type of assets to analyze\n- `include_missing_references` (boolean, optional): Include missing asset references\n- `reference_depth` (number, optional): Depth of reference analysis\n\n#### 17. `find_unused_assets` - Unused Asset Detection\nFind potentially unused assets based on IL2CPP code analysis.\n\n**Parameters:**\n- `asset_types` (array, optional): Types of assets to check for usage\n- `exclude_patterns` (array, optional): Patterns to exclude from analysis\n- `confidence_threshold` (number, optional): Confidence threshold for unused detection\n\n#### 18. `analyze_asset_dependencies` - Asset Dependency Analysis\nComprehensive analysis of asset dependencies and circular references.\n\n**Parameters:**\n- `include_circular_dependencies` (boolean, optional): Include circular dependency detection\n- `asset_type_filter` (array, optional): Filter by specific asset types\n- `dependency_depth` (number, optional): Maximum dependency depth to analyze\n\n### ⚙️ Generation Tools (3 tools)\n\n#### 19. `generate_class_wrapper` - C# Class Wrapper Generation\nGenerate C# wrapper classes from IL2CPP class definitions with full type fidelity.\n\n**Parameters:**\n- `class_name` (string, required): Name of the IL2CPP class to generate wrapper for\n- `include_methods` (boolean, optional): Include method implementations\n- `include_properties` (boolean, optional): Include property implementations\n- `generate_interfaces` (boolean, optional): Generate interface definitions\n- `custom_namespace` (string, optional): Custom namespace for generated code\n- `unity_version` (string, optional): Target Unity version\n\n**Example:**\n```typescript\n// Generate comprehensive wrapper for Player class\ngenerate_class_wrapper({\n  class_name: \"Player\",\n  include_methods: true,\n  generate_interfaces: true,\n  custom_namespace: \"Game.Wrappers\"\n})\n```\n\n#### 20. `generate_method_stubs` - Method Stub Generation\nGenerate method stubs and interfaces from IL2CPP class definitions.\n\n**Parameters:**\n- `class_name` (string, required): Name of the IL2CPP class to generate method stubs for\n- `method_filter` (string, optional): Regex pattern to match specific methods\n- `include_documentation` (boolean, optional): Include XML documentation comments\n- `include_error_handling` (boolean, optional): Include error handling and validation\n- `generate_async` (boolean, optional): Generate async/await patterns where applicable\n\n#### 21. `generate_monobehaviour_template` - Unity MonoBehaviour Template Generation\nGenerate Unity-ready MonoBehaviour scripts with common patterns and lifecycle methods.\n\n**Parameters:**\n- `class_name` (string, required): Name of the IL2CPP MonoBehaviour class\n- `template_type` (string, optional): Template type (`basic`, `ui`, `gameplay`, `system`)\n- `include_lifecycle_methods` (boolean, optional): Include Unity lifecycle methods\n- `include_unity_events` (boolean, optional): Include UnityEvent implementations\n- `include_serialized_fields` (boolean, optional): Include SerializeField attributes\n\n## 🤖 Agentic Workflows and Usage Examples\n\n### Intelligent Tool Orchestration\n\nThe agentic layer automatically chains tools for complex analysis tasks:\n\n```typescript\n// Example: Comprehensive Player class analysis\n// The system automatically orchestrates multiple tools:\n\n1. search_code({ query: \"Player\", filter_type: \"class\" })\n2. find_class_hierarchy({ class_name: \"Player\" })\n3. analyze_dependencies({ class_name: \"Player\", analysis_type: \"bidirectional\" })\n4. find_design_patterns({ pattern_types: [\"singleton\", \"observer\"] })\n5. generate_class_wrapper({ class_name: \"Player\", include_methods: true })\n\n// All executed intelligently with context preservation\n```\n\n### Context-Aware Analysis\n\n```typescript\n// Example: MonoBehaviour ecosystem analysis\n// The agent maintains context across tool calls:\n\n1. find_monobehaviours({ query: \"Enemy\" })\n   // Context: Found EnemyController, EnemyAI, EnemyHealth\n\n2. analyze_dependencies({ class_name: \"EnemyController\" })\n   // Context: Uses previous results to analyze dependencies\n\n3. find_cross_references({ target_name: \"EnemyController\", target_type: \"class\" })\n   // Context: Correlates with dependency analysis\n\n4. generate_monobehaviour_template({ class_name: \"EnemyController\" })\n   // Context: Uses all previous analysis for optimal template generation\n```\n\n### Smart Caching and Performance\n\nThe agentic system implements intelligent caching:\n- **Result Caching**: Frequently accessed analysis results are cached\n- **Context Persistence**: Analysis context is preserved across sessions\n- **Performance Learning**: The system learns from usage patterns to optimize future requests\n- **Adaptive Batching**: Related tool calls are automatically batched for efficiency\n\n### Resources\n\nThe server exposes resources through the MCP resource system:\n\n- `il2cpp://{query}`: Retrieves code snippets matching the query with intelligent ranking\n  - Query parameters:\n    - `top_k`: Number of results to return (default: 5)\n    - `filter_type`: Filter by entity type (class, method, enum, interface)\n    - `filter_namespace`: Filter by namespace\n    - `filter_monobehaviour`: Filter to only include MonoBehaviour classes\n    - `context_aware`: Enable context-aware result ranking (default: true)\n\n## Development\n\n### Development Mode\n\n1. **Run in development mode:**\n   ```bash\n   npm run dev\n   ```\n\n2. **Run tests:**\n   ```bash\n   npm test\n   npm run test:watch    # Watch mode\n   npm run test:coverage # With coverage\n   ```\n\n3. **Lint and format code:**\n   ```bash\n   npm run lint\n   npm run format\n   ```\n\n4. **Build for production:**\n   ```bash\n   npm run build\n   ```\n\n### Testing\n\nThe project includes comprehensive Jest testing infrastructure with agentic component coverage:\n\n- **Unit Tests**: All MCP tools, agentic components, and core functionality\n- **Integration Tests**: Vector store operations, Supabase integration, and tool orchestration\n- **Performance Tests**: Large file processing, embedding generation, and agentic workflow optimization\n- **Agentic Tests**: Context management, tool selection, and intelligent orchestration\n- **Error Handling Tests**: Edge cases, error scenarios, and recovery mechanisms\n\nRun specific test suites:\n```bash\nnpm run test:unit        # Unit tests only\nnpm run test:integration # Integration tests only\nnpm run test:performance # Performance tests only\nnpm run test:mcp-tools   # MCP tool-specific tests\nnpm run test             # Full test suite including agentic components\n```\n\n### Agentic Component Testing\n\n```bash\n# Test agentic orchestration\nnpm run test -- --testPathPattern=agent\n\n# Test intelligent tool selection\nnpm run test -- --testPathPattern=mcp-tool-selector\n\n# Test context management\nnpm run test -- --testPathPattern=mcp-context-manager\n```\n\n\n## Project Structure\n\n```\nsrc/\n├── __tests__/              # Test files and test utilities\n│   ├── setup.ts           # Jest test setup\n│   ├── test-data.ts       # Mock IL2CPP data for testing\n│   ├── agent/             # Agentic component tests\n│   ├── integration/       # Integration tests\n│   ├── mcp/               # MCP tool tests\n│   └── *.test.ts          # Individual test files\n├── agent/                 # Agentic Intelligence Layer\n│   ├── mcp-orchestrator.ts # Intelligent tool orchestration\n│   ├── mcp-context-manager.ts # Context management and persistence\n│   ├── mcp-performance-optimizer.ts # Performance optimization\n│   ├── mcp-response-synthesizer.ts # Multi-tool result synthesis\n│   ├── mcp-tool-selector.ts # AI-driven tool selection\n│   ├── types.ts           # Agentic type definitions\n│   └── index.ts           # Agent exports\n├── config/                 # Configuration utilities\n├── database/              # Database connection and management\n│   ├── connection-manager.ts # Database connection pooling\n│   ├── enhanced-vector-store.ts # Enhanced vector operations\n│   └── performance-monitor.ts # Database performance monitoring\n├── embeddings/            # Embedding generation and vector storage\n│   ├── chunker.ts         # IL2CPP-specific code chunking\n│   ├── xenova-embeddings.ts # Xenova Transformers.js integration\n│   ├── supabase-vector-store.ts # Supabase vector store implementation\n│   └── vector-store.ts    # Main vector store interface\n├── generator/             # Code generation infrastructure\n│   ├── types.ts           # TypeScript interfaces for code generation\n│   ├── base-generator.ts  # Abstract base class for generators\n│   ├── template-engine.ts # Template engine integration\n│   ├── class-wrapper-generator.ts # C# class wrapper generator\n│   ├── method-stub-generator.ts # Method stub generator\n│   ├── monobehaviour-generator.ts # Unity MonoBehaviour template generator\n│   └── index.ts           # Generator exports\n├── indexer/               # File indexing and processing\n│   └── indexer.ts         # Main indexing logic with hash management\n├── mcp/                   # MCP server implementation\n│   ├── mcp-sdk-server.ts  # Main MCP server with all tools\n│   ├── stdio-server.ts    # Stdio transport server\n│   ├── tools/             # MCP tool implementations (21 tools)\n│   │   ├── search-code-tool.ts # Semantic code search\n│   │   ├── find-monobehaviours-tool.ts # MonoBehaviour discovery\n│   │   ├── analyze-dependencies-tool.ts # Dependency analysis\n│   │   ├── generate-class-wrapper-tool.ts # Code generation\n│   │   ├── tool-registry.ts # Tool registration and metadata\n│   │   └── ... (18 more tools)\n│   └── types.ts           # MCP type definitions\n├── metadata/              # Metadata analysis and extraction\n│   └── type-analyzer.ts   # Advanced type analysis\n├── monitoring/            # System monitoring and health\n│   ├── health-service.ts  # Health monitoring\n│   ├── metrics-service.ts # Performance metrics\n│   └── lifecycle-manager.ts # Component lifecycle management\n├── parser/                # IL2CPP dump file parsing\n│   ├── il2cpp-parser.ts   # Main parser implementation\n│   ├── enhanced-il2cpp-parser.ts # Enhanced parser with metadata\n│   ├── advanced-parser.ts # Advanced parsing capabilities\n│   └── index.ts           # Parser exports\n├── performance/           # Performance optimization\n│   ├── chunked-processor.ts # Chunked processing for large files\n│   ├── batch-vector-store.ts # Batch vector operations\n│   └── streaming-parser.ts # Streaming parser for memory efficiency\n├── transport/             # Transport layer implementations\n│   ├── http-transport.ts  # HTTP transport\n│   ├── transport-factory.ts # Transport factory\n│   └── index.ts           # Transport exports\n└── utils/                 # Utility functions\n    ├── hash-manager.ts    # File hash management\n    ├── supabase-hash-manager.ts # Supabase-based hash storage\n    ├── mcp-response-formatter.ts # Response formatting\n    └── parameter-validator.ts # Parameter validation\n\nbin/\n└── il2cpp-mcp-stdio.js    # Executable MCP server binary\n\nexamples/                   # Code generation examples and documentation\n├── README.md              # Examples overview\n├── class-wrapper-example.md # Class wrapper generation examples\n├── method-stubs-example.md # Method stub generation examples\n└── monobehaviour-template-example.md # MonoBehaviour template examples\n\nsupabase-setup.sql          # Supabase database schema\n```\n\n## 🏗️ Architecture\n\n### Foundation Layer\n1. **Enhanced IL2CPP Parser**: Advanced parsing with metadata extraction and type analysis\n2. **Semantic Code Chunker**: Context-preserving chunking with IL2CPP-specific optimizations\n3. **Xenova Embeddings Engine**: 384-dimensional embeddings using Transformers.js all-MiniLM-L6-v2\n4. **Supabase Vector Store**: High-performance vector search with pgvector extension\n5. **Hash-based Change Detection**: Intelligent file change tracking and incremental processing\n\n### Agentic Intelligence Layer\n6. **MCP Tool Orchestrator**: Intelligent tool selection and workflow automation\n7. **Context Manager**: Persistent context across tool calls with smart compression\n8. **Performance Optimizer**: Real-time performance monitoring and optimization\n9. **Response Synthesizer**: Multi-tool result aggregation and correlation\n10. **Tool Selector**: AI-driven tool selection based on task requirements\n\n### MCP Server Layer\n11. **MCP SDK Server**: Official MCP TypeScript SDK implementation with 21 specialized tools\n12. **Transport Layer**: Multi-transport support (stdio, HTTP, SSE) with connection pooling\n13. **Validation Engine**: Comprehensive Zod schema validation with error recovery\n14. **Resource Manager**: Efficient memory management and connection handling\n\n### Data Flow with Agentic Enhancement\n\n1. **Input Processing**: IL2CPP dump.cs file with intelligent preprocessing\n2. **Agentic Analysis**: Smart task decomposition and tool selection\n3. **Parallel Processing**: Concurrent parsing, chunking, and embedding generation\n4. **Vector Storage**: Optimized storage in Supabase with intelligent indexing\n5. **Context-Aware Retrieval**: Smart caching and context-aware search\n6. **Multi-Tool Orchestration**: Automated tool chaining for complex analysis\n7. **Result Synthesis**: Intelligent aggregation and correlation of results\n8. **Adaptive Learning**: Performance optimization based on usage patterns\n\n## MCP SDK Integration\n\nThis project uses the official Model Context Protocol TypeScript SDK (`@modelcontextprotocol/sdk`) for full MCP compliance:\n\n### Key Features\n- **Standardized Protocol**: Full MCP specification compliance\n- **Resource Templates**: Expose IL2CPP data through MCP resources\n- **Tool Definitions**: Comprehensive parameter validation using Zod schemas\n- **Stdio Transport**: Optimized for desktop applications and command-line tools\n- **Error Handling**: Robust error management with detailed logging\n- **Session Management**: Stateful interactions with MCP clients\n\n### Transport Configuration\nThe server uses **stdio transport only** for optimal compatibility with:\n- Claude Desktop\n- Command-line MCP clients\n- Desktop applications\n- Development tools\n\n## Performance Considerations\n\n- **Incremental Processing**: Hash-based change detection avoids reprocessing\n- **Efficient Chunking**: Semantic-aware chunking preserves code meaning\n- **Vector Optimization**: 384-dimensional embeddings balance quality and performance\n- **Database Indexing**: Optimized Supabase queries with proper indexing\n- **Memory Management**: Streaming processing for large dump files\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Supabase Connection Errors**\n   - Verify `SUPABASE_URL` and `SUPABASE_KEY` in `.env`\n   - Ensure pgvector extension is enabled\n   - Check network connectivity\n\n2. **Embedding Generation Slow**\n   - First run downloads the model (~90MB)\n   - Subsequent runs use cached model\n   - Consider using faster hardware for large files\n\n3. **MCP Client Connection Issues**\n   - Verify stdio transport configuration\n   - Check file permissions on `bin/il2cpp-mcp-stdio.js`\n   - Ensure Node.js is in PATH\n\n4. **Memory Issues with Large Files**\n   - Increase Node.js memory limit: `node --max-old-space-size=4096`\n   - Consider chunking very large dump files\n\n5. **Code Generation Issues**\n   - **Class Not Found**: Ensure the class exists in the IL2CPP dump and is properly indexed\n   - **Invalid Generated Code**: Check Unity version compatibility and namespace conflicts\n   - **Missing Dependencies**: Verify all required using statements are included\n   - **Type Resolution Errors**: Ensure IL2CPP dump contains complete type information\n\n6. **MonoBehaviour Generation Issues**\n   - **Not a MonoBehaviour**: Verify the target class inherits from MonoBehaviour\n   - **Missing Unity Methods**: Check Unity version compatibility for lifecycle methods\n   - **Serialization Issues**: Ensure fields are properly marked as serializable\n\n## 🐳 Docker Support\n\nThe IL2CPP Dump Analyzer MCP system includes comprehensive Docker support for easy deployment and development.\n\n### Quick Start with Docker\n\n1. **Setup Environment**:\n   ```bash\n   # Linux/macOS\n   ./docker-setup.sh\n\n   # Windows PowerShell\n   .\\docker-setup.ps1\n   ```\n\n2. **Start Production Environment**:\n   ```bash\n   docker-compose --env-file .env.docker up -d\n   ```\n\n3. **Start Development Environment**:\n   ```bash\n   docker-compose -f docker-compose.dev.yml --env-file .env.docker.dev up -d\n   ```\n\n### Docker Architecture\n\nThe system uses a multi-container architecture:\n- **IL2CPP MCP Server**: Main application container with Xenova embeddings\n- **Supabase Database**: PostgreSQL with pgvector extension\n- **Supabase REST API**: PostgREST API gateway\n- **Kong Gateway**: API gateway and routing (production)\n- **Supabase Studio**: Database management UI (development)\n\n### Recent Docker Improvements\n\n✅ **Fixed Xenova Model Loading**: Proper path resolution and timeout handling\n✅ **Enhanced Memory Management**: Increased limits for model loading (4GB)\n✅ **Improved Startup Times**: Extended health check periods (5 minutes)\n✅ **Better Error Handling**: Retry logic and graceful failure recovery\n✅ **Volume Optimization**: Named volumes for better cross-platform compatibility\n\n### Troubleshooting\n\nIf you encounter Docker issues, see [DOCKER-TROUBLESHOOTING.md](./DOCKER-TROUBLESHOOTING.md) for detailed solutions.\n\n## 🤝 Contributing\n\nWe welcome contributions to the IL2CPP Dump Analyzer Agentic RAG MCP System! Please follow these guidelines:\n\n### Development Guidelines\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-agentic-feature`\n3. **Follow Test-Driven Development (TFD)**: Write tests before implementing features\n4. **Add comprehensive tests**: Include unit, integration, and agentic component tests\n5. **Run the full test suite**: `npm test`\n6. **Test agentic components**: `npm run test -- --testPathPattern=agent`\n7. **Commit your changes**: `git commit -m 'Add amazing agentic feature'`\n8. **Push to the branch**: `git push origin feature/amazing-agentic-feature`\n9. **Open a Pull Request**\n\n### Agentic Development Guidelines\n\nWhen contributing to agentic components:\n\n- **Context Preservation**: Ensure context is properly managed across tool calls\n- **Performance Optimization**: Consider performance implications of intelligent workflows\n- **Tool Orchestration**: Design workflows that intelligently chain MCP tools\n- **Error Recovery**: Implement robust error handling and recovery mechanisms\n- **Adaptive Learning**: Consider how the system can learn from usage patterns\n\n### Code Quality Standards\n\n- **TypeScript Strict Mode**: Maintain full TypeScript compliance\n- **JSDoc Documentation**: Document all functions with comprehensive JSDoc comments\n- **Zod Validation**: Use Zod schemas for all input validation\n- **MCP Compliance**: Ensure all MCP tools follow the official specification\n- **Agentic Patterns**: Follow established patterns for agentic component development\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification and agentic framework foundation\n- [Xenova/Transformers.js](https://github.com/xenova/transformers.js) for client-side embeddings and AI capabilities\n- [Supabase](https://supabase.com/) for vector database infrastructure and real-time capabilities\n- [TypeScript](https://www.typescriptlang.org/) for type safety and development experience\n- Unity Technologies for IL2CPP technology and game development innovation\n- The open-source community for continuous inspiration and collaboration\n\n---\n\n**Built with ❤️ for the Unity game development and reverse engineering community**\n\n*Empowering developers with intelligent IL2CPP analysis through agentic AI and the Model Context Protocol*\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjfaizp%2Fil2cpp-dump-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjfaizp%2Fil2cpp-dump-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjfaizp%2Fil2cpp-dump-analyzer/lists"}