V Language MCP Server

#!/usr/bin/env python3 """ V Language MCP Server A Model Context Protocol server that provides comprehensive information about the V programming language to help LLMs understand and generate V code. """ import os import re import json import logging import time from pathlib import Path from typing import List, Dict, Any, Optional from functools import lru_cache from fastmcp import FastMCP import asyncio from dataclasses import dataclass # Configure logging logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s') logger = logging.getLogger(__name__) @dataclass class VServerConfig: """Configuration for the V MCP Server.""" v_repo_path: Path v_ui_path: Optional[Path] = None cache_ttl_seconds: int = 300 # 5 minutes default max_search_results: int = 50 log_level: str = "INFO" @classmethod def from_env(cls) -> 'VServerConfig': """Create configuration from environment variables.""" # V repository path v_repo_path = os.getenv('V_REPO_PATH') if v_repo_path: repo_path = Path(v_repo_path) else: # Default to parent directory repo_path = Path(__file__).parent.parent # V UI repository path (optional) v_ui_path = os.getenv('V_UI_PATH') if v_ui_path: ui_path = Path(v_ui_path) else: # Default to v-ui submodule in parent directory ui_path = repo_path / "v-ui" if not ui_path.exists(): ui_path = None # Cache TTL cache_ttl = int(os.getenv('V_CACHE_TTL_SECONDS', '300')) # Max search results max_results = int(os.getenv('V_MAX_SEARCH_RESULTS', '50')) # Log level log_level = os.getenv('V_LOG_LEVEL', 'INFO').upper() return cls( v_repo_path=repo_path, v_ui_path=ui_path, cache_ttl_seconds=cache_ttl, max_search_results=max_results, log_level=log_level ) # Initialize FastMCP server mcp = FastMCP("V Language Assistant") # Load configuration config = VServerConfig.from_env() # Configure logging level logging.getLogger().setLevel(getattr(logging, config.log_level, logging.INFO)) class VDocumentationServer: """Server for providing V language documentation and examples.""" def __init__(self, config: VServerConfig): self.config = config self.v_repo_path = config.v_repo_path self.docs_path = config.v_repo_path / "doc" self.examples_path = config.v_repo_path / "examples" self.vlib_path = config.v_repo_path / "vlib" # V UI paths (optional) self.v_ui_path = config.v_ui_path self.v_ui_examples_path = config.v_ui_path / "examples" if config.v_ui_path else None self.v_ui_docs_path = config.v_ui_path / "docs.md" if config.v_ui_path else None # Cache with TTL (time-to-live) in seconds self._cache = {} self._cache_ttl = config.cache_ttl_seconds self._cache_timestamps = {} self._max_search_results = config.max_search_results # Store path validation results for graceful degradation self._path_status = self._validate_paths() def _validate_paths(self) -> Dict[str, bool]: """Validate that required paths exist and return status.""" path_status = { "docs": self.docs_path.exists(), "examples": self.examples_path.exists(), "stdlib": self.vlib_path.exists(), "v_ui": self.v_ui_path.exists() if self.v_ui_path else False, "v_ui_examples": self.v_ui_examples_path.exists() if self.v_ui_examples_path else False } missing_paths = [] for component, exists in path_status.items(): if not exists and component not in ["v_ui", "v_ui_examples"]: # V UI is optional path = getattr(self, f"{component}_path", None) if path: missing_paths.append(f"{component.title()}: {path}") if missing_paths: logger.warning(f"Some V repository components are missing: {', '.join(missing_paths)}") logger.warning("Server functionality will be limited to available components") else: logger.info("All V repository components found successfully") if path_status.get("v_ui"): logger.info("V UI repository found and will be indexed") elif self.v_ui_path: logger.info(f"V UI repository path specified but not found: {self.v_ui_path}") return path_status def _get_cache(self, key: str) -> Any: """Get item from cache if it exists and hasn't expired.""" if key in self._cache: if time.time() - self._cache_timestamps.get(key, 0) < self._cache_ttl: return self._cache[key] else: # Remove expired entry del self._cache[key] del self._cache_timestamps[key] return None def _set_cache(self, key: str, value: Any) -> None: """Store item in cache with current timestamp.""" self._cache[key] = value self._cache_timestamps[key] = time.time() def _clear_expired_cache(self) -> None: """Remove all expired cache entries.""" current_time = time.time() expired_keys = [ key for key, timestamp in self._cache_timestamps.items() if current_time - timestamp >= self._cache_ttl ] for key in expired_keys: del self._cache[key] del self._cache_timestamps[key] def clear_cache(self) -> Dict[str, int]: """Clear all cache entries and return statistics.""" cache_count = len(self._cache) timestamp_count = len(self._cache_timestamps) self._cache.clear() self._cache_timestamps.clear() return { "cleared_entries": cache_count, "cleared_timestamps": timestamp_count, "message": f"Cleared {cache_count} cache entries" } def get_cache_stats(self) -> Dict[str, int]: """Get cache statistics without clearing.""" return { "entries": len(self._cache), "timestamps": len(self._cache_timestamps), "ttl_seconds": self._cache_ttl } def _validate_query(self, query: str, min_length: int = 2) -> str: """Validate and sanitize search query.""" if not query or len(query.strip()) < min_length: raise ValueError(f"Query must be at least {min_length} characters long") return query.strip() def _read_file_content(self, file_path: Path) -> str: """Read file content safely.""" try: if not file_path.exists(): return f"Error: File not found: {file_path}" with open(file_path, 'r', encoding='utf-8', errors='replace') as f: return f.read() except PermissionError: return f"Error: Permission denied reading file {file_path}" except UnicodeDecodeError: return f"Error: Unable to decode file {file_path} (encoding issue)" except Exception as e: logger.error(f"Unexpected error reading file {file_path}: {e}") return f"Error reading file {file_path}: {str(e)}" def _search_in_file(self, file_path: Path, pattern: str, context_lines: int = 3) -> List[Dict]: """Search for pattern in file and return matches with enhanced context.""" try: if not file_path.exists(): return [{'error': f'File not found: {file_path}'}] if not pattern or len(pattern.strip()) < 1: return [{'error': 'Search pattern cannot be empty'}] with open(file_path, 'r', encoding='utf-8', errors='replace') as f: content = f.read() matches = [] # Create case-insensitive pattern with word boundaries for better matching search_pattern = r'\b' + re.escape(pattern) + r'\b' compiled_pattern = re.compile(search_pattern, re.IGNORECASE | re.MULTILINE) lines = content.split('\n') for i, line in enumerate(lines): if compiled_pattern.search(line): # Enhanced context: try to get paragraph-level context start_line = max(0, i - context_lines) end_line = min(len(lines), i + context_lines + 1) # Look for paragraph boundaries (empty lines) while start_line > 0 and lines[start_line - 1].strip(): start_line -= 1 while end_line < len(lines) and lines[end_line].strip(): end_line += 1 context_lines_list = lines[start_line:end_line] context = '\n'.join(context_lines_list).strip() # Calculate relevance score based on: # - Exact match bonus # - Position in line (earlier = higher score) # - Context richness score = 1.0 if pattern.lower() in line.lower(): score += 0.5 # Exact match bonus if line.lower().startswith(pattern.lower()): score += 0.3 # Starts with pattern bonus if len(context) > len(line): score += 0.2 # Rich context bonus matches.append({ 'line': i + 1, 'content': line.strip(), 'context': context, 'file': str(file_path.relative_to(self.v_repo_path)), 'score': score, 'pattern': pattern }) # Sort by relevance score (highest first) matches.sort(key=lambda x: x['score'], reverse=True) return matches except re.error as e: return [{'error': f'Invalid regex pattern: {pattern} - {str(e)}'}] except PermissionError: return [{'error': f'Permission denied reading file: {file_path}'}] except Exception as e: logger.error(f'Unexpected error searching file {file_path}: {e}') return [{'error': f'Error searching file {file_path}: {str(e)}'}] def get_documentation_sections(self) -> Dict[str, str]: """Extract main sections from V documentation.""" cache_key = "docs_sections" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result docs_file = self.docs_path / "docs.md" if not docs_file.exists(): result = {"error": "Documentation file not found"} self._set_cache(cache_key, result) return result content = self._read_file_content(docs_file) # Split by main headers sections = {} current_section = None current_content = [] for line in content.split('\n'): if line.startswith('# '): if current_section: sections[current_section] = '\n'.join(current_content) current_section = line[2:].strip() current_content = [line] elif line.startswith('## '): if current_section: sections[current_section] = '\n'.join(current_content) current_section = line[3:].strip() current_content = [line] else: current_content.append(line) if current_section: sections[current_section] = '\n'.join(current_content) # Cache the result self._set_cache(cache_key, sections) return sections def search_documentation(self, query: str) -> List[Dict]: """Search V documentation for relevant information.""" try: query = self._validate_query(query) docs_file = self.docs_path / "docs.md" if not docs_file.exists(): return [{"error": f"Documentation file not found at {docs_file}"}] return self._search_in_file(docs_file, query) except ValueError as e: return [{"error": str(e)}] except Exception as e: logger.error(f"Error searching documentation: {e}") return [{"error": f"Failed to search documentation: {str(e)}"}] def get_examples_list(self) -> List[Dict]: """Get list of available V examples.""" cache_key = "examples_list" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result if not self.examples_path.exists(): result = [{"error": "Examples directory not found"}] self._set_cache(cache_key, result) return result examples = [] for item in self.examples_path.rglob("*.v"): if item.is_file(): examples.append({ 'name': item.stem, 'path': str(item.relative_to(self.v_repo_path)), 'description': self._extract_example_description(item) }) # Cache the result self._set_cache(cache_key, examples) return examples def _extract_example_description(self, file_path: Path) -> str: """Extract description from example file comments.""" try: with open(file_path, 'r', encoding='utf-8') as f: lines = f.readlines()[:10] # Check first 10 lines for line in lines: if line.strip().startswith('//') or line.strip().startswith('/*'): desc = line.strip()[2:].strip() if desc and not desc.startswith('Copyright'): return desc except: pass return f"V example: {file_path.stem}" def get_example_content(self, example_name: str) -> Dict: """Get content of a specific example.""" cache_key = f"example_content_{example_name}" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result for item in self.examples_path.rglob(f"{example_name}.v"): if item.is_file(): result = { 'name': example_name, 'path': str(item.relative_to(self.v_repo_path)), 'content': self._read_file_content(item) } # Cache the result self._set_cache(cache_key, result) return result result = {"error": f"Example '{example_name}' not found"} # Cache negative results too to avoid repeated filesystem searches self._set_cache(cache_key, result) return result def search_examples(self, query: str) -> List[Dict]: """Search through V examples for patterns.""" try: query = self._validate_query(query) if not self.examples_path.exists(): return [{"error": f"Examples directory not found at {self.examples_path}"}] results = [] v_files = list(self.examples_path.rglob("*.v")) if not v_files: return [{"error": "No V example files found"}] for v_file in v_files[:self._max_search_results]: # Limit based on configuration matches = self._search_in_file(v_file, query) if matches: for match in matches: if 'error' not in match: # Only add successful matches match['example_name'] = v_file.stem results.append(match) return results except ValueError as e: return [{"error": str(e)}] except Exception as e: logger.error(f"Error searching examples: {e}") return [{"error": f"Failed to search examples: {str(e)}"}] def get_stdlib_modules(self) -> List[Dict]: """Get list of V standard library modules.""" cache_key = "stdlib_modules" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result if not self.vlib_path.exists(): result = [{"error": "Standard library directory not found"}] self._set_cache(cache_key, result) return result modules = [] for item in self.vlib_path.iterdir(): if item.is_dir() and not item.name.startswith('.'): readme_file = item / "README.md" description = "V standard library module" if readme_file.exists(): content = self._read_file_content(readme_file) # Extract first meaningful line as description for line in content.split('\n')[:5]: line = line.strip() if line and not line.startswith('#') and len(line) > 10: description = line break modules.append({ 'name': item.name, 'path': str(item.relative_to(self.v_repo_path)), 'description': description }) sorted_modules = sorted(modules, key=lambda x: x['name']) # Cache the result self._set_cache(cache_key, sorted_modules) return sorted_modules def get_module_info(self, module_name: str) -> Dict: """Get information about a specific standard library module.""" module_path = self.vlib_path / module_name if not module_path.exists(): return {"error": f"Module '{module_name}' not found"} info = { 'name': module_name, 'files': [], 'readme': None } # Get README if available readme_file = module_path / "README.md" if readme_file.exists(): info['readme'] = self._read_file_content(readme_file) # List V files in the module for v_file in module_path.rglob("*.v"): if v_file.is_file(): info['files'].append({ 'name': v_file.name, 'path': str(v_file.relative_to(self.v_repo_path)), 'size': v_file.stat().st_size }) return info def get_v_ui_examples_list(self) -> List[Dict]: """Get a list of all V UI examples.""" cache_key = "v_ui_examples_list" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result if not self.v_ui_examples_path or not self.v_ui_examples_path.exists(): result = [{"error": "V UI examples directory not found"}] self._set_cache(cache_key, result) return result examples = [] for item in self.v_ui_examples_path.rglob("*.v"): if item.is_file(): examples.append({ 'name': item.stem, 'path': str(item.relative_to(self.v_ui_path)), 'full_path': str(item) }) sorted_examples = sorted(examples, key=lambda x: x['name']) # Cache the result self._set_cache(cache_key, sorted_examples) return sorted_examples def get_v_ui_example_content(self, example_name: str) -> Dict: """Get the content of a specific V UI example.""" cache_key = f"v_ui_example_{example_name}" # Try cache first cached_result = self._get_cache(cache_key) if cached_result: return cached_result if not self.v_ui_examples_path or not self.v_ui_examples_path.exists(): result = {"error": "V UI examples directory not found"} self._set_cache(cache_key, result) return result # Search for the example file for item in self.v_ui_examples_path.rglob(f"{example_name}.v"): if item.is_file(): content = self._read_file_content(item) result = { 'name': example_name, 'path': str(item.relative_to(self.v_ui_path)), 'content': content } self._set_cache(cache_key, result) return result result = {"error": f"V UI example '{example_name}' not found"} self._set_cache(cache_key, result) return result def search_v_ui_examples(self, query: str) -> List[Dict]: """Search through V UI examples for specific patterns.""" try: query = self._validate_query(query) if not self.v_ui_examples_path or not self.v_ui_examples_path.exists(): return [{"error": f"V UI examples directory not found at {self.v_ui_examples_path}"}] results = [] v_files = list(self.v_ui_examples_path.rglob("*.v")) if not v_files: return [{"error": "No V UI example files found"}] for file_path in v_files: matches = self._search_in_file(file_path, query) for match in matches: match['source'] = 'v_ui' match['file'] = str(file_path.relative_to(self.v_ui_path)) results.append(match) # Sort by relevance score and limit results results.sort(key=lambda x: x.get('score', 0), reverse=True) results = results[:self._max_search_results] return results if results else [{"message": f"No matches found for '{query}' in V UI examples"}] except ValueError as e: return [{"error": str(e)}] except Exception as e: logger.error(f"Error searching V UI examples: {e}") return [{"error": f"Error searching V UI examples: {str(e)}"}] # Initialize the documentation server v_server = VDocumentationServer(config) # MCP Tools @mcp.tool def get_v_documentation(section: Optional[str] = None) -> str: """ Get V programming language documentation. Provides access to the complete V programming language documentation. When no section is specified, returns an overview of all available sections. When a specific section is requested, returns detailed content for that section. Args: section: Optional specific section to retrieve (e.g., 'Structs', 'Functions', 'Modules') Returns: Documentation content for the requested section or overview of available sections """ try: # Check if documentation is available if not v_server._path_status.get("docs", False): return """# V Documentation - Not Available ❌ **V documentation is not available on this system.** This could be because: - The V repository is not properly set up - The documentation files are missing - The V_REPO_PATH environment variable points to the wrong location ## Solutions: 1. **Verify V repository location:** ```bash # Check if you're in the correct directory ls -la # Should see doc/, examples/, vlib/ directories ``` 2. **Set V_REPO_PATH if needed:** ```bash export V_REPO_PATH="/path/to/v/repository" ``` 3. **Check server configuration:** Use `get_v_config()` to see current settings 4. **Restart the MCP server** after fixing the path **Alternative:** Use `explain_v_syntax(feature)` for specific language features or `get_v_quick_reference()` for basic syntax.""" sections = v_server.get_documentation_sections() if "error" in sections: return f"""# V Documentation - Error ❌ **Error loading V documentation:** {sections['error']} This might be a temporary issue. Try: - `clear_v_cache()` to refresh cached content - `get_v_config()` to check server status - Restarting the MCP server **Alternative resources:** - Use `explain_v_syntax(feature)` for specific language features - Use `get_v_quick_reference()` for basic syntax reference""" if section: if section in sections: return f"# {section}\n\n{sections[section]}" else: available_sections = list(sections.keys()) return f"""# Section Not Found ❌ **Section '{section}' not found in V documentation.** **Available sections:** {chr(10).join(f"- {sec}" for sec in available_sections[:10])} **Suggestions:** - Check spelling and capitalization - Use `get_v_documentation()` to see all sections - Try `search_v_docs('{section}')` for related content""" else: # Return overview of main sections overview = "# V Programming Language Documentation\n\n" overview += f"✅ **Documentation loaded successfully** ({len(sections)} sections available)\n\n" overview += "**Available sections:**\n\n" for sec in sections.keys(): overview += f"- {sec}\n" overview += "\n**Usage:** `get_v_documentation(section_name)` to get specific sections." return overview except Exception as e: logger.error(f"Unexpected error in get_v_documentation: {e}") return f"""# Documentation Error ❌ **Unexpected error loading V documentation:** {str(e)} Please try: - `get_v_config()` to check server status - `clear_v_cache()` to reset cache - Restarting the MCP server **Alternative:** Use `explain_v_syntax(feature)` for specific language features.""" @mcp.tool def search_v_docs(query: str) -> str: """ Search through V documentation for specific topics. Performs full-text search across the V programming language documentation. Returns relevant sections with context where the search terms are found. Args: query: Search term to look for in V documentation (minimum 2 characters) Returns: Search results with relevant documentation sections and context """ results = v_server.search_documentation(query) if not results: return f"No results found for '{query}' in V documentation." output = f"# Search Results for '{query}'\n\n" successful_results = [r for r in results if 'error' not in r] if successful_results: output += f"Found {len(successful_results)} matches (showing top 10):\n\n" for result in successful_results[:10]: # Show top 10 by relevance score output += f"**File:** {result['file']}\n" output += f"**Line {result['line']}:** {result['content']}\n" output += f"**Context:**\n```\n{result['context']}\n```\n\n" else: # Show any error messages for result in results: if 'error' in result: output += f"Error: {result['error']}\n\n" return output @mcp.tool def list_v_examples() -> str: """ Get a list of available V programming examples. Returns a comprehensive list of all available V code examples from the repository. Each example includes its name, file path, and description extracted from comments. Returns: Formatted list of example programs with descriptions (shows first 20 examples) """ try: # Check if examples are available if not v_server._path_status.get("examples", False): return """# V Examples - Not Available ❌ **V code examples are not available on this system.** This could be because: - The V repository is not properly set up - The examples directory is missing - The V_REPO_PATH environment variable points to the wrong location ## Solutions: 1. **Verify examples directory exists:** ```bash # Check if examples directory exists ls -la examples/ ``` 2. **Set V_REPO_PATH if needed:** ```bash export V_REPO_PATH="/path/to/v/repository" ``` 3. **Check server configuration:** Use `get_v_config()` to see current settings 4. **Restart the MCP server** after fixing the path **Alternative:** Use `explain_v_syntax(feature)` to learn V language features with code examples.""" examples = v_server.get_examples_list() if not examples: return """# No Examples Found ❌ **No V examples were found.** This might be because: - The examples directory exists but is empty - File permissions prevent reading - The V repository structure has changed Try: - `get_v_config()` to check server status - `clear_v_cache()` to refresh cached content - Restarting the MCP server""" # Check if there are any actual examples (not just error entries) valid_examples = [ex for ex in examples if 'error' not in ex] error_examples = [ex for ex in examples if 'error' in ex] output = "# V Programming Examples\n\n" if error_examples: output += f"⚠️ **Warning:** {len(error_examples)} example(s) could not be loaded.\n\n" if valid_examples: output += f"✅ **Found {len(valid_examples)} examples**\n\n" for example in valid_examples[:20]: # Limit to first 20 examples output += f"**{example['name']}**\n" output += f"- Path: {example['path']}\n" output += f"- Description: {example['description']}\n\n" if len(valid_examples) > 20: output += f"\n*Showing first 20 of {len(valid_examples)} examples.*\n" output += "*Use `get_v_example(name)` to see the full code for any example.*" else: output += "*Use `get_v_example(name)` to see the full code for any example.*" else: output += "❌ **No valid examples could be loaded.**\n\n" output += "**Troubleshooting:**\n" output += "- Check file permissions in the examples directory\n" output += "- Verify the examples contain .v files\n" output += "- Try `get_v_config()` for detailed status" return output except Exception as e: logger.error(f"Unexpected error in list_v_examples: {e}") return f"""# Examples Error ❌ **Unexpected error loading V examples:** {str(e)} Please try: - `get_v_config()` to check server status - `clear_v_cache()` to reset cache - Restarting the MCP server **Alternative:** Use `explain_v_syntax(feature)` for language feature explanations.""" @mcp.tool def get_v_example(example_name: str) -> str: """ Get the source code of a specific V example. Retrieves the complete source code for a named V programming example. The example name should match the filename without the .v extension. Args: example_name: Name of the example to retrieve (e.g., 'fibonacci', 'hello_world') Returns: Complete source code of the example with syntax highlighting, or error message if not found """ result = v_server.get_example_content(example_name) if 'error' in result: return f"""# Example Not Found ❌ **Example '{example_name}' not found.** **Possible reasons:** - Incorrect spelling or capitalization - Example doesn't exist in the repository - Examples directory is not available **Suggestions:** - Use `list_v_examples()` to see all available examples - Try `search_v_examples('{example_name}')` for similar examples - Check `get_v_config()` for server status **Error details:** {result['error']}""" output = f"# V Example: {result['name']}\n\n" output += f"**Path:** {result['path']}\n\n" output += "## Source Code\n\n" output += f"```v\n{result['content']}\n```\n" return output @mcp.tool def search_v_examples(query: str) -> str: """ Search through V example code for specific patterns or features. Performs full-text search across all V programming examples in the repository. Useful for finding code patterns, specific functions, or language features in use. Args: query: Search term to look for in example code (minimum 2 characters) Returns: Examples containing the search term with context and file information """ results = v_server.search_examples(query) if not results: return f"No examples found containing '{query}'." output = f"# Examples containing '{query}'\n\n" successful_results = [r for r in results if 'error' not in r] if successful_results: output += f"Found {len(successful_results)} matches across examples:\n\n" current_example = None for result in successful_results[:15]: # Show top 15 results if current_example != result['example_name']: current_example = result['example_name'] output += f"## Example: {current_example}\n\n" output += f"**File:** {result['file']}\n" output += f"**Line {result['line']}:** {result['content']}\n" output += f"**Context:**\n```v\n{result['context']}\n```\n\n" else: # Show any error messages for result in results: if 'error' in result: output += f"Error: {result['error']}\n\n" return output @mcp.tool def list_v_stdlib_modules() -> str: """ Get a list of V standard library modules. Returns a comprehensive list of all available modules in V's standard library. Each module includes its name, description, and indicates its functionality. Returns: Formatted list of standard library modules with descriptions """ modules = v_server.get_stdlib_modules() if not modules: return "No standard library modules found." output = "# V Standard Library Modules\n\n" for module in modules: if 'error' in module: output += f"Error: {module['error']}\n" else: output += f"**{module['name']}**\n" output += f"- Description: {module['description']}\n\n" output += "\nUse `get_v_module_info(module_name)` to get detailed information about a specific module." return output @mcp.tool def get_v_module_info(module_name: str) -> str: """ Get detailed information about a V standard library module. Provides comprehensive information about a specific V standard library module, including its README documentation (if available) and list of source files. Args: module_name: Name of the module to get information about (e.g., 'os', 'json', 'net') Returns: Detailed information including files, documentation, and module structure """ result = v_server.get_module_info(module_name) if 'error' in result: return f"Error: {result['error']}\n\nUse `list_v_stdlib_modules()` to see available modules." output = f"# V Standard Library Module: {result['name']}\n\n" if result['readme']: output += "## Documentation\n\n" output += result['readme'] output += "\n\n" if result['files']: output += "## Files\n\n" for file_info in result['files'][:10]: # Limit to first 10 files output += f"- **{file_info['name']}** ({file_info['size']} bytes)\n" output += f" - Path: {file_info['path']}\n" if len(result['files']) > 10: output += f"\n*... and {len(result['files']) - 10} more files*\n" return output @mcp.tool def explain_v_syntax(feature: str) -> str: """ Explain V programming language syntax and features. Provides detailed explanations of V programming language concepts and syntax. Includes code examples and practical usage patterns for each feature. Args: feature: The V language feature to explain (e.g., 'arrays', 'structs', 'functions', 'concurrency') Returns: Comprehensive explanation of the requested V language feature with examples """ # Common V language features and their explanations features = { 'variables': """ # V Variables V supports several types of variables: ## Declaration and Initialization ```v name := 'Bob' // Inferred type string age := 20 // Inferred type int is_adult := true // Inferred type bool ``` ## Explicit Type Declaration ```v mut name string = 'Bob' // Mutable variable age int = 20 // Immutable variable ``` ## Constants ```v const pi = 3.14159 const ( rate = 0.05 days = 365 ) ``` """, 'arrays': """ # V Arrays ## Declaration and Initialization ```v mut numbers := [1, 2, 3] // Inferred type []int names := ['Alice', 'Bob'] // []string empty := []int{} // Empty array ``` ## Array Operations ```v numbers << 4 // Append element numbers << [5, 6] // Append array first := numbers[0] // Access element numbers[1] = 10 // Modify element len := numbers.len // Get length ``` ## Array Methods ```v numbers.insert(0, 0) // Insert at index numbers.delete(1) // Delete element numbers.reverse() // Reverse array numbers.sort() // Sort array ``` """, 'structs': """ # V Structs ## Definition ```v struct User { id int name string age int mut: email string // Mutable field pub: active bool // Public field } ``` ## Usage ```v user := User{ id: 1 name: 'Alice' age: 30 email: 'alice@example.com' active: true } // Access fields println(user.name) // Alice user.email = 'new@example.com' // Modify mutable field ``` ## Methods ```v fn (u User) full_name() string { return '${u.name} (ID: ${u.id})' } fn (mut u User) deactivate() { u.active = false } ``` """, 'functions': """ # V Functions ## Basic Function ```v fn greet(name string) string { return 'Hello, ${name}!' } message := greet('World') ``` ## Multiple Return Values ```v fn divide(a int, b int) (int, int) { quotient := a / b remainder := a % b return quotient, remainder } q, r := divide(10, 3) ``` ## Variadic Functions ```v fn sum(numbers ...int) int { mut total := 0 for num in numbers { total += num } return total } result := sum(1, 2, 3, 4, 5) ``` ## Anonymous Functions ```v fn apply_twice(f fn(int) int, x int) int { return f(f(x)) } double := fn(x int) int { return x * 2 } result := apply_twice(double, 3) // 12 ``` """, 'control_flow': """ # V Control Flow ## If Statements ```v age := 18 if age >= 18 { println('Adult') } else if age >= 13 { println('Teenager') } else { println('Child') } ``` ## If as Expression ```v max := if a > b { a } else { b } status := if user.active { 'Active' } else { 'Inactive' } ``` ## Match Statement ```v color := 'red' match color { 'red' { println('Stop!') } 'yellow' { println('Caution!') } 'green' { println('Go!') } else { println('Unknown color') } } ``` ## For Loops ```v // Basic loop for i in 0..10 { println(i) } // Loop over array fruits := ['apple', 'banana', 'cherry'] for fruit in fruits { println(fruit) } // Loop with index for i, fruit in fruits { println('${i}: ${fruit}') } // Infinite loop for { println('Forever...') break } ``` """, 'modules': """ # V Modules ## Module Declaration Each V file belongs to a module. The module name is the same as the folder name. ``` project/ ├── main.v └── utils/ ├── math.v └── string.v ``` ## Importing Modules ```v import os import utils.math import utils.string as str_utils ``` ## Selective Imports ```v import os { read_file, write_file } import utils.math { add, multiply as mul } ``` ## Module Initialization ```v // In utils/math.v module math pub fn add(a int, b int) int { return a + b } // In main.v import utils.math fn main() { result := math.add(5, 3) println(result) // 8 } ``` """, 'error_handling': """ # V Error Handling ## Option Types ```v fn find_user(id int) ?User { if id < 0 { return none } return User{ id: id, name: 'User ${id}' } } // Usage user := find_user(123) or { println('User not found') return } println(user.name) ``` ## If Unwrapping ```v if user := find_user(456) { println(user.name) } else { println('User not found') } ``` ## Error Types ```v fn risky_operation() !string { if rand.intn(2) == 0 { return error('Something went wrong') } return 'Success!' } // Usage result := risky_operation() or { println('Error: ${err}') exit(1) } println(result) ``` """, 'concurrency': """ # V Concurrency ## Goroutines ```v fn worker(id int) { println('Worker ${id} starting') time.sleep(1 * time.second) println('Worker ${id} done') } fn main() { for i in 1..5 { go worker(i) } time.sleep(2 * time.second) // Wait for goroutines } ``` ## Channels ```v fn producer(ch chan int) { for i in 1..10 { ch <- i time.sleep(100 * time.millisecond) } ch.close() } fn consumer(ch chan int) { for { if val := <-ch { println('Received: ${val}') } else { break // Channel closed } } } fn main() { ch := chan int{} go producer(ch) consumer(ch) } ``` """ } try: if not feature or len(feature.strip()) < 1: available_features = list(features.keys()) return f"Feature name cannot be empty. Available features: {', '.join(available_features)}" feature_key = feature.lower().strip() if feature_key in features: return features[feature_key] else: available_features = sorted(features.keys()) return f"Feature '{feature}' not found. Available features: {', '.join(available_features)}\n\nUse `search_v_docs('{feature}')` to search documentation for this topic." except Exception as e: logger.error(f"Error explaining V syntax for feature '{feature}': {e}") available_features = sorted(features.keys()) return f"An error occurred while explaining '{feature}'. Available features: {', '.join(available_features)}" @mcp.tool def get_v_quick_reference() -> str: """ Get a quick reference guide for V programming language basics. Provides a concise reference covering the most essential V programming language syntax and concepts. Perfect for getting started or as a quick reminder. Returns: Quick reference guide with essential V language syntax and examples """ return """ # V Programming Language Quick Reference ## Basic Syntax ```v // Hello World fn main() { println('Hello, World!') } // Variables name := 'Alice' // Inferred string age := 30 // Inferred int is_active := true // Inferred bool mut counter := 0 // Mutable variable // Constants const pi = 3.14159 const days_in_week = 7 ``` ## Data Types ```v // Primitives bool_var := true // bool int_var := 42 // int float_var := 3.14 // f64 string_var := 'hello' // string rune_var := `A` // rune (Unicode code point) // Arrays numbers := [1, 2, 3] // []int names := ['Alice', 'Bob'] // []string empty := []int{} // Empty array // Maps ages := {'Alice': 30, 'Bob': 25} // map[string]int ``` ## Control Flow ```v // If statement if age >= 18 { println('Adult') } else { println('Minor') } // For loops for i in 0..5 { println(i) // 0, 1, 2, 3, 4 } fruits := ['apple', 'banana'] for fruit in fruits { println(fruit) } // Match color := 'red' match color { 'red' => println('Stop') 'green' => println('Go') else => println('Unknown') } ``` ## Functions ```v fn greet(name string) string { return 'Hello, ${name}!' } fn add(a int, b int) int { return a + b } // Multiple return values fn divide(a int, b int) (int, int) { return a / b, a % b } quotient, remainder := divide(10, 3) ``` ## Structs ```v struct User { id int name string mut: email string } user := User{ id: 1 name: 'Alice' email: 'alice@example.com' } ``` ## Modules ```v // In utils.v module utils pub fn helper() string { return 'Helper function' } // In main.v import utils fn main() { result := utils.helper() println(result) } ``` ## Error Handling ```v fn risky() ?string { if rand.intn(2) == 0 { return none } return 'Success!' } if result := risky() { println(result) } else { println('Failed!') } ``` ## Arrays and Strings ```v // Array operations mut numbers := [1, 2, 3] numbers << 4 // Append numbers.insert(0, 0) // Insert at index numbers.delete(1) // Delete at index // String operations text := 'Hello, World!' println(text.len) // Length println(text.contains('World')) // true parts := text.split(', ') // Split into array ``` ## File I/O ```v import os // Read file content := os.read_file('file.txt') or { println('Error reading file') return } // Write file text := 'Hello, File!' os.write_file('output.txt', text) or { println('Error writing file') return } ``` ## Concurrency ```v import time fn worker(id int) { println('Worker ${id}') time.sleep(1 * time.second) } // Start goroutine go worker(1) go worker(2) // Channels ch := chan int{} go fn() { ch <- 42 }() value := <-ch println(value) // 42 ``` For more detailed information, use the other tools available: - `get_v_documentation()` - Full language documentation - `search_v_docs(query)` - Search documentation - `list_v_examples()` - Browse code examples - `explain_v_syntax(feature)` - Detailed syntax explanations Available features for explain_v_syntax: - variables, arrays, structs, functions, control_flow, modules, error_handling, concurrency """ @mcp.tool def get_v_config() -> str: """ Get current V MCP server configuration. Shows the current configuration settings including V repository path, cache settings, and other server parameters. Returns: Current server configuration information """ output = f"# V MCP Server Configuration\n\n" output += f"**V Repository Path:** `{config.v_repo_path}`\n" output += f"**Cache TTL:** {config.cache_ttl_seconds} seconds ({config.cache_ttl_seconds // 60} minutes)\n" output += f"**Max Search Results:** {config.max_search_results}\n" output += f"**Log Level:** {config.log_level}\n\n" # Check if paths exist output += f"**Path Status:**\n" paths = { "Documentation": config.v_repo_path / "doc", "Examples": config.v_repo_path / "examples", "Standard Library": config.v_repo_path / "vlib" } for name, path in paths.items(): status = "✅ Found" if path.exists() else "❌ Missing" output += f"- **{name}:** {status} (`{path}`)\n" # Cache statistics cache_stats = v_server.get_cache_stats() output += f"\n**Cache Statistics:**\n" output += f"- Current cache entries: {cache_stats['entries']}\n" output += f"- Cache TTL: {cache_stats['ttl_seconds']}s ({cache_stats['ttl_seconds'] // 60} minutes)\n" return output @mcp.tool def clear_v_cache() -> str: """ Clear the V MCP server cache. This clears all cached documentation, examples, and search results. Useful when the V repository has been updated and you want fresh content. Returns: Cache clearing statistics and confirmation message """ result = v_server.clear_cache() output = f"# Cache Cleared\n\n" output += f"✅ {result['message']}\n\n" output += f"**Statistics:**\n" output += f"- Cache entries cleared: {result['cleared_entries']}\n" output += f"- Timestamp entries cleared: {result['cleared_timestamps']}\n\n" output += f"Next requests will reload content from the V repository." return output @mcp.tool def list_v_ui_examples() -> str: """ Get a list of available V UI examples. Returns a comprehensive list of all available V UI code examples from the v-ui repository. Returns: JSON string containing a list of V UI examples with their names and paths """ try: if not v_server._path_status.get("v_ui_examples", False): return json.dumps({ "error": "V UI examples are not available", "message": "V UI repository not found or examples directory missing. Make sure the v-ui submodule is initialized." }, indent=2) examples = v_server.get_v_ui_examples_list() if examples and "error" in examples[0]: return json.dumps(examples[0], indent=2) return json.dumps({ "count": len(examples), "examples": examples[:50] # Limit to first 50 for readability }, indent=2) except Exception as e: logger.error(f"Error listing V UI examples: {e}") return json.dumps({"error": f"Error listing V UI examples: {str(e)}"}, indent=2) @mcp.tool def get_v_ui_example(example_name: str) -> str: """ Get the source code of a specific V UI example. Retrieves the complete source code for a named V UI programming example. Args: example_name: Name of the V UI example to retrieve (without .v extension) Returns: JSON string containing the example source code and metadata """ try: if not v_server._path_status.get("v_ui_examples", False): return json.dumps({ "error": "V UI examples are not available", "message": "V UI repository not found or examples directory missing." }, indent=2) result = v_server.get_v_ui_example_content(example_name) return json.dumps(result, indent=2) except Exception as e: logger.error(f"Error getting V UI example: {e}") return json.dumps({"error": f"Error getting V UI example: {str(e)}"}, indent=2) @mcp.tool def search_v_ui_examples(query: str) -> str: """ Search through V UI example code for specific patterns or features. Performs full-text search across all V UI programming examples in the repository. Args: query: Search query (supports regex patterns) Returns: JSON string containing search results with matching code snippets """ try: if not v_server._path_status.get("v_ui_examples", False): return json.dumps({ "error": "V UI examples are not available", "message": "V UI repository not found or examples directory missing." }, indent=2) results = v_server.search_v_ui_examples(query) return json.dumps({ "query": query, "count": len(results), "results": results }, indent=2) except Exception as e: logger.error(f"Error searching V UI examples: {e}") return json.dumps({"error": f"Error searching V UI examples: {str(e)}"}, indent=2) @mcp.tool def get_v_help() -> str: """ Get help and information about available V MCP server tools. Provides an overview of all available tools and how to use them effectively. Returns: Help information about available tools and usage examples """ return """ # V MCP Server Help The V MCP Server provides comprehensive access to V programming language resources. ## Available Tools ### 📚 Documentation Tools - **`get_v_documentation([section])`** - Get V documentation, optionally for a specific section - Example: `get_v_documentation()` or `get_v_documentation("Structs")` - **`search_v_docs(query)`** - Search through V documentation - Example: `search_v_docs("arrays")` ### 💡 Code Examples - **`list_v_examples()`** - List all available V code examples - **`get_v_example(name)`** - Get complete source code for a specific example - Example: `get_v_example("fibonacci")` - **`search_v_examples(query)`** - Search through example code - Example: `search_v_examples("http")` ### 🔧 Standard Library - **`list_v_stdlib_modules()`** - List all V standard library modules - **`get_v_module_info(module_name)`** - Get detailed info about a specific module - Example: `get_v_module_info("os")` ### 🎨 V UI Examples - **`list_v_ui_examples()`** - List all available V UI code examples - **`get_v_ui_example(name)`** - Get complete source code for a specific V UI example - Example: `get_v_ui_example("users")` - **`search_v_ui_examples(query)`** - Search through V UI example code - Example: `search_v_ui_examples("button")` ### 🎯 Language Reference - **`explain_v_syntax(feature)`** - Explain V language features - Available features: variables, arrays, structs, functions, control_flow, modules, error_handling, concurrency - Example: `explain_v_syntax("structs")` - **`get_v_quick_reference()`** - Get quick V syntax reference ### ⚙️ Configuration & Cache - **`get_v_config()`** - Show current server configuration and cache statistics - **`clear_v_cache()`** - Clear cached content for fresh results ### 🆘 Help & Discovery - **`get_v_help()`** - Show this help information ## Usage Tips 1. **Start with the basics**: Use `get_v_quick_reference()` to learn essential syntax 2. **Explore examples**: Use `list_v_examples()` to see practical code 3. **Search documentation**: Use `search_v_docs()` for specific topics 4. **Learn features**: Use `explain_v_syntax()` for detailed explanations 5. **Browse stdlib**: Use `list_v_stdlib_modules()` to explore available modules 6. **Check configuration**: Use `get_v_config()` to verify server settings 7. **Clear cache when needed**: Use `clear_v_cache()` after V repository updates ## Common Issues - **Empty search results**: Try more specific search terms (minimum 2 characters) - **Example not found**: Use `list_v_examples()` to see available examples - **Unknown feature**: Use `explain_v_syntax("")` to see available features """ if __name__ == "__main__": # Run the MCP server try: logger.info("Starting V MCP Server...") mcp.run() except Exception as e: logger.error(f"Failed to start MCP server: {e}") raise