Commit ab4d840
Changed files (3)
cmd
mcp-semantic
cmd/mcp-semantic/DESIGN.md
@@ -0,0 +1,1073 @@
+# Semantic MCP Server - Comprehensive Design Document
+
+## 1. Executive Summary
+
+The **Semantic MCP Server** provides intelligent, symbol-aware code operations that go beyond text manipulation to understand code structure, relationships, and semantics. Inspired by [Serena](https://github.com/oraios/serena), this server enables AI assistants to perform precise code editing, analysis, and refactoring at the semantic level.
+
+### Key Value Propositions
+- **Symbol-first operations**: Edit functions, classes, and variables as semantic units
+- **Cross-language consistency**: Unified interface for Go, Rust, Python, TypeScript, Java, C#
+- **Relationship awareness**: Understand how code symbols interact and depend on each other
+- **Safe refactoring**: Precise edits with automatic context preservation
+- **AI-optimized**: Designed specifically for LLM workflows and code understanding
+
+## 2. Architecture Overview
+
+### 2.1 Core Components
+
+```
+SemanticServer
+├── LanguageServerManager # LSP client pool for different languages
+├── SymbolManager # Symbol discovery, caching, and operations
+├── ProjectManager # Project context and boundary management
+├── ToolRegistry # 20+ semantic tools for code operations
+└── IntegrationLayer # Connects to existing MCP ecosystem
+```
+
+### 2.2 Technology Stack
+
+**Language Server Protocol (LSP) Foundation:**
+- **Primary approach**: Leverage existing language servers (gopls, rust-analyzer, pylsp, etc.)
+- **Protocol**: JSON-RPC communication with language servers
+- **Synchronous wrapper**: Simplified async handling for tool reliability
+
+**Supporting Technologies:**
+- **Tree-sitter**: Fallback parsing for languages without LSP support
+- **File watching**: Monitor project changes for cache invalidation
+- **Symbol caching**: In-memory and persistent symbol information
+- **Project indexing**: Background analysis for large codebases
+
+### 2.3 Integration Architecture
+
+```mermaid
+graph TB
+ Claude[Claude Code] --> MCP[Semantic MCP Server]
+ MCP --> LSM[Language Server Manager]
+ MCP --> SM[Symbol Manager]
+ MCP --> PM[Project Manager]
+
+ LSM --> gopls[gopls - Go]
+ LSM --> rust[rust-analyzer]
+ LSM --> pylsp[Python LSP]
+ LSM --> tsserver[TypeScript Server]
+
+ SM --> Cache[Symbol Cache]
+ SM --> Index[Project Index]
+
+ MCP --> Git[Git MCP Server]
+ MCP --> FS[Filesystem MCP Server]
+ MCP --> Mem[Memory MCP Server]
+```
+
+## 3. Tool Specification
+
+### 3.1 Symbol Discovery Tools
+
+#### `semantic_find_symbol`
+**Purpose**: Find symbols by name, type, or pattern across the project
+
+**Parameters:**
+```json
+{
+ "name": "UserService.authenticate", // Symbol path or pattern
+ "kind": "method", // function, class, variable, etc.
+ "scope": "project", // project, file, directory
+ "language": "go", // Optional language filter
+ "include_children": false, // Include child symbols
+ "max_results": 50 // Limit results
+}
+```
+
+**Response:**
+```json
+{
+ "symbols": [
+ {
+ "name": "authenticate",
+ "full_path": "UserService.authenticate",
+ "kind": "method",
+ "file_path": "src/services/user.go",
+ "location": {"line": 45, "column": 6},
+ "signature": "func (u *UserService) authenticate(email, password string) (*User, error)",
+ "visibility": "public",
+ "language": "go"
+ }
+ ],
+ "total_found": 1
+}
+```
+
+#### `semantic_get_overview`
+**Purpose**: Get high-level symbol overview of files or directories
+
+**Parameters:**
+```json
+{
+ "path": "src/services", // File or directory path
+ "depth": 2, // How deep to analyze
+ "include_kinds": ["class", "function"], // Filter symbol types
+ "exclude_private": true // Skip private symbols
+}
+```
+
+### 3.2 Symbol Analysis Tools
+
+#### `semantic_get_references`
+**Purpose**: Find all places where a symbol is used
+
+**Parameters:**
+```json
+{
+ "symbol": "UserService.authenticate", // Target symbol
+ "include_definitions": false, // Include definition location
+ "context_lines": 3, // Lines of context around usage
+ "filter_by_kind": ["call", "import"] // Type of references
+}
+```
+
+#### `semantic_get_definition`
+**Purpose**: Get detailed information about a symbol's definition
+
+**Parameters:**
+```json
+{
+ "symbol": "UserService.authenticate", // Target symbol
+ "include_signature": true, // Include full signature
+ "include_documentation": true, // Include comments/docs
+ "include_dependencies": true // Include what this symbol uses
+}
+```
+
+#### `semantic_get_call_hierarchy`
+**Purpose**: Understand calling relationships (what calls this, what this calls)
+
+**Parameters:**
+```json
+{
+ "symbol": "UserService.authenticate", // Target symbol
+ "direction": "both", // "incoming", "outgoing", "both"
+ "max_depth": 3, // How many levels deep
+ "include_external": false // Include calls to external packages
+}
+```
+
+### 3.3 Symbol Editing Tools
+
+#### `semantic_replace_symbol`
+**Purpose**: Replace a symbol's implementation while preserving context
+
+**Parameters:**
+```json
+{
+ "symbol": "UserService.authenticate", // Target symbol to replace
+ "new_code": "func (u *UserService) authenticate(email, password string) (*User, error) {\n // New implementation\n}",
+ "preserve_signature": true, // Keep existing signature
+ "preserve_comments": true, // Keep existing documentation
+ "dry_run": false // Preview changes without applying
+}
+```
+
+#### `semantic_insert_after_symbol`
+**Purpose**: Insert new code after a specific symbol
+
+**Parameters:**
+```json
+{
+ "target_symbol": "UserService.authenticate", // Reference point
+ "new_code": "func (u *UserService) logout() error {\n // Implementation\n}",
+ "auto_indent": true, // Match indentation
+ "add_spacing": true // Add appropriate spacing
+}
+```
+
+#### `semantic_rename_symbol`
+**Purpose**: Rename a symbol across the entire project
+
+**Parameters:**
+```json
+{
+ "old_name": "UserService.authenticate", // Current symbol name
+ "new_name": "UserService.login", // New symbol name
+ "scope": "project", // "file", "package", "project"
+ "preview_changes": true, // Show what will be changed
+ "include_comments": true // Update references in comments
+}
+```
+
+### 3.4 Project Analysis Tools
+
+#### `semantic_analyze_dependencies`
+**Purpose**: Analyze symbol dependencies and relationships
+
+**Parameters:**
+```json
+{
+ "scope": "src/services", // Analysis scope
+ "include_external": false, // Include external dependencies
+ "group_by": "package", // "file", "package", "kind"
+ "show_unused": true // Highlight unused symbols
+}
+```
+
+#### `semantic_get_impact_analysis`
+**Purpose**: Analyze what would be affected by changing a symbol
+
+**Parameters:**
+```json
+{
+ "symbol": "UserService.authenticate", // Symbol to analyze
+ "change_type": "signature", // "delete", "rename", "signature"
+ "include_tests": true, // Include test file impacts
+ "include_docs": true // Include documentation impacts
+}
+```
+
+## 4. Implementation Details
+
+### 4.1 Language Server Integration
+
+**Supported Languages & Servers:**
+```go
+type LanguageServerConfig struct {
+ Language string `json:"language"`
+ ServerCmd string `json:"server_cmd"`
+ Args []string `json:"args"`
+ FileExts []string `json:"file_extensions"`
+ Initialized bool `json:"initialized"`
+}
+
+var DefaultLanguageServers = map[string]LanguageServerConfig{
+ "go": {
+ Language: "go",
+ ServerCmd: "gopls",
+ Args: []string{"serve"},
+ FileExts: []string{".go"},
+ },
+ "rust": {
+ Language: "rust",
+ ServerCmd: "rust-analyzer",
+ Args: []string{},
+ FileExts: []string{".rs"},
+ },
+ "ruby": {
+ Language: "ruby",
+ ServerCmd: "solargraph",
+ Args: []string{"stdio"},
+ FileExts: []string{".rb", ".rbw", ".rake", ".gemspec"},
+ },
+ "python": {
+ Language: "python",
+ ServerCmd: "pylsp",
+ Args: []string{},
+ FileExts: []string{".py"},
+ },
+ "typescript": {
+ Language: "typescript",
+ ServerCmd: "typescript-language-server",
+ Args: []string{"--stdio"},
+ FileExts: []string{".ts", ".tsx", ".js", ".jsx"},
+ },
+ "html": {
+ Language: "html",
+ ServerCmd: "vscode-html-language-server",
+ Args: []string{"--stdio"},
+ FileExts: []string{".html", ".htm", ".xhtml"},
+ },
+ "css": {
+ Language: "css",
+ ServerCmd: "vscode-css-language-server",
+ Args: []string{"--stdio"},
+ FileExts: []string{".css", ".scss", ".sass", ".less"},
+ },
+ "java": {
+ Language: "java",
+ ServerCmd: "jdtls",
+ Args: []string{},
+ FileExts: []string{".java"},
+ },
+ "csharp": {
+ Language: "csharp",
+ ServerCmd: "omnisharp",
+ Args: []string{"--stdio"},
+ FileExts: []string{".cs"},
+ },
+}
+```
+
+**LSP Communication Pattern:**
+```go
+type LSPClient struct {
+ cmd *exec.Cmd
+ stdin io.WriteCloser
+ stdout io.ReadCloser
+ stderr io.ReadCloser
+ requestID int
+ responses map[int]chan LSPResponse
+ mu sync.RWMutex
+}
+
+func (c *LSPClient) SendRequest(method string, params interface{}) (*LSPResponse, error) {
+ c.mu.Lock()
+ requestID := c.requestID
+ c.requestID++
+ c.mu.Unlock()
+
+ request := LSPRequest{
+ JSONRPC: "2.0",
+ ID: requestID,
+ Method: method,
+ Params: params,
+ }
+
+ // Send request and wait for response
+ return c.sendAndWait(request)
+}
+```
+
+### 4.2 Symbol Management
+
+**Symbol Representation:**
+```go
+type Symbol struct {
+ Name string `json:"name"`
+ FullPath string `json:"full_path"`
+ Kind SymbolKind `json:"kind"`
+ Location SourceLocation `json:"location"`
+ Signature string `json:"signature,omitempty"`
+ Documentation string `json:"documentation,omitempty"`
+ Visibility string `json:"visibility"`
+ Language string `json:"language"`
+ Children []Symbol `json:"children,omitempty"`
+ References []SourceLocation `json:"references,omitempty"`
+ Dependencies []string `json:"dependencies,omitempty"`
+}
+
+type SymbolKind string
+const (
+ SymbolKindFile SymbolKind = "file"
+ SymbolKindModule SymbolKind = "module"
+ SymbolKindNamespace SymbolKind = "namespace"
+ SymbolKindPackage SymbolKind = "package"
+ SymbolKindClass SymbolKind = "class"
+ SymbolKindMethod SymbolKind = "method"
+ SymbolKindProperty SymbolKind = "property"
+ SymbolKindField SymbolKind = "field"
+ SymbolKindConstructor SymbolKind = "constructor"
+ SymbolKindEnum SymbolKind = "enum"
+ SymbolKindInterface SymbolKind = "interface"
+ SymbolKindFunction SymbolKind = "function"
+ SymbolKindVariable SymbolKind = "variable"
+ SymbolKindConstant SymbolKind = "constant"
+ SymbolKindString SymbolKind = "string"
+ SymbolKindNumber SymbolKind = "number"
+ SymbolKindBoolean SymbolKind = "boolean"
+ SymbolKindArray SymbolKind = "array"
+ SymbolKindObject SymbolKind = "object"
+ SymbolKindKey SymbolKind = "key"
+ SymbolKindNull SymbolKind = "null"
+ SymbolKindEnumMember SymbolKind = "enum_member"
+ SymbolKindStruct SymbolKind = "struct"
+ SymbolKindEvent SymbolKind = "event"
+ SymbolKindOperator SymbolKind = "operator"
+ SymbolKindTypeParameter SymbolKind = "type_parameter"
+)
+
+type SourceLocation struct {
+ FilePath string `json:"file_path"`
+ Line int `json:"line"`
+ Column int `json:"column"`
+ EndLine int `json:"end_line,omitempty"`
+ EndColumn int `json:"end_column,omitempty"`
+}
+```
+
+**Symbol Cache Management:**
+```go
+type SymbolCache struct {
+ symbols map[string][]Symbol // file_path -> symbols
+ references map[string][]Reference // symbol_path -> references
+ index map[string][]string // name -> file_paths
+ lastUpdate map[string]time.Time // file_path -> last_modified
+ mu sync.RWMutex
+}
+
+func (c *SymbolCache) InvalidateFile(filePath string) {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+
+ // Remove symbols for this file
+ delete(c.symbols, filePath)
+ delete(c.lastUpdate, filePath)
+
+ // Update index
+ c.rebuildIndex()
+}
+
+func (c *SymbolCache) FindSymbolsByName(name string) []Symbol {
+ c.mu.RLock()
+ defer c.mu.RUnlock()
+
+ var results []Symbol
+ if filePaths, exists := c.index[name]; exists {
+ for _, filePath := range filePaths {
+ if symbols, exists := c.symbols[filePath]; exists {
+ for _, symbol := range symbols {
+ if symbol.Name == name || strings.Contains(symbol.FullPath, name) {
+ results = append(results, symbol)
+ }
+ }
+ }
+ }
+ }
+ return results
+}
+```
+
+### 4.3 Project Management
+
+**Project Context:**
+```go
+type ProjectManager struct {
+ rootPath string
+ gitignoreRules []string
+ languageFiles map[string][]string // language -> file_paths
+ projectConfig *ProjectConfig
+ watcher *fsnotify.Watcher
+ mu sync.RWMutex
+}
+
+type ProjectConfig struct {
+ Name string `json:"name"`
+ RootPath string `json:"root_path"`
+ Languages []string `json:"languages"`
+ ExcludePatterns []string `json:"exclude_patterns"`
+ IncludePatterns []string `json:"include_patterns"`
+ CustomSettings map[string]string `json:"custom_settings"`
+}
+
+func (pm *ProjectManager) DiscoverProject(rootPath string) error {
+ // 1. Detect languages by file extensions
+ // 2. Load .gitignore and exclude patterns
+ // 3. Scan for language-specific config files
+ // 4. Initialize project boundaries
+ // 5. Start file system watcher
+}
+
+func (pm *ProjectManager) GetFilesByLanguage(language string) []string {
+ pm.mu.RLock()
+ defer pm.mu.RUnlock()
+ return pm.languageFiles[language]
+}
+
+func (pm *ProjectManager) IsFileInProject(filePath string) bool {
+ // Check if file is within project boundaries
+ // Apply gitignore and exclude patterns
+ // Validate file extension for supported languages
+}
+```
+
+### 4.4 Integration with Existing MCP Servers
+
+**Git Integration:**
+```go
+func (s *SemanticServer) handleSemanticCommitSymbols(req mcp.CallToolRequest) (mcp.CallToolResult, error) {
+ var args struct {
+ Symbols []string `json:"symbols"`
+ Message string `json:"message"`
+ }
+
+ // 1. Find all files containing the symbols
+ files := s.getFilesForSymbols(args.Symbols)
+
+ // 2. Call git MCP server to stage files
+ gitResult := s.callGitServer("git_add", map[string]interface{}{
+ "files": files,
+ })
+
+ // 3. Generate semantic commit message
+ semanticMessage := s.generateSemanticCommitMessage(args.Symbols, args.Message)
+
+ // 4. Call git MCP server to commit
+ return s.callGitServer("git_commit", map[string]interface{}{
+ "message": semanticMessage,
+ })
+}
+```
+
+**Memory Integration:**
+```go
+func (s *SemanticServer) handleStoreSymbolGraph(req mcp.CallToolRequest) (mcp.CallToolResult, error) {
+ // 1. Analyze symbol relationships in project
+ graph := s.buildSymbolDependencyGraph()
+
+ // 2. Convert to memory MCP format
+ entities := s.convertSymbolsToEntities(graph.Symbols)
+ relations := s.convertDependenciesToRelations(graph.Dependencies)
+
+ // 3. Store in memory MCP server
+ memoryResult := s.callMemoryServer("create_entities", map[string]interface{}{
+ "entities": entities,
+ })
+
+ return s.callMemoryServer("create_relations", map[string]interface{}{
+ "relations": relations,
+ })
+}
+```
+
+**Filesystem Integration:**
+```go
+func (s *SemanticServer) handleSemanticReadFile(req mcp.CallToolRequest) (mcp.CallToolResult, error) {
+ var args struct {
+ FilePath string `json:"file_path"`
+ Symbols []string `json:"symbols,omitempty"`
+ }
+
+ if len(args.Symbols) == 0 {
+ // Fallback to regular file read
+ return s.callFilesystemServer("read_file", map[string]interface{}{
+ "file_path": args.FilePath,
+ })
+ }
+
+ // 1. Get symbols from file
+ symbols := s.getSymbolsFromFile(args.FilePath, args.Symbols)
+
+ // 2. Extract code for specified symbols only
+ codeSegments := s.extractSymbolCode(args.FilePath, symbols)
+
+ // 3. Return structured response
+ return mcp.CallToolResult{
+ Content: []mcp.Content{
+ mcp.TextContent{
+ Type: "text",
+ Text: s.formatSymbolCode(codeSegments),
+ },
+ },
+ }, nil
+}
+```
+
+## 5. Performance Considerations
+
+### 5.1 Language Server Management
+
+**Connection Pooling:**
+```go
+type LanguageServerPool struct {
+ servers map[string]*LSPClient
+ maxIdle time.Duration
+ mu sync.RWMutex
+}
+
+func (p *LanguageServerPool) GetServer(language string) (*LSPClient, error) {
+ p.mu.RLock()
+ if server, exists := p.servers[language]; exists && server.IsHealthy() {
+ p.mu.RUnlock()
+ return server, nil
+ }
+ p.mu.RUnlock()
+
+ // Start new language server
+ return p.startLanguageServer(language)
+}
+```
+
+**Lazy Initialization:**
+- Language servers started on-demand when first tool call requires them
+- Automatic shutdown after idle timeout to conserve resources
+- Health checking to restart failed servers
+
+**Request Batching:**
+```go
+func (s *SemanticServer) batchSymbolRequests(requests []SymbolRequest) []Symbol {
+ // Group requests by language/file for efficient LSP calls
+ batches := s.groupRequestsByLanguage(requests)
+
+ var results []Symbol
+ for language, batch := range batches {
+ languageResults := s.processLanguageBatch(language, batch)
+ results = append(results, languageResults...)
+ }
+
+ return results
+}
+```
+
+### 5.2 Caching Strategy
+
+**Multi-Level Caching:**
+1. **In-Memory Cache**: Hot symbols and recent operations
+2. **File-based Cache**: Persistent symbol index across sessions
+3. **Incremental Updates**: Only re-analyze changed files
+
+**Cache Invalidation:**
+```go
+func (s *SemanticServer) onFileChanged(filePath string) {
+ // 1. Invalidate symbol cache for file
+ s.symbolCache.InvalidateFile(filePath)
+
+ // 2. Invalidate dependent files (imports, etc.)
+ dependentFiles := s.getDependentFiles(filePath)
+ for _, depFile := range dependentFiles {
+ s.symbolCache.InvalidateFile(depFile)
+ }
+
+ // 3. Trigger background re-analysis
+ go s.reanalyzeFile(filePath)
+}
+```
+
+### 5.3 Scalability Limits
+
+**Resource Limits:**
+- **Max concurrent language servers**: 5
+- **Symbol cache size**: 50MB per project
+- **File watch limit**: 10,000 files
+- **Symbol query timeout**: 30 seconds
+
+**Large Project Optimization:**
+```go
+func (s *SemanticServer) optimizeForLargeProject(projectSize int) {
+ if projectSize > 100000 { // 100k+ files
+ // Enable aggressive caching
+ s.symbolCache.SetMaxSize(200 * 1024 * 1024) // 200MB
+
+ // Reduce file watching scope
+ s.projectManager.SetWatchPatterns([]string{
+ "**/*.go", "**/*.rs", "**/*.py", "**/*.ts",
+ })
+
+ // Enable background indexing
+ s.enableBackgroundIndexing()
+ }
+}
+```
+
+## 6. Error Handling & Reliability
+
+### 6.1 Language Server Failures
+
+**Graceful Degradation:**
+```go
+func (s *SemanticServer) handleSymbolRequest(req SymbolRequest) (*Symbol, error) {
+ // Try LSP first
+ if server, err := s.getLanguageServer(req.Language); err == nil {
+ if symbol, err := server.GetSymbol(req); err == nil {
+ return symbol, nil
+ }
+ }
+
+ // Fallback to tree-sitter parsing
+ if parser, err := s.getTreeSitterParser(req.Language); err == nil {
+ return parser.ParseSymbol(req)
+ }
+
+ // Final fallback to regex-based parsing
+ return s.parseSymbolWithRegex(req)
+}
+```
+
+**Health Monitoring:**
+```go
+func (s *SemanticServer) monitorLanguageServerHealth() {
+ ticker := time.NewTicker(30 * time.Second)
+ defer ticker.Stop()
+
+ for range ticker.C {
+ for language, server := range s.languageServers {
+ if !server.IsHealthy() {
+ log.Printf("Language server %s is unhealthy, restarting", language)
+ s.restartLanguageServer(language)
+ }
+ }
+ }
+}
+```
+
+### 6.2 File System Issues
+
+**Concurrent Access:**
+```go
+func (s *SemanticServer) safeFileOperation(filePath string, operation func() error) error {
+ // File-level locking to prevent concurrent modifications
+ lock := s.getFileLock(filePath)
+ lock.Lock()
+ defer lock.Unlock()
+
+ // Verify file still exists and is accessible
+ if !s.isFileAccessible(filePath) {
+ return fmt.Errorf("file not accessible: %s", filePath)
+ }
+
+ return operation()
+}
+```
+
+**Data Integrity:**
+```go
+func (s *SemanticServer) validateSymbolData(symbol *Symbol) error {
+ if symbol.Name == "" {
+ return errors.New("symbol name is required")
+ }
+
+ if symbol.Location.Line < 1 {
+ return errors.New("invalid symbol location")
+ }
+
+ if !s.projectManager.IsFileInProject(symbol.Location.FilePath) {
+ return errors.New("symbol file is outside project boundaries")
+ }
+
+ return nil
+}
+```
+
+## 7. Configuration & Deployment
+
+### 7.1 Server Configuration
+
+**Configuration File** (`semantic-config.json`):
+```json
+{
+ "project": {
+ "auto_discover": true,
+ "max_project_size": 100000,
+ "exclude_patterns": [
+ "**/node_modules/**",
+ "**/vendor/**",
+ "**/.git/**",
+ "**/target/**",
+ "**/dist/**"
+ ]
+ },
+ "language_servers": {
+ "go": {
+ "enabled": true,
+ "server_cmd": "gopls",
+ "args": ["serve"],
+ "timeout": 30
+ },
+ "rust": {
+ "enabled": true,
+ "server_cmd": "rust-analyzer",
+ "timeout": 60
+ }
+ },
+ "cache": {
+ "max_memory_mb": 100,
+ "persist_to_disk": true,
+ "cache_dir": "$HOME/.mcp/semantic-cache"
+ },
+ "performance": {
+ "max_concurrent_servers": 5,
+ "symbol_query_timeout": 30,
+ "file_watch_enabled": true
+ }
+}
+```
+
+**Command Line Flags:**
+```bash
+mcp-semantic \
+ --project-root=/path/to/project \
+ --config=/path/to/semantic-config.json \
+ --cache-dir=/path/to/cache \
+ --log-level=info \
+ --enable-dashboard \
+ --dashboard-port=8080
+```
+
+### 7.2 Dependencies
+
+**Language Server Requirements:**
+```bash
+# Go
+go install golang.org/x/tools/gopls@latest
+
+# Rust
+rustup component add rust-analyzer
+
+# Ruby
+gem install solargraph
+
+# Python
+pip install python-lsp-server
+
+# JavaScript/TypeScript
+npm install -g typescript-language-server typescript
+
+# HTML
+npm install -g vscode-langservers-extracted
+
+# CSS
+npm install -g vscode-langservers-extracted
+
+# Java (Eclipse JDT Language Server)
+# Download from: https://download.eclipse.org/jdtls/snapshots/
+
+# C# (OmniSharp)
+# Download from: https://github.com/OmniSharp/omnisharp-roslyn
+```
+
+**Optional Dependencies:**
+```bash
+# Tree-sitter parsers for fallback parsing
+npm install tree-sitter tree-sitter-go tree-sitter-rust tree-sitter-python
+
+# File watching
+go get github.com/fsnotify/fsnotify
+
+# Git integration
+go get github.com/go-git/go-git/v5
+```
+
+### 7.3 Integration Setup
+
+**Claude Code Configuration:**
+```json
+{
+ "mcpServers": {
+ "semantic": {
+ "command": "/usr/local/bin/mcp-semantic",
+ "args": [
+ "--project-root", ".",
+ "--config", "~/.config/semantic-mcp.json"
+ ]
+ }
+ }
+}
+```
+
+**Goose Integration:**
+```yaml
+# ~/.config/goose/contexts/semantic-dev.yaml
+GOOSE_MODEL: qwen2.5
+GOOSE_PROVIDER: ollama
+mcp_servers:
+ semantic:
+ command: /usr/local/bin/mcp-semantic
+ args: ["--project-root", "."]
+ git:
+ command: /usr/local/bin/mcp-git
+ args: ["--repository", "."]
+ filesystem:
+ command: /usr/local/bin/mcp-filesystem
+ args: ["--allowed-directory", "."]
+```
+
+## 8. Testing Strategy
+
+### 8.1 Unit Tests
+
+**Symbol Management Tests:**
+```go
+func TestSymbolCache_FindByName(t *testing.T) {
+ cache := NewSymbolCache()
+
+ // Add test symbols
+ symbols := []Symbol{
+ {Name: "UserService", FullPath: "services.UserService", Kind: SymbolKindClass},
+ {Name: "authenticate", FullPath: "services.UserService.authenticate", Kind: SymbolKindMethod},
+ }
+ cache.AddSymbols("test.go", symbols)
+
+ // Test search
+ results := cache.FindSymbolsByName("authenticate")
+ assert.Len(t, results, 1)
+ assert.Equal(t, "authenticate", results[0].Name)
+}
+```
+
+**Language Server Integration Tests:**
+```go
+func TestLSPClient_GetSymbols(t *testing.T) {
+ if !hasLanguageServer("go") {
+ t.Skip("gopls not available")
+ }
+
+ client, err := NewLSPClient("go")
+ require.NoError(t, err)
+ defer client.Shutdown()
+
+ symbols, err := client.GetDocumentSymbols("testdata/sample.go")
+ require.NoError(t, err)
+ assert.Greater(t, len(symbols), 0)
+}
+```
+
+### 8.2 Integration Tests
+
+**End-to-End Workflow Tests:**
+```go
+func TestSemanticWorkflow_FindAndEdit(t *testing.T) {
+ server := setupTestServer(t)
+ defer server.Shutdown()
+
+ // 1. Find symbol
+ findReq := mcp.CallToolRequest{
+ Name: "semantic_find_symbol",
+ Arguments: map[string]interface{}{
+ "name": "UserService.authenticate",
+ "kind": "method",
+ },
+ }
+
+ findResult, err := server.CallTool(findReq)
+ require.NoError(t, err)
+
+ // 2. Edit symbol
+ editReq := mcp.CallToolRequest{
+ Name: "semantic_replace_symbol",
+ Arguments: map[string]interface{}{
+ "symbol": "UserService.authenticate",
+ "new_code": "func (u *UserService) authenticate(email, password string) (*User, error) {\n return nil, nil\n}",
+ },
+ }
+
+ editResult, err := server.CallTool(editReq)
+ require.NoError(t, err)
+
+ // 3. Verify edit was applied
+ // ... verification logic
+}
+```
+
+### 8.3 Performance Tests
+
+**Benchmark Large Projects:**
+```go
+func BenchmarkSymbolSearch_LargeProject(b *testing.B) {
+ server := setupLargeProjectServer(b) // 10k+ files
+ defer server.Shutdown()
+
+ req := mcp.CallToolRequest{
+ Name: "semantic_find_symbol",
+ Arguments: map[string]interface{}{
+ "name": "main",
+ "scope": "project",
+ },
+ }
+
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _, err := server.CallTool(req)
+ require.NoError(b, err)
+ }
+}
+```
+
+**Memory Usage Tests:**
+```go
+func TestMemoryUsage_SymbolCache(t *testing.T) {
+ var m1, m2 runtime.MemStats
+ runtime.GC()
+ runtime.ReadMemStats(&m1)
+
+ // Load large project
+ server := setupLargeProjectServer(t)
+ defer server.Shutdown()
+
+ runtime.GC()
+ runtime.ReadMemStats(&m2)
+
+ memoryUsed := m2.Alloc - m1.Alloc
+ assert.Less(t, memoryUsed, uint64(100*1024*1024)) // <100MB
+}
+```
+
+## 9. Future Enhancements
+
+### 9.1 Advanced Features
+
+**AI-Powered Code Analysis:**
+```go
+// semantic_suggest_refactoring
+func (s *SemanticServer) suggestRefactoring(symbol *Symbol) []RefactoringSuggestion {
+ // Analyze code patterns, complexity, dependencies
+ // Suggest extract method, rename, move class, etc.
+}
+
+// semantic_generate_tests
+func (s *SemanticServer) generateTests(symbol *Symbol) string {
+ // Generate unit tests based on symbol signature and dependencies
+}
+
+// semantic_optimize_imports
+func (s *SemanticServer) optimizeImports(filePath string) []ImportChange {
+ // Remove unused imports, organize, suggest better imports
+}
+```
+
+**Cross-Project Analysis:**
+```go
+// semantic_find_duplicate_code
+func (s *SemanticServer) findDuplicateCode(threshold float64) []DuplicateMatch {
+ // Find similar code patterns across projects
+}
+
+// semantic_track_symbol_evolution
+func (s *SemanticServer) trackSymbolEvolution(symbol string) []SymbolChange {
+ // Track how symbols change over time via git history
+}
+```
+
+### 9.2 Language Extensions
+
+**Additional Language Support:**
+- **PHP**: PHP Language Server
+- **Ruby**: Solargraph
+- **C/C++**: clangd
+- **Swift**: sourcekit-lsp
+- **Kotlin**: Kotlin Language Server
+
+**Domain-Specific Languages:**
+- **SQL**: SQL language server for database schema analysis
+- **YAML/JSON**: Schema-aware editing for configuration files
+- **Markdown**: Documentation structure analysis
+
+### 9.3 Integration Enhancements
+
+**IDE Integration:**
+```go
+// Export LSP proxy for IDEs
+func (s *SemanticServer) ExportLSPProxy() *LSPProxy {
+ // Allow IDEs to use semantic server as LSP backend
+}
+```
+
+**CI/CD Integration:**
+```go
+// semantic_validate_changes
+func (s *SemanticServer) validateChanges(pullRequest *PullRequest) []ValidationResult {
+ // Analyze PR for breaking changes, test coverage, etc.
+}
+```
+
+**Documentation Integration:**
+```go
+// semantic_generate_docs
+func (s *SemanticServer) generateDocumentation(scope string) string {
+ // Generate API documentation from symbols
+}
+```
+
+## 10. Conclusion
+
+The Semantic MCP Server represents a significant advancement in AI-assisted code editing, moving beyond text manipulation to true semantic understanding. By leveraging Language Server Protocol and providing a rich set of symbol-aware tools, it enables AI assistants to perform precise, safe, and intelligent code operations.
+
+**Key Benefits:**
+- **Precision**: Symbol-level operations instead of error-prone text manipulation
+- **Safety**: Context-aware editing with automatic formatting preservation
+- **Intelligence**: Understanding of code relationships and dependencies
+- **Consistency**: Unified interface across multiple programming languages
+- **Integration**: Seamless connection with existing MCP ecosystem
+
+**Implementation Priority:**
+1. **Phase 1**: Core symbol discovery and basic editing tools
+2. **Phase 2**: Advanced analysis tools (references, call hierarchy)
+3. **Phase 3**: Integration with existing MCP servers
+4. **Phase 4**: Performance optimization and caching
+5. **Phase 5**: Advanced features and additional language support
+
+This design provides a solid foundation for building a production-ready semantic code editing system that can significantly enhance AI-assisted software development workflows.
\ No newline at end of file
cmd/mcp-semantic/IMPLEMENTATION_PLAN.md
@@ -0,0 +1,335 @@
+# Semantic MCP Server - Implementation Plan
+
+## 🎯 Implementation Phases
+
+### Phase 1: Foundation & Core Discovery (Week 1-2)
+**Goal**: Basic symbol discovery and project setup
+
+**Deliverables:**
+- [ ] Basic project structure and MCP server framework
+- [ ] Language server integration for Go and Rust
+- [ ] Core symbol discovery tools
+- [ ] Basic caching mechanism
+- [ ] Integration tests
+
+**Tools to Implement:**
+- [ ] `semantic_find_symbol` - Find symbols by name/pattern
+- [ ] `semantic_get_overview` - Project structure overview
+- [ ] `semantic_get_definition` - Symbol details
+
+**Technical Tasks:**
+- [ ] Set up Language Server Protocol (LSP) client framework
+- [ ] Implement symbol representation and caching
+- [ ] Create project discovery and boundary management
+- [ ] Build basic MCP tool registry
+- [ ] Add integration test framework
+
+### Phase 2: Analysis & Relationships (Week 3-4)
+**Goal**: Symbol relationship analysis and cross-references
+
+**Deliverables:**
+- [ ] Reference analysis tools
+- [ ] Call hierarchy understanding
+- [ ] Dependency mapping
+- [ ] Performance optimization
+
+**Tools to Implement:**
+- [ ] `semantic_get_references` - Find symbol usage
+- [ ] `semantic_get_call_hierarchy` - Call relationships
+- [ ] `semantic_analyze_dependencies` - Project dependencies
+
+**Technical Tasks:**
+- [ ] Implement cross-reference analysis via LSP
+- [ ] Build symbol relationship graph
+- [ ] Add efficient symbol indexing
+- [ ] Optimize language server connection pooling
+
+### Phase 3: Semantic Editing (Week 5-6)
+**Goal**: Safe, context-aware code editing
+
+**Deliverables:**
+- [ ] Symbol replacement and insertion tools
+- [ ] Context preservation during edits
+- [ ] Validation and dry-run capabilities
+- [ ] Rollback mechanisms
+
+**Tools to Implement:**
+- [ ] `semantic_replace_symbol` - Replace symbol implementations
+- [ ] `semantic_insert_after_symbol` - Insert code after symbols
+- [ ] `semantic_rename_symbol` - Project-wide renaming
+
+**Technical Tasks:**
+- [ ] Implement precise symbol location tracking
+- [ ] Add automatic indentation and formatting preservation
+- [ ] Build edit validation and preview system
+- [ ] Create backup and rollback mechanisms
+
+### Phase 4: MCP Integration (Week 7-8)
+**Goal**: Seamless integration with existing MCP servers
+
+**Deliverables:**
+- [ ] Git MCP integration for semantic commits
+- [ ] Filesystem MCP integration for symbol-aware operations
+- [ ] Memory MCP integration for symbol graph storage
+- [ ] Cross-server workflow examples
+
+**Tools to Implement:**
+- [ ] `semantic_commit_symbols` - Git commits by symbols
+- [ ] `semantic_read_symbols` - Read specific symbols from files
+- [ ] `semantic_store_symbol_graph` - Save to memory server
+
+**Technical Tasks:**
+- [ ] Build MCP server communication layer
+- [ ] Implement symbol-to-file mapping
+- [ ] Create semantic commit message generation
+- [ ] Add cross-server workflow orchestration
+
+### Phase 5: Advanced Features (Week 9-10)
+**Goal**: Advanced analysis and optimization features
+
+**Deliverables:**
+- [ ] Impact analysis for safe refactoring
+- [ ] Multi-language support expansion
+- [ ] Performance monitoring and optimization
+- [ ] Production deployment readiness
+
+**Tools to Implement:**
+- [ ] `semantic_get_impact_analysis` - Change impact assessment
+- [ ] `semantic_suggest_refactoring` - AI-powered suggestions
+- [ ] `semantic_validate_changes` - Pre-commit validation
+
+**Technical Tasks:**
+- [ ] Add TypeScript and Python language server support
+- [ ] Implement impact analysis algorithms
+- [ ] Build performance monitoring dashboard
+- [ ] Create production deployment scripts
+
+## 🏗️ Technical Implementation Strategy
+
+### Core Architecture Components
+
+**1. Language Server Manager**
+```go
+// pkg/semantic/lsp_manager.go
+type LSPManager struct {
+ servers map[string]*LSPClient
+ configs map[string]LSPConfig
+ pool *sync.Pool
+ health *HealthChecker
+}
+
+func (m *LSPManager) GetClient(language string) (*LSPClient, error) {
+ // Connection pooling, health checking, lazy initialization
+}
+```
+
+**2. Symbol Manager**
+```go
+// pkg/semantic/symbol_manager.go
+type SymbolManager struct {
+ cache *SymbolCache
+ index *SymbolIndex
+ lspManager *LSPManager
+}
+
+func (m *SymbolManager) FindSymbols(query SymbolQuery) ([]Symbol, error) {
+ // Multi-level caching, LSP queries, result aggregation
+}
+```
+
+**3. Project Manager**
+```go
+// pkg/semantic/project_manager.go
+type ProjectManager struct {
+ rootPath string
+ boundaries *ProjectBoundaries
+ watcher *FileWatcher
+ languages *LanguageDetector
+}
+
+func (m *ProjectManager) DiscoverProject(rootPath string) (*Project, error) {
+ // Language detection, boundary setting, file watching
+}
+```
+
+### Development Workflow
+
+**1. Setup Development Environment**
+```bash
+# Install language servers
+go install golang.org/x/tools/gopls@latest
+rustup component add rust-analyzer
+
+# Set up test projects
+mkdir -p testdata/{go-project,rust-project,python-project}
+
+# Initialize integration test suite
+make setup-semantic-tests
+```
+
+**2. Iterative Development Process**
+- **Week 1**: Basic LSP integration + symbol discovery
+- **Week 2**: Caching + project management
+- **Week 3**: Reference analysis + call hierarchy
+- **Week 4**: Performance optimization
+- **Week 5**: Symbol editing + validation
+- **Week 6**: Context preservation + safety
+- **Week 7**: MCP integration layer
+- **Week 8**: Cross-server workflows
+- **Week 9**: Advanced analysis features
+- **Week 10**: Production readiness + deployment
+
+**3. Testing Strategy Per Phase**
+```bash
+# Phase 1: Basic functionality
+make test-semantic-discovery
+
+# Phase 2: Performance and relationships
+make test-semantic-analysis
+make benchmark-semantic-cache
+
+# Phase 3: Editing safety
+make test-semantic-editing
+make test-semantic-rollback
+
+# Phase 4: Integration
+make test-semantic-integration
+make test-mcp-workflows
+
+# Phase 5: Production
+make test-semantic-production
+make benchmark-semantic-large-projects
+```
+
+## 📊 Success Metrics
+
+### Performance Targets
+- **Startup Time**: <100ms (consistent with other MCP servers)
+- **Symbol Query**: <500ms for 10k+ file projects
+- **Memory Usage**: <100MB per project
+- **Language Server Health**: >99% uptime
+
+### Functionality Targets
+- **Language Support**: Go, Rust, Python, TypeScript minimum
+- **Symbol Accuracy**: >95% correct symbol identification
+- **Edit Safety**: Zero data loss with validation
+- **Integration**: Seamless with all existing MCP servers
+
+### User Experience Targets
+- **API Consistency**: Uniform tool interface across languages
+- **Error Handling**: Graceful degradation on LSP failures
+- **Documentation**: Complete API docs and examples
+- **Reliability**: Production-ready error handling
+
+## 🔧 Development Tools & Scripts
+
+**Build and Test Scripts:**
+```bash
+# Development shortcuts
+make semantic-dev # Development build with debug symbols
+make semantic-test # Run all semantic tests
+make semantic-bench # Performance benchmarks
+make semantic-lint # Code quality checks
+
+# Language server management
+make install-lsp-servers # Install all required language servers
+make test-lsp-health # Check language server availability
+make debug-lsp-protocol # Debug LSP communication
+
+# Integration testing
+make test-semantic-integration # Test with other MCP servers
+make test-semantic-e2e # End-to-end workflow tests
+```
+
+**Debugging and Monitoring:**
+```bash
+# Debug mode with detailed logging
+mcp-semantic --debug --log-level=trace --enable-dashboard
+
+# Performance monitoring
+mcp-semantic --enable-metrics --metrics-port=9090
+
+# LSP protocol debugging
+mcp-semantic --debug-lsp --lsp-log-dir=/tmp/lsp-logs
+```
+
+## 🚀 Deployment Strategy
+
+### Local Development
+```bash
+# Development build
+make semantic-dev
+
+# Local testing with Claude Code
+export CLAUDE_CONFIG=~/.config/claude/semantic-dev.json
+claude-code
+```
+
+### Production Deployment
+```bash
+# Production build with optimizations
+make semantic-release
+
+# System installation
+sudo make install-semantic
+
+# Configuration validation
+mcp-semantic --validate-config --config=production.json
+```
+
+### CI/CD Integration
+```yaml
+# .github/workflows/semantic-mcp.yml
+name: Semantic MCP Server
+on: [push, pull_request]
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - uses: actions/setup-go@v3
+ - name: Install Language Servers
+ run: make install-lsp-servers
+ - name: Run Tests
+ run: make test-semantic
+ - name: Performance Benchmarks
+ run: make benchmark-semantic
+```
+
+## 📋 Implementation Checklist
+
+### Phase 1: Foundation ✅
+- [ ] Project structure and basic MCP framework
+- [ ] LSP client implementation for Go and Rust
+- [ ] Basic symbol discovery tools
+- [ ] Core caching mechanism
+- [ ] Unit and integration tests
+
+### Phase 2: Analysis ⏳
+- [ ] Reference analysis via LSP
+- [ ] Call hierarchy tools
+- [ ] Symbol relationship mapping
+- [ ] Performance optimization
+
+### Phase 3: Editing 📅
+- [ ] Safe symbol replacement
+- [ ] Context-aware insertion
+- [ ] Project-wide renaming
+- [ ] Edit validation and rollback
+
+### Phase 4: Integration 📅
+- [ ] Git MCP integration
+- [ ] Filesystem MCP integration
+- [ ] Memory MCP integration
+- [ ] Cross-server workflows
+
+### Phase 5: Advanced 📅
+- [ ] Impact analysis
+- [ ] Multi-language expansion
+- [ ] Production monitoring
+- [ ] Deployment automation
+
+---
+
+**This implementation plan provides a structured approach to building a production-ready Semantic MCP Server that transforms how AI assistants work with code.**
\ No newline at end of file
cmd/mcp-semantic/README.md
@@ -0,0 +1,272 @@
+# Semantic MCP Server
+
+**Intelligent, symbol-aware code operations for AI assistants**
+
+The Semantic MCP Server provides AI assistants like Claude with the ability to understand and manipulate code at the semantic level - working with functions, classes, and variables as meaningful units rather than plain text.
+
+## 🎯 What This Enables
+
+**Instead of this** (text-based):
+```bash
+# Find a function by searching text
+filesystem_read_file("service.go") | grep "func authenticate"
+
+# Edit code by line numbers (fragile)
+edit_file --line=45 --text="new implementation"
+```
+
+**You get this** (semantic):
+```bash
+# Find symbols by meaning
+semantic_find_symbol --name="UserService.authenticate" --kind="method"
+
+# Edit code by semantic understanding
+semantic_replace_symbol --symbol="UserService.authenticate" --new_code="..."
+```
+
+## 🔧 Core Capabilities
+
+### Symbol Discovery
+- **`semantic_find_symbol`** - Find functions, classes, variables by name/pattern
+- **`semantic_get_overview`** - Get high-level code structure overview
+- **`semantic_analyze_dependencies`** - Understand symbol relationships
+
+### Code Analysis
+- **`semantic_get_references`** - Find all places a symbol is used
+- **`semantic_get_definition`** - Get detailed symbol information
+- **`semantic_get_call_hierarchy`** - Understand calling relationships
+
+### Semantic Editing
+- **`semantic_replace_symbol`** - Replace function/class implementations safely
+- **`semantic_insert_after_symbol`** - Add code after specific symbols
+- **`semantic_rename_symbol`** - Rename across entire project
+
+### Project Intelligence
+- **`semantic_get_impact_analysis`** - What breaks if I change this?
+- **`semantic_commit_symbols`** - Git commits by symbols changed
+- **`semantic_store_symbol_graph`** - Save symbol relationships to memory
+
+## 🏗️ Architecture
+
+**Language Server Foundation:**
+- Leverages existing language servers (gopls, rust-analyzer, solargraph, etc.)
+- Unified interface across **Go, Rust, Ruby, Python, JavaScript, TypeScript, HTML, CSS, Java, C#**
+- Fallback to tree-sitter parsing for unsupported languages
+
+**Integration with Existing MCP Servers:**
+- **Git**: Semantic commits, symbol-level diffs
+- **Filesystem**: Symbol-aware file operations
+- **Memory**: Store code relationships and project context
+
+## 🚀 Quick Start
+
+### Installation
+```bash
+# Build semantic server
+make semantic
+
+# Install to system
+sudo make install
+```
+
+### Configuration
+```json
+{
+ "mcpServers": {
+ "semantic": {
+ "command": "/usr/local/bin/mcp-semantic",
+ "args": ["--project-root", "."]
+ }
+ }
+}
+```
+
+### Language Server Dependencies
+```bash
+# Go
+go install golang.org/x/tools/gopls@latest
+
+# Rust
+rustup component add rust-analyzer
+
+# Ruby
+gem install solargraph
+
+# Python
+pip install python-lsp-server
+
+# JavaScript/TypeScript
+npm install -g typescript-language-server typescript
+
+# HTML/CSS
+npm install -g vscode-langservers-extracted
+```
+
+## 💡 Example Workflows
+
+### Intelligent Refactoring
+```bash
+# 1. Find all places that call a function
+semantic_get_references --symbol="utils.deprecated_helper"
+
+# 2. Understand what would break
+semantic_get_impact_analysis --symbol="utils.deprecated_helper" --change_type="delete"
+
+# 3. Safely rename across project
+semantic_rename_symbol --old_name="utils.deprecated_helper" --new_name="utils.new_helper"
+```
+
+### Code Understanding
+```bash
+# 1. Get project overview
+semantic_get_overview --path="src/services" --depth=2
+
+# 2. Drill into specific service
+semantic_find_symbol --name="UserService" --include_children=true
+
+# 3. Understand dependencies
+semantic_get_call_hierarchy --symbol="UserService.authenticate" --direction="both"
+```
+
+### Safe Code Editing
+```bash
+# 1. Find the exact function
+semantic_find_symbol --name="UserService.authenticate" --kind="method"
+
+# 2. Replace implementation with context preservation
+semantic_replace_symbol \
+ --symbol="UserService.authenticate" \
+ --new_code="func (u *UserService) authenticate(email, password string) (*User, error) { ... }" \
+ --preserve_signature=true
+```
+
+## 🎮 Integration Examples
+
+### Enhanced Git Workflow
+```bash
+# Commit by symbols changed instead of files
+semantic_commit_symbols \
+ --symbols=["UserService.authenticate", "Database.findUser"] \
+ --message="refactor user authentication"
+```
+
+### Intelligent File Operations
+```bash
+# Read only specific symbols from large files
+semantic_read_file \
+ --file_path="large_service.go" \
+ --symbols=["UserService.authenticate", "UserService.validate"]
+```
+
+### Memory Integration
+```bash
+# Store project structure for AI context
+semantic_store_symbol_graph --project="myapp"
+
+# Query relationships later
+memory_query --query="What functions call UserService.authenticate?"
+```
+
+## 📊 Performance & Scalability
+
+**Language Server Pool:**
+- Lazy initialization (servers started on-demand)
+- Connection pooling and health monitoring
+- Automatic restart on failures
+
+**Symbol Caching:**
+- In-memory cache for hot symbols
+- Persistent file-based cache across sessions
+- Incremental updates on file changes
+
+**Resource Limits:**
+- Max 5 concurrent language servers
+- 100MB symbol cache per project
+- 30-second query timeout
+
+## 🔧 Configuration Options
+
+**Project Settings:**
+```json
+{
+ "project": {
+ "auto_discover": true,
+ "max_project_size": 100000,
+ "exclude_patterns": ["**/node_modules/**", "**/vendor/**"]
+ },
+ "language_servers": {
+ "go": {"enabled": true, "timeout": 30},
+ "rust": {"enabled": true, "timeout": 60}
+ },
+ "cache": {
+ "max_memory_mb": 100,
+ "persist_to_disk": true
+ }
+}
+```
+
+**Command Line:**
+```bash
+mcp-semantic \
+ --project-root=/path/to/project \
+ --config=/path/to/config.json \
+ --cache-dir=/path/to/cache \
+ --enable-dashboard \
+ --dashboard-port=8080
+```
+
+## 🧪 Development Status
+
+**Implementation Phases:**
+
+- [ ] **Phase 1**: Core symbol discovery and basic editing tools
+- [ ] **Phase 2**: Advanced analysis tools (references, call hierarchy)
+- [ ] **Phase 3**: Integration with existing MCP servers
+- [ ] **Phase 4**: Performance optimization and caching
+- [ ] **Phase 5**: Advanced features and additional language support
+
+**Current Status:** 📋 **Design Complete** - Ready for implementation
+
+## 🤝 Contributing
+
+**Getting Started:**
+1. Read the [comprehensive design document](DESIGN.md)
+2. Set up development environment with language servers
+3. Run integration tests: `make test-semantic`
+4. Check performance benchmarks: `make benchmark-semantic`
+
+**Architecture Overview:**
+- **Core**: Language server management and symbol operations
+- **Tools**: 20+ semantic tools for code operations
+- **Cache**: Multi-level caching for performance
+- **Integration**: Connects with git, filesystem, memory MCP servers
+
+## 📚 Documentation
+
+- **[Design Document](DESIGN.md)** - Comprehensive technical specification
+- **[API Reference](API.md)** - Detailed tool documentation
+- **[Integration Guide](INTEGRATION.md)** - How to integrate with other MCP servers
+- **[Performance Guide](PERFORMANCE.md)** - Optimization and scaling strategies
+
+## 🔮 Future Vision
+
+**Advanced Features:**
+- AI-powered refactoring suggestions
+- Cross-project duplicate code detection
+- Automatic test generation from symbols
+- Documentation generation from code structure
+
+**Additional Languages:**
+- PHP, Ruby, C/C++, Swift, Kotlin support
+- Domain-specific languages (SQL, YAML, Markdown)
+- Custom language server integration
+
+**Ecosystem Integration:**
+- IDE plugins (VSCode, cursor, etc.)
+- CI/CD pipeline integration
+- Documentation generation tools
+- Code quality analysis
+
+---
+
+**The Semantic MCP Server transforms how AI assistants work with code - from text manipulation to true semantic understanding.**
\ No newline at end of file