Commit 77bd3b0
Changed files (15)
cmd/bash/DESIGN.md
@@ -1,504 +0,0 @@
-# Bash MCP Server Design
-
-## Overview
-
-The Bash MCP server provides AI coding agents with direct shell command execution capabilities through the Model Context Protocol. This server enables agents to perform any system operation that doesn't require sudo privileges, making it a powerful tool for development, automation, and system interaction.
-
-## Design Principles
-
-### 1. **Unrestricted Access**
-- Execute any shell command that doesn't require sudo
-- No command filtering or sandboxing (by design)
-- Full access to filesystem within user permissions
-- Complete environment variable access
-
-### 2. **Minimal Resource Usage**
-- Lazy loading of all components
-- No background processes or persistent state
-- Minimal memory footprint (<5MB)
-- Efficient command execution without overhead
-
-### 3. **MCP Protocol Compliance**
-- Standard JSON-RPC 2.0 over stdio
-- Proper tool definitions with JSON schemas
-- Resource discovery for system information
-- Clean error handling and responses
-
-### 4. **Performance First**
-- Fast startup (<2ms)
-- Streaming output support for long-running commands
-- Configurable timeouts
-- Asynchronous execution where beneficial
-
-## Architecture
-
-```
-AI Agent → JSON-RPC → Bash Server → Shell Execution → System
- ↓
- Environment Management
- ↓
- Output Processing
-```
-
-## Tool Specifications
-
-### Core Execution Tools
-
-#### `bash_exec`
-**Primary command execution tool**
-
-```json
-{
- "name": "bash_exec",
- "description": "Execute a shell command and return output",
- "inputSchema": {
- "type": "object",
- "properties": {
- "command": {
- "type": "string",
- "description": "Shell command to execute"
- },
- "working_dir": {
- "type": "string",
- "description": "Working directory for command execution (optional)"
- },
- "timeout": {
- "type": "number",
- "description": "Timeout in seconds (default: 30, max: 300)"
- },
- "capture_stderr": {
- "type": "boolean",
- "description": "Include stderr in output (default: true)"
- },
- "env": {
- "type": "object",
- "description": "Additional environment variables"
- }
- },
- "required": ["command"]
- }
-}
-```
-
-**Response Format:**
-```json
-{
- "stdout": "command output",
- "stderr": "error output",
- "exit_code": 0,
- "execution_time_ms": 150,
- "working_dir": "/current/directory",
- "command": "ls -la"
-}
-```
-
-#### `bash_exec_stream`
-**Streaming command execution for long-running processes**
-
-```json
-{
- "name": "bash_exec_stream",
- "description": "Execute command with real-time output streaming",
- "inputSchema": {
- "type": "object",
- "properties": {
- "command": {"type": "string"},
- "working_dir": {"type": "string"},
- "timeout": {"type": "number"},
- "buffer_size": {"type": "number", "description": "Stream buffer size in bytes"}
- },
- "required": ["command"]
- }
-}
-```
-
-### Documentation Tools
-
-#### `man_page`
-**Access system manual pages**
-
-```json
-{
- "name": "man_page",
- "description": "Get manual page for a command",
- "inputSchema": {
- "type": "object",
- "properties": {
- "command": {"type": "string", "description": "Command to get manual for"},
- "section": {"type": "string", "description": "Manual section (1-8)"}
- },
- "required": ["command"]
- }
-}
-```
-
-#### `which_command`
-**Locate command binaries**
-
-```json
-{
- "name": "which_command",
- "description": "Find the location of a command",
- "inputSchema": {
- "type": "object",
- "properties": {
- "command": {"type": "string"}
- },
- "required": ["command"]
- }
-}
-```
-
-#### `command_help`
-**Get command help information**
-
-```json
-{
- "name": "command_help",
- "description": "Get help text for a command (--help flag)",
- "inputSchema": {
- "type": "object",
- "properties": {
- "command": {"type": "string"}
- },
- "required": ["command"]
- }
-}
-```
-
-### Environment Management Tools
-
-#### `get_env`
-**Access environment variables**
-
-```json
-{
- "name": "get_env",
- "description": "Get environment variable value",
- "inputSchema": {
- "type": "object",
- "properties": {
- "variable": {"type": "string", "description": "Environment variable name"},
- "all": {"type": "boolean", "description": "Return all environment variables"}
- }
- }
-}
-```
-
-#### `get_working_dir`
-**Get current working directory**
-
-```json
-{
- "name": "get_working_dir",
- "description": "Get the current working directory",
- "inputSchema": {"type": "object"}
-}
-```
-
-#### `set_working_dir`
-**Change working directory for subsequent commands**
-
-```json
-{
- "name": "set_working_dir",
- "description": "Set working directory for future commands",
- "inputSchema": {
- "type": "object",
- "properties": {
- "directory": {"type": "string"}
- },
- "required": ["directory"]
- }
-}
-```
-
-### System Information Tools
-
-#### `system_info`
-**Get system information**
-
-```json
-{
- "name": "system_info",
- "description": "Get basic system information",
- "inputSchema": {"type": "object"}
-}
-```
-
-**Returns:**
-```json
-{
- "hostname": "server.local",
- "os": "Linux",
- "architecture": "x86_64",
- "kernel": "5.15.0",
- "shell": "/bin/bash",
- "user": "username",
- "home": "/home/username",
- "path": "/usr/bin:/bin:/usr/local/bin"
-}
-```
-
-#### `process_info`
-**Get information about running processes**
-
-```json
-{
- "name": "process_info",
- "description": "Get process information (ps command wrapper)",
- "inputSchema": {
- "type": "object",
- "properties": {
- "format": {"type": "string", "description": "ps format string (default: aux)"},
- "filter": {"type": "string", "description": "grep filter for processes"}
- }
- }
-}
-```
-
-## Resources
-
-### System Resources
-- **URI Format**: `bash://system/info`
-- **Description**: Live system information and environment state
-- **Content**: JSON with current system status
-
-### Command History Resource
-- **URI Format**: `bash://history/recent`
-- **Description**: Recent command execution history
-- **Content**: JSON array of recent commands with metadata
-
-### Environment Resource
-- **URI Format**: `bash://env/all`
-- **Description**: Complete environment variables
-- **Content**: JSON object with all environment variables
-
-## Implementation Details
-
-### Server Structure
-
-```go
-type BashServer struct {
- *mcp.Server
- workingDir string
- commandHistory []CommandRecord
- mu sync.RWMutex
-}
-
-type CommandRecord struct {
- Timestamp time.Time `json:"timestamp"`
- Command string `json:"command"`
- WorkingDir string `json:"working_dir"`
- ExitCode int `json:"exit_code"`
- Duration int64 `json:"duration_ms"`
- OutputSize int `json:"output_size_bytes"`
-}
-```
-
-### Command Execution
-
-```go
-type ExecutionOptions struct {
- Command string `json:"command"`
- WorkingDir string `json:"working_dir,omitempty"`
- Timeout int `json:"timeout,omitempty"`
- Env map[string]string `json:"env,omitempty"`
- CaptureStderr bool `json:"capture_stderr"`
-}
-
-type ExecutionResult struct {
- Stdout string `json:"stdout"`
- Stderr string `json:"stderr"`
- ExitCode int `json:"exit_code"`
- ExecutionTime int64 `json:"execution_time_ms"`
- WorkingDir string `json:"working_dir"`
- Command string `json:"command"`
-}
-```
-
-### Resource Management
-
-```go
-// Lazy loading - no persistent state
-func (bs *BashServer) registerResources() {
- // Register lightweight resource placeholders
- systemResource := mcp.Resource{
- URI: "bash://system/info",
- Name: "System Information",
- Description: "Live system information and environment state",
- MimeType: "application/json",
- }
- bs.Server.RegisterResourceWithDefinition(systemResource, bs.HandleSystemResource)
-}
-```
-
-### Streaming Implementation
-
-```go
-type StreamingExecution struct {
- cmd *exec.Cmd
- stdout io.ReadCloser
- stderr io.ReadCloser
- done chan error
-}
-
-func (bs *BashServer) executeStreaming(options ExecutionOptions) (*StreamingExecution, error) {
- // Non-blocking command execution with streaming output
- // Real-time stdout/stderr streaming via channels
-}
-```
-
-## Security Considerations (Future)
-
-### Current Design (Unrestricted)
-- No command filtering
-- No sandboxing
-- Full filesystem access (within user permissions)
-- No sudo prevention (relies on system configuration)
-
-### Future Security Options
-- Command whitelist/blacklist patterns
-- Working directory restrictions
-- Resource usage limits
-- Audit logging
-- Timeout enforcement
-- Network access controls
-
-## Performance Characteristics
-
-### Resource Usage
-- **Memory**: <5MB baseline
-- **CPU**: Minimal overhead, direct process execution
-- **Startup**: <2ms
-- **Command Overhead**: <1ms per execution
-
-### Scalability
-- Stateless execution model
-- No connection pooling required
-- Concurrent command execution support
-- Configurable resource limits
-
-## Configuration
-
-### Environment Variables
-```bash
-BASH_MCP_DEFAULT_TIMEOUT=30 # Default command timeout
-BASH_MCP_MAX_TIMEOUT=300 # Maximum allowed timeout
-BASH_MCP_MAX_HISTORY=100 # Command history size
-BASH_MCP_WORKING_DIR=/tmp # Default working directory
-```
-
-### Command Line Flags
-```bash
-mcp-bash [options]
- --default-timeout int Default command timeout in seconds (default: 30)
- --max-timeout int Maximum command timeout in seconds (default: 300)
- --history-size int Command history size (default: 100)
- --working-dir string Default working directory (default: current)
-```
-
-## Example Usage Patterns
-
-### Development Workflow
-```bash
-# Project setup
-git clone https://github.com/user/project.git
-cd project
-npm install
-npm test
-
-# Build and deploy
-make build
-docker build -t myapp .
-docker run -p 3000:3000 myapp
-```
-
-### System Administration
-```bash
-# Process monitoring
-ps aux | grep nginx
-netstat -tulpn | grep :80
-systemctl status nginx
-
-# Log analysis
-tail -f /var/log/nginx/error.log
-grep "ERROR" /var/log/app/*.log
-```
-
-### File Operations
-```bash
-# Complex file operations
-find . -name "*.log" -mtime +7 -delete
-tar -czf backup.tar.gz --exclude='node_modules' .
-rsync -av src/ backup/src/
-```
-
-## Integration with Other MCP Servers
-
-### Complementary Usage
-- **Filesystem MCP**: High-level file operations
-- **Bash MCP**: Complex shell operations and automation
-- **Git MCP**: Git-specific operations
-- **Bash MCP**: Advanced git workflows and scripting
-
-### Resource Sharing
-- Bash server can invoke other MCP tools indirectly
-- Shared working directory concepts
-- Environment variable coordination
-
-## Future Enhancements
-
-### Phase 1 Additions
-- Command completion suggestions
-- Interactive shell session support
-- Background process management
-- Signal handling (SIGINT, SIGTERM)
-
-### Phase 2 Additions
-- Command history search and replay
-- Macro/script execution
-- Pipeline composition tools
-- Performance monitoring
-
-### Phase 3 Additions
-- Multi-server orchestration
-- Distributed command execution
-- Advanced streaming capabilities
-- Custom shell environments
-
-## Testing Strategy
-
-### Unit Tests
-- Command execution validation
-- Error handling verification
-- Resource management testing
-- Performance benchmarking
-
-### Integration Tests
-- Real command execution
-- Timeout handling
-- Working directory management
-- Environment variable handling
-
-### Performance Tests
-- Concurrent execution limits
-- Memory usage under load
-- Command execution overhead
-- Streaming performance
-
-## Deployment Considerations
-
-### Minimal Setup
-- Single binary deployment
-- No external dependencies
-- Standard stdio interface
-- Environment-based configuration
-
-### Production Readiness
-- Process supervision (systemd, supervisor)
-- Log rotation and management
-- Resource monitoring
-- Graceful shutdown handling
-
-This design provides maximum flexibility and power while maintaining the minimal resource usage and lazy loading principles. The unrestricted nature allows for comprehensive AI agent capabilities while keeping the door open for future security enhancements based on observed usage patterns.
cmd/fetch/README.md
@@ -1,294 +0,0 @@
-# Fetch MCP Server
-
-A Model Context Protocol (MCP) server that provides web content fetching capabilities with advanced HTML processing and conversion.
-
-## Overview
-
-The Fetch MCP server enables AI assistants to retrieve and process web content through a standardized protocol. It features professional HTML parsing, automatic content cleaning, and conversion to clean markdown format for better AI consumption.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make fetch
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-fetch ./cmd/fetch
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-fetch
-```
-
-**No arguments required** - The server is ready to accept fetch requests for any publicly accessible URL.
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-fetch
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-fetch
-
-# Fetch a webpage
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://example.com"}}}' | timeout 10s mcp-fetch
-```
-
-#### Web Content Fetching
-```bash
-# Fetch news article
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://news.ycombinator.com"}}}' | timeout 10s mcp-fetch
-
-# Fetch documentation
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://golang.org/doc/"}}}' | timeout 10s mcp-fetch
-
-# Fetch with custom reason
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://api.github.com", "reason": "Check GitHub API status"}}}' | timeout 10s mcp-fetch
-```
-
-## Available Tools
-
-### Web Fetching
-- **`fetch`**: Retrieve and process web content
- - **Parameters:**
- - `url` (required): The URL to fetch
- - `reason` (optional): Human-readable reason for the fetch (for logging/context)
- - **Returns:** Clean markdown representation of the web content
-
-## Prompts
-
-### Interactive URL Fetching
-- **`fetch`**: Interactive prompt for URL entry with context
- - Guides users through URL entry
- - Requests optional reasoning for the fetch
- - Validates URLs before processing
-
-## Advanced Features
-
-### HTML Processing
-- **Professional Parsing**: Uses `goquery` for robust HTML parsing
-- **Content Extraction**: Intelligent content area detection
-- **Noise Removal**: Automatic filtering of ads, navigation, scripts, and styles
-- **Clean Conversion**: HTML-to-markdown conversion with proper formatting
-
-### Content Optimization
-- **Markdown Output**: Clean, AI-friendly markdown format
-- **Structure Preservation**: Maintains headings, lists, and formatting
-- **Link Processing**: Converts HTML links to markdown format
-- **Image Handling**: Processes image references and alt text
-
-### Performance & Reliability
-- **Timeout Handling**: Configurable request timeouts
-- **Error Recovery**: Graceful handling of network errors
-- **User Agent**: Professional user agent for better site compatibility
-- **Rate Limiting**: Built-in protection against excessive requests
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "fetch": {
- "command": "/usr/local/bin/mcp-fetch"
- }
- }
-}
-```
-
-### Multiple Fetch Services
-```json
-{
- "mcpServers": {
- "web-fetch": {
- "command": "/usr/local/bin/mcp-fetch"
- },
- "backup-fetch": {
- "command": "/usr/local/bin/mcp-fetch"
- }
- }
-}
-```
-
-## Example Workflows
-
-### Research and Documentation
-```bash
-# Fetch technical documentation
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://docs.python.org/3/library/requests.html", "reason": "Learning about Python requests library"}}}' | mcp-fetch
-
-# Fetch latest news
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://techcrunch.com", "reason": "Checking latest tech news"}}}' | mcp-fetch
-```
-
-### API Documentation Access
-```bash
-# Fetch REST API docs
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://docs.github.com/en/rest", "reason": "GitHub API reference"}}}' | mcp-fetch
-
-# Fetch OpenAPI specs
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://petstore.swagger.io/", "reason": "Example API specification"}}}' | mcp-fetch
-```
-
-### Content Analysis
-```bash
-# Fetch blog posts for analysis
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://blog.golang.org/go1.21", "reason": "Analyzing Go 1.21 features"}}}' | mcp-fetch
-
-# Fetch competitor content
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://competitor.com/features", "reason": "Competitive analysis"}}}' | mcp-fetch
-```
-
-### Interactive Fetching with Prompts
-```bash
-# Use the interactive prompt
-echo '{"jsonrpc": "2.0", "id": 1, "method": "prompts/get", "params": {"name": "fetch", "arguments": {}}}' | mcp-fetch
-
-# The prompt will guide you through:
-# 1. URL entry with validation
-# 2. Optional reason/context entry
-# 3. Automatic fetching and processing
-```
-
-## Supported Content Types
-
-### Web Pages
-- **HTML Documents**: Full HTML parsing and conversion
-- **Blog Posts**: Article extraction with clean formatting
-- **Documentation Sites**: Technical documentation processing
-- **News Articles**: News content with metadata extraction
-
-### API Responses
-- **JSON APIs**: Raw JSON content preservation
-- **XML Responses**: Basic XML structure maintenance
-- **Plain Text**: Direct text content handling
-
-### Social Media
-- **Limited Support**: Basic content extraction where possible
-- **Rate Limiting**: Respects site rate limits and robots.txt
-
-## Security Considerations
-
-### URL Validation
-- **Protocol Restrictions**: Only HTTP/HTTPS supported
-- **Malicious URL Detection**: Basic URL validation
-- **Request Limits**: Built-in timeout and size limits
-
-### Content Safety
-- **No JavaScript Execution**: Static content only
-- **Content Filtering**: Automatic removal of potentially harmful content
-- **Privacy Protection**: No cookies or session management
-
-### Network Security
-- **Timeout Protection**: Prevents hanging requests
-- **Size Limits**: Prevents excessive content download
-- **Error Handling**: Safe error reporting without sensitive data exposure
-
-## Performance
-
-- **Startup Time**: ~1.5ms
-- **Memory Usage**: <10MB during operation
-- **Request Timeout**: 30 seconds default
-- **Content Limits**: Reasonable size limits for AI processing
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Failed to fetch URL"**
- ```bash
- # Check URL accessibility
- curl -I https://example.com
-
- # Verify network connectivity
- ping google.com
- ```
-
-2. **"Timeout errors"**
- ```bash
- # Check if site is slow
- time curl https://slow-site.com
-
- # Try with different URL
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://httpbin.org/delay/1"}}}' | mcp-fetch
- ```
-
-3. **"Content parsing errors"**
- ```bash
- # Test with simple HTML page
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://example.com"}}}' | mcp-fetch
- ```
-
-4. **"Network blocked"**
- ```bash
- # Check if behind firewall/proxy
- curl --proxy http://proxy:8080 https://example.com
-
- # Verify DNS resolution
- nslookup example.com
- ```
-
-### Testing Connectivity
-```bash
-# Test basic fetch functionality
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://httpbin.org/json"}}}' | mcp-fetch
-
-# Test HTML processing
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://httpbin.org/html"}}}' | mcp-fetch
-
-# Test error handling
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "fetch", "arguments": {"url": "https://httpbin.org/status/404"}}}' | mcp-fetch
-```
-
-## Best Practices
-
-1. **Provide Context**: Always include a reason for fetching to aid in logging and debugging
-2. **Test URLs First**: Verify URLs are accessible before using in production
-3. **Handle Errors**: Expect network errors and have fallback strategies
-4. **Respect Rate Limits**: Don't make excessive requests to the same domain
-5. **Check Content**: Verify the fetched content meets your expectations
-
-## Limitations
-
-### Technical Limitations
-- **Static Content Only**: No JavaScript execution or dynamic content
-- **Size Limits**: Large files may be truncated
-- **Format Limitations**: Best results with standard HTML content
-
-### Network Limitations
-- **Public URLs Only**: Cannot access internal/private networks
-- **No Authentication**: Cannot handle login-required content
-- **Rate Limiting**: May be limited by target sites
-
-### Content Limitations
-- **Dynamic Content**: Cannot fetch dynamically generated content
-- **Interactive Elements**: Forms, buttons, etc. are not preserved
-- **Multimedia**: Limited support for video/audio content
-
-## Use Cases
-
-- **Research**: Gathering information from web sources
-- **Documentation**: Accessing technical documentation
-- **Content Analysis**: Analyzing competitor or industry content
-- **News Monitoring**: Tracking news and updates
-- **API Exploration**: Examining API documentation and responses
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/filesystem/README.md
@@ -1,201 +0,0 @@
-# Filesystem MCP Server
-
-A ultra-minimal Model Context Protocol (MCP) server optimized for efficient filesystem access with open models like gpt-oss:latest.
-
-## Overview
-
-The Filesystem MCP server provides essential file operations through a standardized protocol with minimal token overhead. Designed for maximum efficiency on commodity hardware while maintaining strict security boundaries.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make filesystem
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-filesystem ./cmd/filesystem
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-filesystem --allowed-directory <path1> [--allowed-directory <path2> ...]
-```
-
-**Required Arguments:**
-- `--allowed-directory <path>`: Directory path to allow access to (can be repeated for multiple directories)
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-filesystem --allowed-directory /tmp
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-filesystem --allowed-directory /tmp
-
-# List filesystem resources
-echo '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}' | timeout 5s mcp-filesystem --allowed-directory /tmp
-```
-
-#### File Operations Testing
-```bash
-# Create a test file
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "write_file", "arguments": {"path": "/tmp/test.txt", "content": "Hello, World!"}}}' | timeout 5s mcp-filesystem --allowed-directory /tmp
-
-# Read the file back
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": "/tmp/test.txt"}}}' | timeout 5s mcp-filesystem --allowed-directory /tmp
-```
-
-## Available Tools
-
-### Core File Operations
-- **`read_file`**: Read contents of a file
-- **`write_file`**: Write content to a file (creates or overwrites)
-
-## Resources
-
-The server provides `file://` resources for efficient file discovery:
-
-### Directory Resources
-- **URI Format**: `file://<directory_path>`
-- **Example**: `file:///home/user/projects`
-- **Description**: Automatic discovery of programming files (.go, .js, .py, etc.)
-
-### Supported File Types
-- Programming files: `.go`, `.js`, `.ts`, `.py`, `.rs`, `.java`, `.c`, `.cpp`, `.md`, `.json`, `.yaml`, etc.
-- Build files: `Makefile`, `package.json`, `go.mod`, `Cargo.toml`, etc.
-- Configuration files: `.env`, `.gitignore`, etc.
-
-## Security Features
-
-### Access Control
-- **Directory Restrictions**: Only allowed directories are accessible
-- **Path Validation**: All paths are validated and normalized
-- **No Directory Traversal**: `../` attempts are blocked
-
-### File Safety
-- **Binary Detection**: Automatic detection and safe handling of binary files
-- **Resource Limits**: 500 file limit for resource discovery to prevent performance issues
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "filesystem": {
- "command": "/usr/local/bin/mcp-filesystem",
- "args": ["--allowed-directory", "/home/user/projects", "--allowed-directory", "/tmp"]
- }
- }
-}
-```
-
-### Development Environment
-```json
-{
- "mcpServers": {
- "filesystem": {
- "command": "/usr/local/bin/mcp-filesystem",
- "args": [
- "--allowed-directory", "/home/user/code",
- "--allowed-directory", "/tmp"
- ]
- }
- }
-}
-```
-
-## Efficiency & Design Philosophy
-
-This ultra-minimal filesystem server is specifically optimized for:
-
-- **Token Efficiency**: 92% reduction in tool definitions compared to full-featured servers
-- **Open Models**: Optimized for gpt-oss:latest and similar models on commodity hardware
-- **Essential Operations**: Only the most critical file operations (read/write)
-- **Complementary Design**: Works with bash MCP server for advanced operations:
- - Directory listing: Use `ls` via bash MCP
- - File search: Use `find` or `grep` via bash MCP
- - Directory creation: Use `mkdir -p` via bash MCP
- - File info: Use `stat` via bash MCP
-
-## Performance
-
-- **Startup Time**: <10ms for typical configurations
-- **Memory Usage**: <5MB base usage
-- **Token Overhead**: ~150 tokens per tools/list (vs ~1800 for full servers)
-- **Resource Discovery**: Up to 500 files discovered automatically
-- **Thread Safety**: Safe for concurrent operations
-
-## Advanced Usage
-
-### File Discovery via Resources
-Instead of directory listing tools, use the resources API:
-```bash
-# Discover all programming files
-echo '{"jsonrpc": "2.0", "id": 1, "method": "resources/list"}' | mcp-filesystem --allowed-directory /project
-
-# Read discovered files via resources/read
-echo '{"jsonrpc": "2.0", "id": 2, "method": "resources/read", "params": {"uri": "file:///project/main.go"}}' | mcp-filesystem --allowed-directory /project
-```
-
-### Workflow Pattern
-1. **Discover**: Use `resources/list` to find files
-2. **Read**: Use `read_file` for content
-3. **Modify**: Process content in your application
-4. **Write**: Use `write_file` to save changes
-
-## Complementary Tools
-
-This minimal server works best with:
-- **Bash MCP Server**: For directory operations, file search, system commands
-- **Git MCP Server**: For version control operations
-- **Your IDE/Editor**: For complex editing operations
-
-## Best Practices
-
-1. **Use Resources API**: Leverage `resources/list` for file discovery instead of directory listing
-2. **Combine with Bash MCP**: Use bash server for operations not included here
-3. **Read-Modify-Write**: Use read → modify → write pattern instead of complex editing
-4. **Absolute Paths**: Always specify full paths to avoid ambiguity
-5. **Limit Directory Scope**: Only include necessary directories in allowed list
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Access denied" errors**
- ```bash
- # Ensure the directory is in allowed-directory list
- mcp-filesystem --allowed-directory /correct/path
- ```
-
-2. **"File not found"**
- ```bash
- # Use resources/list to discover available files first
- echo '{"jsonrpc": "2.0", "id": 1, "method": "resources/list"}' | mcp-filesystem --allowed-directory /path
- ```
-
-3. **Need directory listing**
- ```bash
- # Use bash MCP server instead:
- # ls /path/to/directory
- ```
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/git/README.md
@@ -1,215 +0,0 @@
-# Git MCP Server
-
-A Model Context Protocol (MCP) server that provides comprehensive Git repository operations and browsing capabilities.
-
-## Overview
-
-The Git MCP server enables AI assistants to interact with Git repositories through a standardized protocol. It provides tools for Git operations (status, diff, commit, branch management) and resources for browsing repository contents.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make git
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-git ./cmd/git
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-git --repository <path>
-```
-
-**Required Arguments:**
-- `--repository <path>`: Path to the Git repository to manage
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-git --repository .
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-git --repository .
-
-# List repository resources
-echo '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}' | timeout 5s mcp-git --repository .
-
-# Check Git status
-echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "git_status", "arguments": {}}}' | timeout 5s mcp-git --repository .
-```
-
-#### Interactive Session
-```bash
-# Start the server (in another terminal or script)
-mcp-git --repository /path/to/your/repo
-
-# Then send JSON-RPC requests via stdin
-```
-
-## Available Tools
-
-### Repository Status & Information
-- **`git_status`**: Get current repository status
-- **`git_log`**: View commit history with filtering options
-- **`git_show`**: Show details of a specific commit
-
-### Diff Operations
-- **`git_diff`**: Show differences between commits/branches
-- **`git_diff_staged`**: Show staged changes
-- **`git_diff_unstaged`**: Show unstaged changes
-
-### Branch Management
-- **`git_create_branch`**: Create a new branch
-- **`git_checkout`**: Switch branches or checkout commits
-- **`git_list_branches`**: List all local and remote branches
-
-### File Operations
-- **`git_add`**: Stage files for commit
-- **`git_commit`**: Create commits with messages
-- **`git_reset`**: Reset changes (soft, mixed, hard)
-
-### Repository Initialization
-- **`git_init`**: Initialize a new Git repository
-
-## Resources
-
-The server provides `git://` resources for:
-
-### File Resources
-- **URI Format**: `git://<repo_path>/<branch>/<file_path>`
-- **Example**: `git:///home/user/project/main/src/main.go`
-- **Description**: Access to tracked files in the repository
-
-### Branch Resources
-- **URI Format**: `git://<repo_path>/branches/<branch_name>`
-- **Example**: `git:///home/user/project/branches/feature-branch`
-- **Description**: Information about repository branches
-
-### Commit Resources
-- **URI Format**: `git://<repo_path>/commits/<commit_hash>`
-- **Example**: `git:///home/user/project/commits/abc123def456`
-- **Description**: Detailed commit information
-
-## Configuration Examples
-
-### Claude Desktop Integration
-Add to your `~/.claude.json`:
-
-```json
-{
- "mcpServers": {
- "git": {
- "command": "/usr/local/bin/mcp-git",
- "args": ["--repository", "/path/to/your/repository"]
- }
- }
-}
-```
-
-### Multiple Repositories
-```json
-{
- "mcpServers": {
- "git-project1": {
- "command": "/usr/local/bin/mcp-git",
- "args": ["--repository", "/home/user/project1"]
- },
- "git-project2": {
- "command": "/usr/local/bin/mcp-git",
- "args": ["--repository", "/home/user/project2"]
- }
- }
-}
-```
-
-## Example Workflows
-
-### Check Repository Status
-```bash
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "git_status", "arguments": {}}}' | mcp-git --repository .
-```
-
-### Create and Switch to New Branch
-```bash
-# Create branch
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "git_create_branch", "arguments": {"branch_name": "feature-new"}}}' | mcp-git --repository .
-
-# Switch to branch
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "git_checkout", "arguments": {"target": "feature-new"}}}' | mcp-git --repository .
-```
-
-### View Recent Commits
-```bash
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "git_log", "arguments": {"max_count": 5}}}' | mcp-git --repository .
-```
-
-### Stage and Commit Changes
-```bash
-# Stage files
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "git_add", "arguments": {"files": ["src/main.go", "README.md"]}}}' | mcp-git --repository .
-
-# Commit changes
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "git_commit", "arguments": {"message": "Add new feature implementation"}}}' | mcp-git --repository .
-```
-
-## Security Considerations
-
-- The server only operates within the specified repository directory
-- No access to files outside the repository
-- Git operations respect repository permissions
-- No network operations (clone, push, pull) for security
-
-## Performance
-
-- **Startup Time**: ~2-3ms for typical repositories
-- **Resource Limit**: Maximum 500 files loaded for resource discovery
-- **Memory Usage**: <10MB for most repositories
-- **Lazy Loading**: Resources discovered on-demand
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Repository not found"**
- ```bash
- # Ensure the path exists and is a Git repository
- git status # Test if directory is a valid Git repo
- ```
-
-2. **"Permission denied"**
- ```bash
- # Check file permissions
- ls -la /path/to/repository
- ```
-
-3. **"Invalid repository path"**
- ```bash
- # Use absolute paths for reliability
- mcp-git --repository "$(pwd)"
- ```
-
-### Debug Mode
-```bash
-# Enable verbose logging (if implemented)
-RUST_LOG=debug mcp-git --repository .
-```
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/gitlab/DESIGN.md
@@ -1,685 +0,0 @@
-# GitLab MCP Server Design Document
-
-**Project:** GitLab MCP Server
-**Repository:** `https://github.com/xlgmokha/mcp`
-**Target Path:** `cmd/gitlab/` and `pkg/gitlab/`
-**Language:** Go
-**Version:** 1.0.0
-
----
-
-## Overview
-
-This document outlines the design for a comprehensive GitLab MCP server that provides AI assistants with access to GitLab APIs for issue management, user activity tracking, project operations, and workflow automation. The design is informed by the existing Jive Ruby tool and follows the established Go MCP server patterns.
-
-## Project Context
-
-### Inspiration from Jive Tool
-The Jive Ruby tool (`/Users/xlgmokha/src/gitlab.com/mokhax/gitlab`) demonstrates several key patterns:
-- **Local-first workflow**: Sync GitLab data to local Markdown files with YAML frontmatter
-- **Interactive issue management**: Browse, edit, and sync issues back to GitLab
-- **Template-driven creation**: Use ERB templates for consistent issue creation
-- **Author-specific filtering**: Focus on specific authors and labels
-- **Activity tracking**: Export user activity to YAML files
-
-### MCP Architecture Alignment
-Following the established Go MCP server patterns:
-- Stateless tools that communicate via JSON-RPC over stdio
-- Comprehensive input validation and error handling
-- Structured logging and debugging capabilities
-- Clean separation of concerns with `pkg/gitlab/` for reusable logic
-- Thread-safe operations with proper concurrency handling
-
----
-
-## Architecture
-
-### Directory Structure
-```
-cmd/gitlab/
-├── main.go # Entry point and CLI setup
-└── README.md # Usage documentation
-
-pkg/gitlab/
-├── server.go # MCP server implementation
-├── server_test.go # Server tests
-├── client.go # GitLab API client
-├── client_test.go # Client tests
-├── types.go # GitLab API types and structures
-├── cache.go # Local caching implementation
-├── templates.go # Issue template handling
-└── activity.go # User activity tracking
-```
-
-### Core Components
-
-#### 1. GitLab API Client (`pkg/gitlab/client.go`)
-- HTTP client with retry logic and rate limiting
-- Authentication via Personal Access Token
-- Pagination support for large result sets
-- Comprehensive error handling and logging
-- Support for gitlab.com and self-hosted instances
-
-#### 2. MCP Server (`pkg/gitlab/server.go`)
-- JSON-RPC 2.0 over stdio communication
-- Tool registration and request routing
-- Input validation and sanitization
-- Structured error responses
-- Configurable GitLab instance and authentication
-
-#### 3. Local Cache System (`pkg/gitlab/cache.go`)
-- Optional local storage for offline access
-- Markdown files with YAML frontmatter (compatible with Jive)
-- Sync detection and conflict resolution
-- Cache invalidation strategies
-
-#### 4. Template System (`pkg/gitlab/templates.go`)
-- Issue and MR templates with Go text/template
-- Support for existing ERB templates from Jive
-- Variable substitution and validation
-- Template library management
-
----
-
-## Tools Specification
-
-### Core GitLab Operations
-
-#### `gitlab_get_user_info`
-Get current authenticated user information.
-```json
-{
- "name": "gitlab_get_user_info",
- "description": "Get information about the authenticated GitLab user",
- "inputSchema": {
- "type": "object",
- "properties": {}
- }
-}
-```
-
-#### `gitlab_list_groups`
-List accessible GitLab groups with optional filtering.
-```json
-{
- "name": "gitlab_list_groups",
- "description": "List GitLab groups accessible to the authenticated user",
- "inputSchema": {
- "type": "object",
- "properties": {
- "search": {"type": "string", "description": "Search term for group names"},
- "owned": {"type": "boolean", "description": "Only groups owned by user", "default": false},
- "per_page": {"type": "integer", "description": "Results per page", "default": 20, "maximum": 100}
- }
- }
-}
-```
-
-#### `gitlab_list_projects`
-List projects with advanced filtering options.
-```json
-{
- "name": "gitlab_list_projects",
- "description": "List GitLab projects with filtering options",
- "inputSchema": {
- "type": "object",
- "properties": {
- "group_id": {"type": "integer", "description": "Limit to specific group"},
- "search": {"type": "string", "description": "Search term for project names"},
- "owned": {"type": "boolean", "description": "Only owned projects", "default": false},
- "membership": {"type": "boolean", "description": "Projects user is member of", "default": true},
- "archived": {"type": "boolean", "description": "Include archived projects", "default": false},
- "visibility": {"type": "string", "enum": ["private", "internal", "public"], "description": "Project visibility"},
- "per_page": {"type": "integer", "description": "Results per page", "default": 20, "maximum": 100}
- }
- }
-}
-```
-
-### Issue Management
-
-#### `gitlab_list_issues`
-List issues with comprehensive filtering (inspired by Jive patterns).
-```json
-{
- "name": "gitlab_list_issues",
- "description": "List GitLab issues with advanced filtering options",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "group_id": {"type": "integer", "description": "Group ID (alternative to project_id)"},
- "state": {"type": "string", "enum": ["opened", "closed", "all"], "default": "opened"},
- "author_username": {"type": "string", "description": "Filter by author username"},
- "assignee_username": {"type": "string", "description": "Filter by assignee username"},
- "labels": {"type": "array", "items": {"type": "string"}, "description": "Filter by labels"},
- "milestone": {"type": "string", "description": "Filter by milestone title"},
- "search": {"type": "string", "description": "Search in title and description"},
- "created_after": {"type": "string", "format": "date-time", "description": "Created after date"},
- "created_before": {"type": "string", "format": "date-time", "description": "Created before date"},
- "updated_after": {"type": "string", "format": "date-time", "description": "Updated after date"},
- "updated_before": {"type": "string", "format": "date-time", "description": "Updated before date"},
- "sort": {"type": "string", "enum": ["created_at", "updated_at", "priority", "due_date"], "default": "updated_at"},
- "order": {"type": "string", "enum": ["asc", "desc"], "default": "desc"},
- "per_page": {"type": "integer", "description": "Results per page", "default": 20, "maximum": 100}
- }
- }
-}
-```
-
-#### `gitlab_get_issue`
-Get detailed issue information including comments and metadata.
-```json
-{
- "name": "gitlab_get_issue",
- "description": "Get detailed information about a specific GitLab issue",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "issue_iid": {"type": "integer", "description": "Issue internal ID"},
- "include_comments": {"type": "boolean", "description": "Include issue comments", "default": true},
- "include_system_notes": {"type": "boolean", "description": "Include system notes", "default": false}
- },
- "required": ["project_id", "issue_iid"]
- }
-}
-```
-
-#### `gitlab_create_issue`
-Create new issues with template support.
-```json
-{
- "name": "gitlab_create_issue",
- "description": "Create a new GitLab issue with optional template",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "title": {"type": "string", "description": "Issue title"},
- "description": {"type": "string", "description": "Issue description"},
- "template_name": {"type": "string", "description": "Template to use for issue creation"},
- "template_variables": {"type": "object", "description": "Variables for template substitution"},
- "labels": {"type": "array", "items": {"type": "string"}, "description": "Issue labels"},
- "assignee_usernames": {"type": "array", "items": {"type": "string"}, "description": "Assignee usernames"},
- "milestone_id": {"type": "integer", "description": "Milestone ID"},
- "due_date": {"type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)"},
- "weight": {"type": "integer", "description": "Issue weight", "minimum": 1},
- "confidential": {"type": "boolean", "description": "Mark as confidential", "default": false}
- },
- "required": ["project_id", "title"]
- }
-}
-```
-
-#### `gitlab_update_issue`
-Update existing issues with change tracking.
-```json
-{
- "name": "gitlab_update_issue",
- "description": "Update an existing GitLab issue",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "issue_iid": {"type": "integer", "description": "Issue internal ID"},
- "title": {"type": "string", "description": "New issue title"},
- "description": {"type": "string", "description": "New issue description"},
- "state_event": {"type": "string", "enum": ["close", "reopen"], "description": "State change"},
- "labels": {"type": "array", "items": {"type": "string"}, "description": "Replace labels"},
- "add_labels": {"type": "array", "items": {"type": "string"}, "description": "Add labels"},
- "remove_labels": {"type": "array", "items": {"type": "string"}, "description": "Remove labels"},
- "assignee_usernames": {"type": "array", "items": {"type": "string"}, "description": "Replace assignees"},
- "milestone_id": {"type": "integer", "description": "Milestone ID (null to unset)"},
- "due_date": {"type": "string", "format": "date", "description": "Due date (null to unset)"},
- "weight": {"type": "integer", "description": "Issue weight"},
- "confidential": {"type": "boolean", "description": "Mark as confidential"}
- },
- "required": ["project_id", "issue_iid"]
- }
-}
-```
-
-#### `gitlab_add_issue_comment`
-Add comments to issues with formatting support.
-```json
-{
- "name": "gitlab_add_issue_comment",
- "description": "Add a comment to a GitLab issue",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "issue_iid": {"type": "integer", "description": "Issue internal ID"},
- "body": {"type": "string", "description": "Comment body (Markdown supported)"},
- "confidential": {"type": "boolean", "description": "Mark comment as confidential", "default": false}
- },
- "required": ["project_id", "issue_iid", "body"]
- }
-}
-```
-
-### Merge Request Operations
-
-#### `gitlab_list_merge_requests`
-List merge requests with filtering options.
-```json
-{
- "name": "gitlab_list_merge_requests",
- "description": "List GitLab merge requests with filtering options",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "group_id": {"type": "integer", "description": "Group ID (alternative to project_id)"},
- "state": {"type": "string", "enum": ["opened", "closed", "merged", "all"], "default": "opened"},
- "author_username": {"type": "string", "description": "Filter by author username"},
- "assignee_username": {"type": "string", "description": "Filter by assignee username"},
- "reviewer_username": {"type": "string", "description": "Filter by reviewer username"},
- "labels": {"type": "array", "items": {"type": "string"}, "description": "Filter by labels"},
- "milestone": {"type": "string", "description": "Filter by milestone title"},
- "source_branch": {"type": "string", "description": "Filter by source branch"},
- "target_branch": {"type": "string", "description": "Filter by target branch"},
- "search": {"type": "string", "description": "Search in title and description"},
- "draft": {"type": "boolean", "description": "Filter draft MRs"},
- "sort": {"type": "string", "enum": ["created_at", "updated_at", "priority"], "default": "updated_at"},
- "order": {"type": "string", "enum": ["asc", "desc"], "default": "desc"},
- "per_page": {"type": "integer", "description": "Results per page", "default": 20, "maximum": 100}
- }
- }
-}
-```
-
-#### `gitlab_get_merge_request`
-Get detailed merge request information.
-```json
-{
- "name": "gitlab_get_merge_request",
- "description": "Get detailed information about a specific GitLab merge request",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "merge_request_iid": {"type": "integer", "description": "Merge request internal ID"},
- "include_comments": {"type": "boolean", "description": "Include MR comments", "default": true},
- "include_commits": {"type": "boolean", "description": "Include commit list", "default": false},
- "include_changes": {"type": "boolean", "description": "Include file changes", "default": false}
- },
- "required": ["project_id", "merge_request_iid"]
- }
-}
-```
-
-#### `gitlab_create_merge_request`
-Create new merge requests from branches.
-```json
-{
- "name": "gitlab_create_merge_request",
- "description": "Create a new GitLab merge request",
- "inputSchema": {
- "type": "object",
- "properties": {
- "project_id": {"type": "integer", "description": "Project ID"},
- "title": {"type": "string", "description": "Merge request title"},
- "description": {"type": "string", "description": "Merge request description"},
- "source_branch": {"type": "string", "description": "Source branch name"},
- "target_branch": {"type": "string", "description": "Target branch name", "default": "main"},
- "template_name": {"type": "string", "description": "Template to use for MR creation"},
- "template_variables": {"type": "object", "description": "Variables for template substitution"},
- "labels": {"type": "array", "items": {"type": "string"}, "description": "MR labels"},
- "assignee_usernames": {"type": "array", "items": {"type": "string"}, "description": "Assignee usernames"},
- "reviewer_usernames": {"type": "array", "items": {"type": "string"}, "description": "Reviewer usernames"},
- "milestone_id": {"type": "integer", "description": "Milestone ID"},
- "remove_source_branch": {"type": "boolean", "description": "Remove source branch when merged", "default": false},
- "squash": {"type": "boolean", "description": "Squash commits when merged", "default": false},
- "allow_collaboration": {"type": "boolean", "description": "Allow collaboration", "default": false}
- },
- "required": ["project_id", "title", "source_branch", "target_branch"]
- }
-}
-```
-
-### User Activity Tracking (Inspired by Jive)
-
-#### `gitlab_get_user_activity`
-Get comprehensive user activity with export capabilities.
-```json
-{
- "name": "gitlab_get_user_activity",
- "description": "Get GitLab user activity with optional export to YAML format",
- "inputSchema": {
- "type": "object",
- "properties": {
- "username": {"type": "string", "description": "GitLab username"},
- "start_date": {"type": "string", "format": "date", "description": "Activity start date (YYYY-MM-DD)"},
- "end_date": {"type": "string", "format": "date", "description": "Activity end date (YYYY-MM-DD)"},
- "activity_types": {
- "type": "array",
- "items": {"type": "string", "enum": ["push", "merge", "issue", "comment", "approve", "join"]},
- "description": "Filter by activity types"
- },
- "projects": {"type": "array", "items": {"type": "integer"}, "description": "Filter by project IDs"},
- "export_format": {"type": "string", "enum": ["json", "yaml"], "default": "json"},
- "save_to_cache": {"type": "boolean", "description": "Save to local cache", "default": false},
- "per_page": {"type": "integer", "description": "Results per page", "default": 50, "maximum": 100}
- },
- "required": ["username"]
- }
-}
-```
-
-#### `gitlab_analyze_user_contributions`
-Analyze user contributions across projects and time periods.
-```json
-{
- "name": "gitlab_analyze_user_contributions",
- "description": "Analyze user contributions with statistics and patterns",
- "inputSchema": {
- "type": "object",
- "properties": {
- "username": {"type": "string", "description": "GitLab username"},
- "start_date": {"type": "string", "format": "date", "description": "Analysis start date"},
- "end_date": {"type": "string", "format": "date", "description": "Analysis end date"},
- "project_ids": {"type": "array", "items": {"type": "integer"}, "description": "Limit to specific projects"},
- "include_statistics": {"type": "boolean", "description": "Include detailed statistics", "default": true},
- "group_by": {"type": "string", "enum": ["day", "week", "month"], "default": "week"},
- "export_format": {"type": "string", "enum": ["json", "csv", "yaml"], "default": "json"}
- },
- "required": ["username"]
- }
-}
-```
-
-### Local Cache Management (Jive-Compatible)
-
-#### `gitlab_sync_to_cache`
-Sync GitLab data to local Markdown cache (Jive-compatible format).
-```json
-{
- "name": "gitlab_sync_to_cache",
- "description": "Sync GitLab data to local Markdown cache with YAML frontmatter",
- "inputSchema": {
- "type": "object",
- "properties": {
- "cache_path": {"type": "string", "description": "Local cache directory path"},
- "sync_target": {"type": "string", "enum": ["issues", "merge_requests", "projects", "all"], "default": "issues"},
- "project_ids": {"type": "array", "items": {"type": "integer"}, "description": "Specific projects to sync"},
- "group_ids": {"type": "array", "items": {"type": "integer"}, "description": "Specific groups to sync"},
- "filters": {
- "type": "object",
- "properties": {
- "state": {"type": "string", "enum": ["opened", "closed", "all"], "default": "opened"},
- "author_usernames": {"type": "array", "items": {"type": "string"}},
- "labels": {"type": "array", "items": {"type": "string"}},
- "updated_after": {"type": "string", "format": "date-time"}
- },
- "description": "Filters for syncing data"
- },
- "force_update": {"type": "boolean", "description": "Force update existing cache files", "default": false},
- "preserve_local_changes": {"type": "boolean", "description": "Preserve local modifications", "default": true}
- },
- "required": ["cache_path"]
- }
-}
-```
-
-#### `gitlab_cache_status`
-Check local cache status and sync state.
-```json
-{
- "name": "gitlab_cache_status",
- "description": "Check status of local GitLab cache",
- "inputSchema": {
- "type": "object",
- "properties": {
- "cache_path": {"type": "string", "description": "Local cache directory path"},
- "check_sync": {"type": "boolean", "description": "Check sync status with GitLab", "default": true},
- "detailed": {"type": "boolean", "description": "Include detailed file information", "default": false}
- },
- "required": ["cache_path"]
- }
-}
-```
-
-### Template Management
-
-#### `gitlab_list_templates`
-List available issue and MR templates.
-```json
-{
- "name": "gitlab_list_templates",
- "description": "List available GitLab templates for issues and merge requests",
- "inputSchema": {
- "type": "object",
- "properties": {
- "template_type": {"type": "string", "enum": ["issue", "merge_request", "all"], "default": "all"},
- "project_id": {"type": "integer", "description": "Project ID for project-specific templates"},
- "include_system": {"type": "boolean", "description": "Include system templates", "default": true},
- "include_custom": {"type": "boolean", "description": "Include custom templates", "default": true}
- }
- }
-}
-```
-
-#### `gitlab_apply_template`
-Apply template to issue or MR creation.
-```json
-{
- "name": "gitlab_apply_template",
- "description": "Apply template with variable substitution",
- "inputSchema": {
- "type": "object",
- "properties": {
- "template_name": {"type": "string", "description": "Template name"},
- "template_type": {"type": "string", "enum": ["issue", "merge_request"], "description": "Template type"},
- "variables": {"type": "object", "description": "Template variables for substitution"},
- "project_id": {"type": "integer", "description": "Project ID for project-specific templates"}
- },
- "required": ["template_name", "template_type"]
- }
-}
-```
-
-### Search and Discovery
-
-#### `gitlab_search`
-Global search across GitLab content.
-```json
-{
- "name": "gitlab_search",
- "description": "Search across GitLab projects, issues, merge requests, and code",
- "inputSchema": {
- "type": "object",
- "properties": {
- "query": {"type": "string", "description": "Search query"},
- "scope": {
- "type": "string",
- "enum": ["projects", "issues", "merge_requests", "milestones", "users", "code", "commits", "blobs", "wiki_blobs"],
- "description": "Search scope"
- },
- "project_ids": {"type": "array", "items": {"type": "integer"}, "description": "Limit search to specific projects"},
- "group_ids": {"type": "array", "items": {"type": "integer"}, "description": "Limit search to specific groups"},
- "filters": {
- "type": "object",
- "properties": {
- "state": {"type": "string", "enum": ["opened", "closed", "merged", "all"]},
- "confidential": {"type": "boolean", "description": "Include confidential items"},
- "order_by": {"type": "string", "enum": ["created_at", "updated_at", "title"], "default": "updated_at"},
- "sort": {"type": "string", "enum": ["asc", "desc"], "default": "desc"}
- }
- },
- "per_page": {"type": "integer", "description": "Results per page", "default": 20, "maximum": 100}
- },
- "required": ["query", "scope"]
- }
-}
-```
-
----
-
-## Configuration
-
-### Environment Variables
-- `GITLAB_TOKEN`: Personal Access Token for authentication (required)
-- `GITLAB_URL`: GitLab instance URL (default: "https://gitlab.com")
-- `GITLAB_API_VERSION`: API version (default: "v4")
-- `GITLAB_CACHE_DIR`: Default cache directory for local storage
-- `GITLAB_TIMEOUT`: Request timeout in seconds (default: 30)
-- `GITLAB_RATE_LIMIT`: Requests per minute (default: 1000)
-
-### Command Line Arguments
-```bash
-mcp-gitlab [options]
-
-Options:
- --gitlab-url string GitLab instance URL (default "https://gitlab.com")
- --gitlab-token string Personal Access Token (overrides env var)
- --cache-dir string Local cache directory
- --template-dir string Custom template directory
- --debug Enable debug logging
- --config string Configuration file path
-```
-
-### Configuration File Support
-YAML configuration file for complex setups:
-```yaml
-gitlab:
- url: "https://gitlab.company.com"
- token: "${GITLAB_TOKEN}"
- timeout: 30
- rate_limit: 1000
-
-cache:
- enabled: true
- directory: "./gitlab-cache"
- format: "markdown" # markdown (Jive-compatible) or json
-
-templates:
- directory: "./templates"
- default_issue_template: "bug_report"
- default_mr_template: "feature"
-
-defaults:
- group_id: 9970
- project_ids: [278964, 66499760, 68877410, 69516684]
- authors: ["xlgmokha", "mokhax"]
- labels: ["group::authorization"]
-
-logging:
- level: "info"
- format: "json"
-```
-
----
-
-## Implementation Details
-
-### Authentication and Security
-- Personal Access Token authentication
-- Support for token rotation and refresh
-- Secure token storage (environment variables, not in config files)
-- Rate limiting and retry logic with exponential backoff
-- Request timeout and circuit breaker patterns
-
-### Local Cache System
-- **Jive Compatibility**: Store issues as Markdown files with YAML frontmatter
-- **Sync Detection**: Compare timestamps and checksums for changes
-- **Conflict Resolution**: Preserve local changes with merge conflict markers
-- **Cache Structure**:
- ```
- cache/
- ├── groups/
- │ └── {group_id}/
- ├── projects/
- │ └── {project_id}/
- ├── issues/
- │ └── {project_id}/
- │ └── {issue_iid}.md
- ├── merge_requests/
- │ └── {project_id}/
- │ └── {mr_iid}.md
- └── users/
- └── {username}/
- └── activity/
- └── {date}.yml
- ```
-
-### Template System
-- **Go text/template** engine for variable substitution
-- **ERB Compatibility**: Convert existing Jive ERB templates
-- **Variable Resolution**: Support environment variables and user input
-- **Template Libraries**: System and project-specific templates
-- **Validation**: Schema validation for template variables
-
-### Error Handling and Resilience
-- Comprehensive GitLab API error mapping
-- Graceful degradation for network issues
-- Request retry with exponential backoff
-- Circuit breaker for service availability
-- Detailed error messages with suggested actions
-
-### Performance Optimization
-- **Connection Pooling**: Reuse HTTP connections
-- **Caching**: Local cache for frequently accessed data
-- **Pagination**: Efficient handling of large result sets
-- **Concurrent Requests**: Parallel processing where safe
-- **Memory Management**: Streaming for large responses
-
-### Testing Strategy
-- **Unit Tests**: All tools and utility functions
-- **Integration Tests**: GitLab API interactions with test instance
-- **Mock Testing**: Offline testing with recorded responses
-- **Performance Tests**: Load testing and benchmarking
-- **Cache Tests**: Sync and conflict resolution scenarios
-
----
-
-## Migration from Jive
-
-### Data Migration
-1. **Cache Format**: Convert existing Jive cache to MCP-compatible format
-2. **Templates**: Convert ERB templates to Go text/template format
-3. **Configuration**: Map Jive environment variables to MCP config
-4. **Scripts**: Provide migration utilities for seamless transition
-
-### Workflow Integration
-1. **Backward Compatibility**: Support existing Jive cache structure
-2. **Incremental Migration**: Allow gradual transition from Jive to MCP
-3. **Feature Parity**: Ensure all Jive features are available in MCP server
-4. **Enhanced Capabilities**: Leverage MCP for AI-assisted workflows
-
----
-
-## Future Enhancements
-
-### Phase 2 Features
-- **GitLab CI/CD Integration**: Pipeline management and monitoring
-- **Wiki Management**: GitLab wiki content operations
-- **Repository Operations**: File and branch management
-- **Notification System**: Real-time updates and webhooks
-- **Advanced Analytics**: Project and team productivity metrics
-
-### AI Assistant Integration
-- **Smart Suggestions**: AI-powered issue and MR recommendations
-- **Automated Labeling**: Intelligent label assignment
-- **Code Review Assistant**: AI-enhanced code review workflows
-- **Progress Tracking**: Automated status updates and reporting
-- **Workflow Automation**: Custom automation based on patterns
-
----
-
-## Success Metrics
-
-### Technical Metrics
-- **Response Time**: < 100ms for cached operations, < 2s for API calls
-- **Reliability**: 99.9% uptime with proper error handling
-- **Compatibility**: 100% feature parity with Jive tool
-- **Performance**: Handle 1000+ issues/MRs without memory issues
-
-### User Experience Metrics
-- **Migration Time**: < 30 minutes from Jive to MCP setup
-- **Learning Curve**: < 1 hour to become productive with AI assistant
-- **Workflow Efficiency**: 50% reduction in manual GitLab operations
-- **Error Recovery**: Clear error messages with actionable solutions
-
-This design provides a comprehensive foundation for building a GitLab MCP server that combines the proven patterns from the Jive tool with the modern MCP architecture, enabling powerful AI-assisted GitLab workflows.
\ No newline at end of file
cmd/gitlab/README.md
@@ -1,287 +0,0 @@
-# GitLab MCP Server
-
-A comprehensive GitLab MCP server designed specifically for GitLab software engineers to manage their daily workflow with AI assistance.
-
-## Overview
-
-This server provides AI-powered access to GitLab APIs for:
-- **Project Discovery**: Find and organize projects you have access to
-- **Issue Management**: Track assigned, authored, and mentioned issues
-- **Conversation Tracking**: Follow issue discussions and threads
-- **Cross-Project Search**: Find similar issues across all your projects
-- **Activity Triage**: Get intelligent summaries of your recent work
-
-Perfect for GitLab employees who need to stay organized across multiple projects and issue threads.
-
-## Installation
-
-### Build and Install
-
-```bash
-# Build the GitLab server
-make gitlab
-
-# Install to system (optional)
-sudo make install
-```
-
-### Setup Authentication
-
-The server integrates with your existing GitLab authentication workflow:
-
-```bash
-# For GitLab employees (recommended)
-export-access-token # Sets GITLAB_TOKEN from your pass database
-mcp-gitlab # Start the server
-
-# Or set token manually
-export GITLAB_TOKEN=your_personal_access_token
-mcp-gitlab
-
-# Or specify token as argument
-mcp-gitlab --gitlab-token your_personal_access_token
-```
-
-## Configuration
-
-### Environment Variables
-
-- **`GITLAB_TOKEN`**: Personal Access Token (required)
-- **`GITLAB_URL`**: GitLab instance URL (default: https://gitlab.com)
-
-### Command Line Options
-
-```bash
-mcp-gitlab [options]
-
-Options:
- --gitlab-url string GitLab instance URL (default "https://gitlab.com")
- --gitlab-token string Personal Access Token (overrides GITLAB_TOKEN)
- --help Show help information
-```
-
-## Tools Reference
-
-### 1. `gitlab_list_my_projects`
-List projects you have access to with activity information.
-
-**Parameters:**
-- `limit` (string, optional): Number of projects to return (default: 20, max: 100)
-- `search` (string, optional): Search term for project names
-- `membership` (bool, optional): Only projects you're a member of
-- `archived` (bool, optional): Include archived projects
-
-**Example Output:**
-```
-Your GitLab Projects (15 found):
-
-**1. gitlab-org/gitlab**
- 🔗 https://gitlab.com/gitlab-org/gitlab
- 📊 342 open issues | ⭐ 23.1k stars | 🍴 5.2k forks
- 📅 Last activity: 2024-12-23 14:30
- 📝 The GitLab DevOps Platform...
-```
-
-### 2. `gitlab_list_my_issues`
-List issues assigned, authored, or mentioning you.
-
-**Parameters:**
-- `limit` (string, optional): Number of issues to return (default: 20, max: 100)
-- `scope` (string, optional): "assigned_to_me", "authored_by_me", "all_involving_me" (default: "assigned_to_me")
-- `state` (string, optional): "opened", "closed", "all" (default: "opened")
-- `search` (string, optional): Search term in issue titles/descriptions
-
-**Example Output:**
-```
-Your GitLab Issues (assigned_to_me, 8 found):
-
-**1. Fix authentication bug in SAML flow** 🎯
- 📁 gitlab-org/gitlab #123456
- 🔗 https://gitlab.com/gitlab-org/gitlab/-/issues/123456
- 👤 Author: John Doe | 👥 Assigned: You
- 🏷️ bug, authentication, saml
- 💬 12 comments | 📅 Updated: 2024-12-23 10:15
-```
-
-### 3. `gitlab_get_issue_conversations`
-Get detailed conversation thread for a specific issue.
-
-**Parameters:**
-- `project_id` (string, required): Project ID
-- `issue_iid` (string, required): Issue internal ID
-- `include_system_notes` (bool, optional): Include system notes (default: false)
-
-**Example Output:**
-```
-**Issue Conversation: Fix authentication bug in SAML flow**
-📁 gitlab-org/gitlab #123456 | 🔗 https://gitlab.com/gitlab-org/gitlab/-/issues/123456
-
-**Original Issue** - John Doe (2024-12-20 09:30)
-─────────────────────────────────────────────────
-Users are experiencing authentication failures when using SAML...
-
-**Issue Details:**
-• **State:** opened
-• **Assignees:** You
-• **Labels:** bug, authentication, saml
-• **Total Comments:** 12
-
-**Conversation Thread (12 comments):**
-
-💬 **Comment 1** - Jane Smith (2024-12-20 11:15)
-─────────────────────────────────────────────────
-I can reproduce this issue on staging...
-```
-
-### 4. `gitlab_find_similar_issues`
-Search for similar issues across all your accessible projects.
-
-**Parameters:**
-- `query` (string, required): Search query terms
-- `limit` (string, optional): Number of results (default: 10, max: 50)
-- `scope` (string, optional): Search scope (default: "issues")
-- `include_closed` (string, optional): Include closed issues ("true"/"false")
-
-**Example Output:**
-```
-**Similar Issues Found for: "authentication SAML"**
-Found 5 issues across 3 projects:
-
-**🗂️ Project 1: gitlab-org/gitlab** (3 issues)
-─────────────────────────────────────────────────
-1. 🟢 **SAML authentication timeout issues** opened
- 📋 #123457 | 👤 Alice Cooper | 👥 Bob Wilson
- 🏷️ authentication, saml, timeout
- 🔗 https://gitlab.com/gitlab-org/gitlab/-/issues/123457
- 📅 Updated: 2024-12-22 16:45
- 📝 Users experiencing timeouts during SAML auth...
-```
-
-### 5. `gitlab_get_my_activity`
-Get comprehensive activity summary with intelligent triage.
-
-**Parameters:**
-- `limit` (string, optional): Number of items to analyze (default: 20, max: 100)
-- `days` (string, optional): Days of history to analyze (default: 7, max: 30)
-
-**Example Output:**
-```
-**GitLab Activity Summary for Your Name**
-📅 Last 7 days | 👤 @your-username
-
-**📊 Quick Summary:**
-• Assigned Issues: 8 open
-• Authored Issues: 3 open
-• Recent Activity Events: 15
-
-**🎯 Items Needing Attention:**
-💬 **Issues with Recent Comments:**
- • gitlab-org/gitlab #123456 - Fix auth bug (5 comments)
- • security/security #789 - Review MR permissions (2 comments)
-
-**📋 Assigned Issues (8):**
-1. **Fix authentication bug in SAML flow** - gitlab-org/gitlab #123456
- 📅 Dec 23 | 💬 12 comments | 🏷️ bug, authentication, saml
-```
-
-## Usage Examples
-
-### Daily Workflow Startup
-```bash
-# 1. Set up your environment
-export-access-token
-
-# 2. Start the MCP server
-mcp-gitlab
-
-# 3. In Claude Code, you can now ask:
-# - "What issues are assigned to me?"
-# - "Show me the latest comments on issue #123456 in project 12345"
-# - "Find similar issues to 'authentication timeout'"
-# - "Give me my activity summary for this week"
-```
-
-### Integration with Claude Code
-
-Add to your Claude Code configuration (~/.claude.json):
-
-```json
-{
- "mcpServers": {
- "gitlab": {
- "command": "/usr/local/bin/mcp-gitlab"
- }
- }
-}
-```
-
-Then you can use natural language with Claude:
-
-- **"What GitLab work do I need to focus on today?"** → Uses `gitlab_get_my_activity`
-- **"Show me projects I'm working on"** → Uses `gitlab_list_my_projects`
-- **"Find issues similar to this authentication bug"** → Uses `gitlab_find_similar_issues`
-- **"What's the latest discussion on issue #123 in project 456?"** → Uses `gitlab_get_issue_conversations`
-
-## Benefits for GitLab Engineers
-
-### 🎯 **Workflow Organization**
-- **Intelligent Triage**: Get AI-powered summaries of what needs attention
-- **Cross-Project Visibility**: See all your work across GitLab's many projects
-- **Priority Detection**: Automatically identify overdue issues and recent activity
-
-### 🔍 **Discovery & Context**
-- **Similar Issue Finding**: Avoid duplicates and find related work
-- **Conversation Catching**: Never miss important discussions
-- **Project Discovery**: Find relevant projects and track activity
-
-### 🤖 **AI Integration**
-- **Natural Language Interface**: Ask Claude about your GitLab work
-- **Smart Summarization**: Get context-aware summaries of issues and conversations
-- **Pattern Recognition**: AI helps identify relationships and priorities
-
-### ⚡ **Efficiency Gains**
-- **Single Interface**: Access all GitLab data through Claude Code
-- **Reduced Context Switching**: Stay in your development environment
-- **Automated Organization**: Let AI handle the triage and organization
-
-## Troubleshooting
-
-### Authentication Issues
-```bash
-# Check if token is set
-echo $GITLAB_TOKEN
-
-# Test token validity
-curl -H "Authorization: Bearer $GITLAB_TOKEN" https://gitlab.com/api/v4/user
-
-# For GitLab employees, ensure export-access-token works
-export-access-token
-echo $GITLAB_TOKEN # Should show your token
-```
-
-### Connection Issues
-```bash
-# Test with custom GitLab URL
-mcp-gitlab --gitlab-url https://your-gitlab-instance.com
-
-# Check GitLab API access
-curl -H "Authorization: Bearer $GITLAB_TOKEN" https://your-gitlab-instance.com/api/v4/projects
-```
-
-### Server Issues
-```bash
-# Test basic server functionality
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | mcp-gitlab
-
-# Expected: List of 5 tools
-```
-
-## Contributing
-
-This GitLab MCP server is part of the larger MCP project. See the main project README for contribution guidelines.
-
-## Support
-
-For GitLab employees: This server is designed to integrate seamlessly with your existing `export-access-token` workflow and GitLab development environment.
-
-For issues or feature requests, please file an issue in the main project repository.
\ No newline at end of file
cmd/maildir/DESIGN.md
@@ -1,376 +0,0 @@
-# Maildir MCP Server Design
-
-## Overview
-
-The Maildir MCP Server provides secure access to email archives stored in maildir format. It enables AI assistants to search, analyze, and extract insights from email data while maintaining strict privacy controls and security boundaries.
-
-## Problem Statement
-
-Email archives contain valuable personal and professional context that could enhance AI assistant capabilities:
-
-- **Communication Patterns**: Understanding relationships and interaction frequency
-- **Context Retrieval**: Finding relevant past conversations for current tasks
-- **Contact Management**: Extracting and organizing contact information
-- **Content Analysis**: Analyzing communication styles, topics, and sentiment
-- **Timeline Reconstruction**: Understanding project history through email threads
-
-However, email data is highly sensitive and requires:
-- Strong privacy controls and access restrictions
-- Efficient parsing of various email formats (MIME, HTML, plain text)
-- Respect for email threading and conversation structure
-- Metadata preservation while content filtering
-
-## Architecture
-
-### Maildir Format Support
-
-The server will support the standard maildir format:
-
-```
-/path/to/maildir/
-├── INBOX/
-│ ├── cur/ # Read messages
-│ ├── new/ # Unread messages
-│ └── tmp/ # Temporary files
-├── Sent/
-├── Drafts/
-├── Trash/
-└── [Custom Folders]/
-```
-
-**Filename Format**: `{timestamp}.{process_id}_{delivery_id}.{hostname},{unique_id}:2,{flags}`
-- Flags: `S` (Seen), `R` (Replied), `F` (Flagged), `T` (Trashed), `D` (Draft)
-
-### Core Components
-
-#### 1. Maildir Scanner
-- Recursively scan maildir directory structure
-- Index folder hierarchy and message counts
-- Track maildir state and changes
-- Support for both Maildir and Maildir++ formats
-
-#### 2. Email Parser
-- Parse RFC 2822 email messages
-- Extract headers (From, To, Subject, Date, Message-ID, etc.)
-- Handle MIME multipart messages
-- Extract plain text and HTML content
-- Preserve thread relationships (In-Reply-To, References)
-- Support various character encodings
-
-#### 3. Content Processor
-- Convert HTML to markdown for AI consumption
-- Extract and clean plain text content
-- Parse email signatures and quotes
-- Identify forwarded messages and replies
-- Extract attachments metadata (without content for security)
-
-#### 4. Search Engine
-- Full-text search across message content
-- Metadata filtering (date ranges, senders, folders)
-- Thread-aware search results
-- Fuzzy matching for contact names and subjects
-- Boolean search operators
-
-#### 5. Privacy Filter
-- Configurable PII detection and masking
-- Exclude sensitive folders (e.g., banking, legal)
-- Content sanitization options
-- Whitelist/blacklist for contact domains
-
-## MCP Tools
-
-### 1. `maildir_scan_folders`
-**Description**: Scan and list available maildir folders with message counts.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {
- "type": "string",
- "description": "Path to the maildir root directory"
- },
- "include_counts": {
- "type": "boolean",
- "default": true,
- "description": "Include message counts for each folder"
- }
- },
- "required": ["maildir_path"]
-}
-```
-
-**Output**: List of folders with metadata (path, message count, unread count)
-
-### 2. `maildir_list_messages`
-**Description**: List messages in a folder with pagination and filtering.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "folder": {"type": "string", "default": "INBOX"},
- "limit": {"type": "integer", "default": 50, "maximum": 200},
- "offset": {"type": "integer", "default": 0},
- "date_from": {"type": "string", "format": "date"},
- "date_to": {"type": "string", "format": "date"},
- "sender": {"type": "string"},
- "subject_contains": {"type": "string"},
- "unread_only": {"type": "boolean", "default": false}
- },
- "required": ["maildir_path"]
-}
-```
-
-**Output**: Paginated list of message headers and metadata
-
-### 3. `maildir_read_message`
-**Description**: Read full message content with optional content filtering.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "message_id": {"type": "string"},
- "include_html": {"type": "boolean", "default": false},
- "include_headers": {"type": "boolean", "default": true},
- "sanitize_content": {"type": "boolean", "default": true}
- },
- "required": ["maildir_path", "message_id"]
-}
-```
-
-**Output**: Full message with headers, content, and metadata
-
-### 4. `maildir_search_messages`
-**Description**: Full-text search across email content with advanced filtering.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "query": {"type": "string"},
- "folders": {"type": "array", "items": {"type": "string"}},
- "date_from": {"type": "string", "format": "date"},
- "date_to": {"type": "string", "format": "date"},
- "senders": {"type": "array", "items": {"type": "string"}},
- "limit": {"type": "integer", "default": 50, "maximum": 200},
- "sort_by": {"type": "string", "enum": ["date", "relevance"], "default": "relevance"}
- },
- "required": ["maildir_path", "query"]
-}
-```
-
-**Output**: Ranked search results with snippets and relevance scores
-
-### 5. `maildir_get_thread`
-**Description**: Retrieve complete email thread/conversation.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "message_id": {"type": "string"},
- "max_depth": {"type": "integer", "default": 50}
- },
- "required": ["maildir_path", "message_id"]
-}
-```
-
-**Output**: Thread structure with all related messages in chronological order
-
-### 6. `maildir_analyze_contacts`
-**Description**: Extract and analyze contact information and communication patterns.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "date_from": {"type": "string", "format": "date"},
- "date_to": {"type": "string", "format": "date"},
- "min_messages": {"type": "integer", "default": 2},
- "include_frequency": {"type": "boolean", "default": true}
- },
- "required": ["maildir_path"]
-}
-```
-
-**Output**: Contact list with email frequency, last contact date, and relationship strength
-
-### 7. `maildir_get_statistics`
-**Description**: Generate email usage statistics and insights.
-
-**Input Schema**:
-```json
-{
- "type": "object",
- "properties": {
- "maildir_path": {"type": "string"},
- "period": {"type": "string", "enum": ["week", "month", "year"], "default": "month"},
- "include_charts": {"type": "boolean", "default": false}
- },
- "required": ["maildir_path"]
-}
-```
-
-**Output**: Statistics on email volume, top contacts, response times, etc.
-
-## Security & Privacy
-
-### Access Control
-- Restrict access to explicitly authorized maildir paths
-- Validate all path operations to prevent directory traversal
-- Support for read-only access mode
-- Configurable folder exclusions
-
-### Content Filtering
-- Optional PII detection and masking (phone numbers, SSNs, etc.)
-- Email address anonymization options
-- Subject line sanitization
-- Attachment content exclusion (metadata only)
-
-### Configuration
-- User-defined sensitivity levels
-- Whitelist/blacklist for contact domains
-- Excluded folder patterns
-- Content filtering rules
-
-### Example Security Config
-```json
-{
- "allowed_paths": ["/home/user/.local/share/mail"],
- "excluded_folders": ["Banking", "Legal", "Medical"],
- "pii_masking": true,
- "contact_anonymization": false,
- "max_content_length": 10000,
- "excluded_extensions": [".exe", ".zip", ".pdf"]
-}
-```
-
-## Implementation Details
-
-### File System Operations
-- Efficient directory traversal with caching
-- Watch for maildir changes (new messages)
-- Handle corrupted or malformed email files gracefully
-- Support for compressed maildir archives
-
-### Email Parsing
-- Use Go's built-in `net/mail` package for basic parsing
-- Additional MIME parsing for multipart messages
-- Handle various character encodings (UTF-8, Latin-1, etc.)
-- Extract metadata while preserving original structure
-
-### Search Implementation
-- In-memory inverted index for fast text search
-- Bloom filters for efficient negative lookups
-- Fuzzy string matching for contact names
-- Regular expression support for advanced queries
-
-### Threading Algorithm
-- Parse References and In-Reply-To headers
-- Subject line normalization (Re:, Fwd: removal)
-- Handle broken threading gracefully
-- Support for multiple threading strategies
-
-## Performance Considerations
-
-### Caching Strategy
-- Cache folder structure and message counts
-- Index commonly accessed messages
-- Lazy loading of message content
-- TTL-based cache invalidation
-
-### Memory Management
-- Stream large messages to avoid memory issues
-- Pagination for large result sets
-- Configurable limits on search result size
-- Efficient string operations for content processing
-
-### Scalability
-- Support for maildir archives with millions of messages
-- Incremental indexing for new messages
-- Background processing for expensive operations
-- Rate limiting for resource-intensive queries
-
-## Error Handling
-
-### Graceful Degradation
-- Continue processing despite corrupted messages
-- Handle permission errors gracefully
-- Provide meaningful error messages for invalid queries
-- Fallback options for unsupported email formats
-
-### Logging & Monitoring
-- Structured logging for all operations
-- Performance metrics collection
-- Error rate tracking
-- Privacy-safe audit logging
-
-## Testing Strategy
-
-### Unit Tests
-- Email parsing with various MIME types
-- Maildir scanning with different folder structures
-- Search functionality with edge cases
-- Security validation for path traversal attempts
-
-### Integration Tests
-- Real maildir processing with sample data
-- Performance testing with large archives
-- Security testing with malicious inputs
-- Cross-platform compatibility testing
-
-### Test Data
-- Synthetic email corpus for testing
-- Various maildir layouts and formats
-- Corrupted email samples
-- Edge cases (empty folders, special characters)
-
-## Future Enhancements
-
-### Advanced Features
-- Email sentiment analysis
-- Automatic categorization and tagging
-- Smart contact grouping
-- Email scheduling analysis
-- Conversation summarization
-
-### Integration Options
-- Export to various formats (JSON, CSV, mbox)
-- Integration with external search engines
-- Contact synchronization with address books
-- Calendar event extraction from emails
-
-### Machine Learning
-- Spam/ham classification
-- Important message detection
-- Automatic reply suggestions
-- Writing style analysis
-
-## Compliance & Legal
-
-### Data Protection
-- GDPR compliance for EU users
-- Data retention policies
-- Right to be forgotten implementation
-- Consent management for contact analysis
-
-### Export/Import
-- Standard mailbox format support (mbox, EML)
-- Backup and restore functionality
-- Cross-platform migration tools
-- Format conversion utilities
-
-This design provides a comprehensive, secure, and privacy-conscious approach to email analysis while maintaining the flexibility needed for AI assistant integration.
cmd/maildir/README.md
@@ -1,398 +0,0 @@
-# Maildir MCP Server
-
-A Model Context Protocol (MCP) server that provides secure email management through the Maildir format with comprehensive email analysis capabilities.
-
-## Overview
-
-The Maildir MCP server enables AI assistants to interact with email data stored in Maildir format through a standardized protocol. It provides tools for scanning folders, reading messages, searching emails, analyzing contacts, and generating statistics while maintaining privacy and security.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make maildir
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-maildir ./cmd/maildir
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-maildir --maildir-path <path1> [--maildir-path <path2> ...]
-```
-
-**Required Arguments:**
-- `--maildir-path <path>`: Path to Maildir directory (can be repeated for multiple mailboxes)
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-
-# List maildir resources
-echo '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-
-# Scan folders
-echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "maildir_scan_folders", "arguments": {"maildir_path": "~/.local/share/mail"}}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-#### Multiple Mailboxes
-```bash
-# Handle multiple email accounts
-mcp-maildir --maildir-path ~/.local/share/mail/personal --maildir-path ~/.local/share/mail/work
-```
-
-#### Email Operations Testing
-```bash
-# List messages in INBOX
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_list_messages", "arguments": {"maildir_path": "~/.local/share/mail", "folder": "INBOX", "limit": 10}}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-
-# Search for emails
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_search_messages", "arguments": {"maildir_path": "~/.local/share/mail", "query": "important meeting"}}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-
-# Get statistics
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "maildir_get_statistics", "arguments": {"maildir_path": "~/.local/share/mail"}}}' | timeout 5s mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-## Available Tools
-
-### Folder Management
-- **`maildir_scan_folders`**: Scan and list all Maildir folders
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `include_counts` (optional): Include message and unread counts (default: true)
- - **Returns:** List of folders with metadata
-
-### Message Operations
-- **`maildir_list_messages`**: List messages in a specific folder
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `folder` (optional): Folder name (default: "INBOX")
- - `limit` (optional): Maximum messages to return (max: 200, default: 50)
- - `offset` (optional): Number of messages to skip (default: 0)
- - `date_from` (optional): Filter messages from date (YYYY-MM-DD format)
- - `date_to` (optional): Filter messages to date (YYYY-MM-DD format)
- - `sender` (optional): Filter by sender email/name
- - `subject_contains` (optional): Filter by subject content
- - `unread_only` (optional): Show only unread messages (default: false)
- - **Returns:** Paginated list of message metadata
-
-- **`maildir_read_message`**: Read full message content
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `message_id` (required): Message ID (filename)
- - `include_html` (optional): Include HTML body if available (default: false)
- - `include_headers` (optional): Include email headers (default: true)
- - `sanitize_content` (optional): Apply privacy sanitization (default: true)
- - **Returns:** Complete message with headers and body
-
-### Search and Analysis
-- **`maildir_search_messages`**: Search messages by content
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `query` (required): Search query string
- - `limit` (optional): Maximum results to return (max: 200, default: 50)
- - `search_headers` (optional): Include headers in search (default: true)
- - `search_body` (optional): Include body in search (default: true)
- - **Returns:** Search results with message metadata
-
-- **`maildir_get_thread`**: Get email thread for a message
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `message_id` (required): Starting message ID
- - `max_depth` (optional): Maximum thread depth (default: 50)
- - **Returns:** Thread of related messages
-
-### Contact and Statistics
-- **`maildir_analyze_contacts`**: Analyze contact interactions
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `min_messages` (optional): Minimum message count for inclusion (default: 1)
- - `date_range` (optional): Analyze contacts within date range
- - **Returns:** Contact analysis with interaction statistics
-
-- **`maildir_get_statistics`**: Generate mailbox statistics
- - **Parameters:**
- - `maildir_path` (required): Path to the Maildir directory
- - `include_folders` (optional): Include per-folder statistics (default: true)
- - `include_time_analysis` (optional): Include time-based analysis (default: false)
- - **Returns:** Comprehensive mailbox statistics
-
-## Resources
-
-The server provides `maildir://` resources for:
-
-### Maildir Resources
-- **URI Format**: `maildir://<maildir_path>`
-- **Example**: `maildir:///home/user/.local/share/mail/personal`
-- **Description:** Access to Maildir folders and their metadata
-
-## Maildir Format Support
-
-### Standard Structure
-```
-maildir/
-├── cur/ # Current messages (read)
-├── new/ # New messages (unread)
-├── tmp/ # Temporary files
-└── .folder/ # Subfolders
- ├── cur/
- ├── new/
- └── tmp/
-```
-
-### Message Flags
-- **S**: Seen (read)
-- **R**: Replied
-- **F**: Flagged (important)
-- **T**: Trashed (deleted)
-- **D**: Draft
-- **P**: Passed (forwarded)
-
-### Folder Detection
-Automatically detects standard Maildir folders:
-- **INBOX**: Main inbox folder
-- **Sent**: Sent messages
-- **Drafts**: Draft messages
-- **Trash**: Deleted messages
-- **Custom folders**: User-created folders
-
-## Privacy and Security Features
-
-### Content Sanitization
-- **PII Masking**: Automatic detection and masking of sensitive information
-- **Phone Number Masking**: XXX-XXX-XXXX pattern replacement
-- **SSN Masking**: XXX-XX-XXXX pattern replacement
-- **Custom Patterns**: Configurable sanitization rules
-
-### Access Control
-- **Path Restrictions**: Only allowed Maildir paths are accessible
-- **No Modification**: Read-only access to email data
-- **Safe Parsing**: Robust email parsing with error handling
-- **Size Limits**: Prevents processing of extremely large emails
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "maildir": {
- "command": "/usr/local/bin/mcp-maildir",
- "args": ["--maildir-path", "/home/user/.local/share/mail"]
- }
- }
-}
-```
-
-### Multiple Email Accounts
-```json
-{
- "mcpServers": {
- "email-personal": {
- "command": "/usr/local/bin/mcp-maildir",
- "args": ["--maildir-path", "/home/user/.local/share/mail/personal"]
- },
- "email-work": {
- "command": "/usr/local/bin/mcp-maildir",
- "args": ["--maildir-path", "/home/user/.local/share/mail/work"]
- }
- }
-}
-```
-
-### Combined Mailboxes
-```json
-{
- "mcpServers": {
- "all-email": {
- "command": "/usr/local/bin/mcp-maildir",
- "args": [
- "--maildir-path", "/home/user/.local/share/mail/personal",
- "--maildir-path", "/home/user/.local/share/mail/work",
- "--maildir-path", "/home/user/.local/share/mail/lists"
- ]
- }
- }
-}
-```
-
-## Example Workflows
-
-### Email Management
-```bash
-# Get overview of mailbox
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_scan_folders", "arguments": {"maildir_path": "~/.local/share/mail", "include_counts": true}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Check unread messages
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_list_messages", "arguments": {"maildir_path": "~/.local/share/mail", "folder": "INBOX", "unread_only": true, "limit": 20}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Read specific message
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "maildir_read_message", "arguments": {"maildir_path": "~/.local/share/mail", "message_id": "1701439800.12345_1.hostname", "include_headers": true}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-### Email Search and Analysis
-```bash
-# Search for project-related emails
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_search_messages", "arguments": {"maildir_path": "~/.local/share/mail", "query": "project alpha", "limit": 50}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Find emails from specific date range
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_list_messages", "arguments": {"maildir_path": "~/.local/share/mail", "date_from": "2023-12-01", "date_to": "2023-12-31", "limit": 100}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Analyze most frequent contacts
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "maildir_analyze_contacts", "arguments": {"maildir_path": "~/.local/share/mail", "min_messages": 5}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-### Thread and Conversation Analysis
-```bash
-# Get email thread
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_get_thread", "arguments": {"maildir_path": "~/.local/share/mail", "message_id": "1701439800.12345_1.hostname", "max_depth": 20}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Search conversation history
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_search_messages", "arguments": {"maildir_path": "~/.local/share/mail", "query": "from:john@example.com"}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-### Statistics and Reporting
-```bash
-# Get mailbox statistics
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_get_statistics", "arguments": {"maildir_path": "~/.local/share/mail", "include_folders": true}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-
-# Analyze email patterns
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_analyze_contacts", "arguments": {"maildir_path": "~/.local/share/mail"}}}' | mcp-maildir --maildir-path ~/.local/share/mail
-```
-
-## Advanced Features
-
-### Email Parsing
-- **MIME Support**: Full MIME multipart message support
-- **Encoding Handling**: Proper handling of various text encodings
-- **HTML Processing**: Conversion of HTML emails to plain text
-- **Attachment Detection**: Identification of email attachments (metadata only)
-
-### Search Capabilities
-- **Full-Text Search**: Search across headers, subject, and body
-- **Field-Specific Search**: Search within specific email fields
-- **Date Range Filtering**: Filter messages by date ranges
-- **Sender/Recipient Filtering**: Filter by email participants
-- **Case-Insensitive**: Flexible search matching
-
-### Performance Optimization
-- **Lazy Loading**: Folders and messages loaded on demand
-- **Pagination**: Efficient handling of large mailboxes
-- **Caching**: Smart caching of folder metadata
-- **Resource Limits**: Configurable limits to prevent resource exhaustion
-
-## Common Email Clients
-
-### Compatible Email Clients
-- **Mutt**: Terminal-based email client
-- **Thunderbird**: Cross-platform email client (with Maildir support)
-- **Evolution**: GNOME email client
-- **Claws Mail**: Lightweight email client
-- **OfflineIMAP**: IMAP to Maildir synchronization
-- **mbsync/isync**: Mailbox synchronization utility
-
-### Setting up Maildir
-```bash
-# Create Maildir structure
-mkdir -p ~/.local/share/mail/{cur,new,tmp}
-
-# Use with OfflineIMAP
-offlineimap -c ~/.offlineimaprc
-
-# Use with mbsync
-mbsync -a
-```
-
-## Performance
-
-- **Startup Time**: ~1ms (lazy loading)
-- **Memory Usage**: <10MB for typical mailboxes
-- **Search Performance**: Fast full-text search with indexing
-- **Scalability**: Handles mailboxes with 100K+ messages
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Maildir not found" errors**
- ```bash
- # Check if path exists and has proper structure
- ls -la ~/.local/share/mail
- ls -la ~/.local/share/mail/{cur,new,tmp}
- ```
-
-2. **"Permission denied" errors**
- ```bash
- # Check file permissions
- ls -la ~/.local/share/mail
- chmod -R 755 ~/.local/share/mail
- ```
-
-3. **"No messages found"**
- ```bash
- # Verify Maildir contains messages
- ls ~/.local/share/mail/cur/
- ls ~/.local/share/mail/new/
- ```
-
-4. **"Invalid message format"**
- ```bash
- # Check message file format
- head -20 ~/.local/share/mail/cur/some_message_file
- ```
-
-### Debugging
-```bash
-# Test basic folder scanning
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "maildir_scan_folders", "arguments": {"maildir_path": "/path/to/maildir"}}}' | mcp-maildir --maildir-path /path/to/maildir
-
-# Test message listing
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "maildir_list_messages", "arguments": {"maildir_path": "/path/to/maildir", "limit": 1}}}' | mcp-maildir --maildir-path /path/to/maildir
-```
-
-## Best Practices
-
-1. **Backup First**: Always backup email data before processing
-2. **Use Absolute Paths**: Specify full paths to avoid ambiguity
-3. **Monitor Resources**: Be aware of memory usage with large mailboxes
-4. **Regular Cleanup**: Clean up old messages to maintain performance
-5. **Privacy Awareness**: Enable content sanitization for sensitive data
-
-## Security Considerations
-
-- **Read-Only Access**: Server provides read-only access to email data
-- **Path Validation**: All paths are validated to prevent directory traversal
-- **Content Sanitization**: Optional PII masking for privacy protection
-- **No Network Access**: Server does not make external network connections
-- **Safe Parsing**: Robust email parsing prevents malformed message exploits
-
-## Use Cases
-
-- **Email Analysis**: Analyze email patterns and communication trends
-- **Contact Management**: Identify and analyze email contacts
-- **Information Retrieval**: Search and extract information from emails
-- **Productivity Analysis**: Understand email usage patterns
-- **Archive Management**: Organize and manage email archives
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/memory/README.md
@@ -1,365 +0,0 @@
-# Memory MCP Server
-
-A Model Context Protocol (MCP) server that provides persistent knowledge graph management with entities, relations, and observations.
-
-## Overview
-
-The Memory MCP server enables AI assistants to maintain persistent knowledge through a graph-based memory system. It supports creating entities, establishing relationships, adding observations, and querying the knowledge graph for intelligent context retention across conversations.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make memory
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-memory ./cmd/memory
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-memory [--memory-file <path>]
-```
-
-**Optional Arguments:**
-- `--memory-file <path>`: Path to JSON file for persistent storage (default: `~/.mcp-memory.json`)
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-memory
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-memory
-
-# List memory resources
-echo '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}' | timeout 5s mcp-memory
-
-# Read the knowledge graph
-echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "read_graph", "arguments": {}}}' | timeout 5s mcp-memory
-```
-
-#### Custom Memory File
-```bash
-# Use a specific file for storage
-mcp-memory --memory-file /home/user/my-knowledge.json
-```
-
-#### Knowledge Management Testing
-```bash
-# Create entities
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_entities", "arguments": {"entities": [{"name": "Alice", "entityType": "person", "observations": ["Works as a software engineer", "Lives in San Francisco"]}]}}}' | timeout 5s mcp-memory
-
-# Create relationships
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_relations", "arguments": {"relations": [{"from": "Alice", "to": "Python", "relationType": "uses"}]}}}' | timeout 5s mcp-memory
-
-# Search for entities
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search_nodes", "arguments": {"query": "software engineer"}}}' | timeout 5s mcp-memory
-```
-
-## Available Tools
-
-### Entity Management
-- **`create_entities`**: Create new entities with observations
-- **`add_observations`**: Add observations to existing entities
-- **`delete_entities`**: Remove entities from the knowledge graph
-- **`open_nodes`**: Retrieve detailed information about specific entities
-
-### Relationship Management
-- **`create_relations`**: Establish relationships between entities
-- **`delete_relations`**: Remove relationships from the knowledge graph
-
-### Knowledge Exploration
-- **`read_graph`**: Get overview of the entire knowledge graph
-- **`search_nodes`**: Search entities by name, type, or observations
-
-### Observation Management
-- **`delete_observations`**: Remove specific observations from entities
-
-## Resources
-
-The server provides `memory://` resources for:
-
-### Knowledge Graph Resource
-- **URI Format**: `memory://graph`
-- **Description**: Access to the complete knowledge graph with entities and relations
-- **Content**: JSON representation of all entities, relations, and observations
-
-## Prompts
-
-### Knowledge Query Interface
-- **`knowledge-query`**: Interactive prompt for exploring the knowledge graph
- - Natural language queries about stored information
- - Context-aware search across entities and observations
- - Relationship discovery and exploration
-
-## Data Model
-
-### Entities
-```json
-{
- "name": "entity_name",
- "entityType": "type",
- "observations": ["observation1", "observation2"]
-}
-```
-
-### Relations
-```json
-{
- "from": "source_entity",
- "to": "target_entity",
- "relationType": "relationship_type"
-}
-```
-
-### Knowledge Graph Structure
-```json
-{
- "entities": {
- "entity_name": {
- "name": "entity_name",
- "entityType": "type",
- "observations": ["list", "of", "observations"]
- }
- },
- "relations": {
- "relation_id": {
- "from": "source",
- "to": "target",
- "relationType": "type"
- }
- }
-}
-```
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "memory": {
- "command": "/usr/local/bin/mcp-memory"
- }
- }
-}
-```
-
-### Custom Memory File
-```json
-{
- "mcpServers": {
- "memory": {
- "command": "/usr/local/bin/mcp-memory",
- "args": ["--memory-file", "/home/user/ai-memory.json"]
- }
- }
-}
-```
-
-### Project-Specific Memory
-```json
-{
- "mcpServers": {
- "project-memory": {
- "command": "/usr/local/bin/mcp-memory",
- "args": ["--memory-file", "/home/user/projects/myapp/knowledge.json"]
- }
- }
-}
-```
-
-## Example Workflows
-
-### Building a Knowledge Base
-```bash
-# Create people entities
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_entities", "arguments": {"entities": [{"name": "Alice", "entityType": "person", "observations": ["Software engineer", "Loves Python", "Works remotely"]}, {"name": "Bob", "entityType": "person", "observations": ["Product manager", "Lives in NYC", "Enjoys hiking"]}]}}}' | mcp-memory
-
-# Create project entities
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_entities", "arguments": {"entities": [{"name": "ProjectX", "entityType": "project", "observations": ["Web application", "Uses React and Node.js", "Due in Q2"]}]}}}' | mcp-memory
-
-# Establish relationships
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "create_relations", "arguments": {"relations": [{"from": "Alice", "to": "ProjectX", "relationType": "works_on"}, {"from": "Bob", "to": "ProjectX", "relationType": "manages"}]}}}' | mcp-memory
-```
-
-### Knowledge Exploration
-```bash
-# Search for people
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_nodes", "arguments": {"query": "engineer"}}}' | mcp-memory
-
-# Get detailed information about Alice
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "open_nodes", "arguments": {"names": ["Alice"]}}}' | mcp-memory
-
-# View the entire knowledge graph
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "read_graph", "arguments": {}}}' | mcp-memory
-```
-
-### Updating Knowledge
-```bash
-# Add new observations to Alice
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "add_observations", "arguments": {"entityName": "Alice", "observations": ["Completed Python certification", "Mentoring junior developers"]}}}' | mcp-memory
-
-# Create new relationships
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_relations", "arguments": {"relations": [{"from": "Alice", "to": "Python", "relationType": "expert_in"}]}}}' | mcp-memory
-```
-
-### Knowledge Cleanup
-```bash
-# Remove specific observations
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "delete_observations", "arguments": {"entityName": "Alice", "observations": ["Old outdated info"]}}}' | mcp-memory
-
-# Remove relationships
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "delete_relations", "arguments": {"relations": [{"from": "Alice", "to": "OldProject", "relationType": "worked_on"}]}}}' | mcp-memory
-
-# Remove entire entities
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "delete_entities", "arguments": {"entityNames": ["ObsoleteEntity"]}}}' | mcp-memory
-```
-
-## Advanced Features
-
-### Search Capabilities
-- **Entity Name Search**: Find entities by partial name matching
-- **Type-based Search**: Filter entities by their type
-- **Observation Search**: Search within observation text
-- **Relationship Discovery**: Find connected entities
-
-### Persistence
-- **Automatic Saving**: Changes are automatically persisted to disk
-- **JSON Format**: Human-readable storage format
-- **Backup Support**: File-based storage enables easy backups
-- **Version Control**: JSON files can be version controlled
-
-### Memory Efficiency
-- **Lazy Loading**: Knowledge graph loaded only when needed
-- **Selective Loading**: Load only requested parts of the graph
-- **Memory Limits**: Configurable limits for large knowledge bases
-
-## Data Storage
-
-### Default Location
-```bash
-~/.mcp-memory.json
-```
-
-### Custom Locations
-```bash
-# Project-specific memory
-mcp-memory --memory-file ./project-knowledge.json
-
-# Shared memory location
-mcp-memory --memory-file /shared/team-knowledge.json
-
-# Backup location
-mcp-memory --memory-file /backup/ai-memory-$(date +%Y%m%d).json
-```
-
-### File Format
-The memory file is stored as JSON with the following structure:
-```json
-{
- "entities": {
- "Alice": {
- "name": "Alice",
- "entityType": "person",
- "observations": ["Software engineer", "Loves Python"]
- }
- },
- "relations": {
- "rel_1": {
- "from": "Alice",
- "to": "Python",
- "relationType": "uses"
- }
- }
-}
-```
-
-## Performance
-
-- **Startup Time**: ~1ms (lazy loading)
-- **Memory Usage**: <5MB for typical knowledge graphs
-- **Storage Efficiency**: JSON compression for large graphs
-- **Query Performance**: In-memory search for fast responses
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Memory file not found**
- ```bash
- # Check if file exists and is readable
- ls -la ~/.mcp-memory.json
-
- # Create with proper permissions if needed
- touch ~/.mcp-memory.json
- chmod 644 ~/.mcp-memory.json
- ```
-
-2. **JSON parsing errors**
- ```bash
- # Validate JSON format
- jq . ~/.mcp-memory.json
-
- # Backup and reset if corrupted
- cp ~/.mcp-memory.json ~/.mcp-memory.json.backup
- echo '{"entities":{},"relations":{}}' > ~/.mcp-memory.json
- ```
-
-3. **Permission errors**
- ```bash
- # Check file permissions
- ls -la ~/.mcp-memory.json
-
- # Fix permissions
- chmod 644 ~/.mcp-memory.json
- ```
-
-### Backup and Recovery
-```bash
-# Create backup
-cp ~/.mcp-memory.json ~/.mcp-memory-backup-$(date +%Y%m%d).json
-
-# Restore from backup
-cp ~/.mcp-memory-backup-20231201.json ~/.mcp-memory.json
-
-# Reset memory (caution: destroys all data)
-echo '{"entities":{},"relations":{}}' > ~/.mcp-memory.json
-```
-
-## Best Practices
-
-1. **Regular Backups**: Backup memory files before major changes
-2. **Meaningful Names**: Use descriptive entity names and types
-3. **Structured Observations**: Keep observations concise and factual
-4. **Relationship Types**: Use consistent relationship type naming
-5. **Cleanup**: Regularly remove outdated entities and observations
-6. **Version Control**: Store memory files in version control for shared projects
-
-## Use Cases
-
-- **Personal Knowledge Management**: Track people, projects, and ideas
-- **Research Notes**: Organize research findings and connections
-- **Project Documentation**: Maintain project context and relationships
-- **Learning Journals**: Record learning progress and connections
-- **Team Knowledge**: Share institutional knowledge across team members
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/semantic/DESIGN.md
@@ -1,1073 +0,0 @@
-# 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/semantic/IMPLEMENTATION_PLAN.md
@@ -1,335 +0,0 @@
-# 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) ✅ COMPLETE
-**Goal**: Symbol relationship analysis and cross-references
-
-**Deliverables:**
-- [x] Reference analysis tools
-- [x] Call hierarchy understanding
-- [x] Dependency mapping
-- [x] Performance optimization
-
-**Tools to Implement:**
-- [x] `semantic_get_references` - Find symbol usage
-- [x] `semantic_get_call_hierarchy` - Call relationships
-- [x] `semantic_analyze_dependencies` - Project dependencies
-
-**Technical Tasks:**
-- [x] Implement cross-reference analysis via LSP
-- [x] Build symbol relationship graph
-- [x] Add efficient symbol indexing
-- [x] 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 ✅
-- [x] Project structure and basic MCP framework
-- [x] LSP client implementation for Go, Rust, Ruby
-- [x] Basic symbol discovery tools (semantic_find_symbol, semantic_get_overview, semantic_get_definition)
-- [x] Core caching mechanism with file watching
-- [x] Unit and integration tests
-
-### Phase 2: Analysis ✅
-- [x] Reference analysis via LSP (semantic_get_references)
-- [x] Call hierarchy tools (semantic_get_call_hierarchy)
-- [x] Symbol relationship mapping (semantic_analyze_dependencies)
-- [x] Performance optimization and LSP enhancement
-
-### 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/semantic/README.md
@@ -1,272 +0,0 @@
-# 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:**
-
-- [x] **Phase 1**: Core symbol discovery and basic editing tools
-- [x] **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:** ✅ **Phase 2 Complete** - Analysis and relationship tools implemented
-
-## 🤝 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
cmd/sequential-thinking/README.md
@@ -1,361 +0,0 @@
-# Sequential Thinking MCP Server
-
-A Model Context Protocol (MCP) server that provides structured thinking workflows with persistent session management and branch tracking for AI assistants to break down complex problems step-by-step.
-
-## Overview
-
-The Sequential Thinking MCP server enables AI assistants to engage in structured, step-by-step reasoning through a standardized protocol. It provides tools for organizing thoughts, breaking down complex problems, maintaining logical flow in problem-solving processes, and **persisting thought history across sessions** with full **branch tracking** for alternative reasoning paths.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make sequential-thinking
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-sequential-thinking ./cmd/sequential-thinking
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-sequential-thinking [--session-file <path>] [--help]
-```
-
-**Options:**
-- `--session-file <path>`: Optional file path for persisting thinking sessions across server restarts
-- `--help`: Show help message with usage information
-
-**Example:**
-```bash
-# Run without persistence (sessions lost on restart)
-mcp-sequential-thinking
-
-# Run with session persistence
-mcp-sequential-thinking --session-file /path/to/sessions.json
-```
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-sequential-thinking
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-sequential-thinking
-
-# Start a thinking process
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"problem": "How to design a scalable web application?"}}}' | timeout 5s mcp-sequential-thinking
-```
-
-#### Sequential Thinking Process
-```bash
-# Start a thinking session with first thought
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "I need to analyze whether migrating to microservices makes sense for our current system", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 5}}}' | timeout 5s mcp-sequential-thinking
-
-# Continue with second thought (sessionId will be returned from first call)
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Let me first evaluate our current monolith - it serves 10M users with a team of 50 developers", "nextThoughtNeeded": true, "thoughtNumber": 2, "totalThoughts": 5, "sessionId": "session_123456789"}}}' | timeout 5s mcp-sequential-thinking
-
-# Create a branch for alternative reasoning
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "What if we consider a hybrid approach instead of full microservices?", "nextThoughtNeeded": true, "thoughtNumber": 3, "totalThoughts": 4, "branchFromThought": 2, "branchId": "hybrid-approach", "sessionId": "session_123456789"}}}' | timeout 5s mcp-sequential-thinking
-```
-
-## Available Tools
-
-### Core Thinking Tool
-- **`sequentialthinking`**: Engage in step-by-step problem analysis with session persistence
- - **Parameters:**
- - `thought` (required): Your current thinking step
- - `nextThoughtNeeded` (required): Whether another thought step is needed
- - `thoughtNumber` (required): Current thought number (1-based)
- - `totalThoughts` (required): Estimated total thoughts needed
- - `isRevision` (optional): Whether this revises previous thinking
- - `revisesThought` (optional): Which thought number is being reconsidered
- - `branchFromThought` (optional): Branching point thought number
- - `branchId` (optional): Branch identifier for alternative reasoning paths
- - `needsMoreThoughts` (optional): If more thoughts are needed beyond initial estimate
- - `sessionId` (optional): Session ID for thought continuity (auto-generated if not provided)
- - **Returns:** Structured thinking process with session context and persistence
-
-### Session Management Tools
-- **`get_session_history`**: Get the complete thought history for a thinking session
- - **Parameters:**
- - `sessionId` (required): Session ID to get history for
- - **Returns:** Complete session data with all thoughts and metadata
-
-- **`list_sessions`**: List all active thinking sessions
- - **Parameters:** None
- - **Returns:** Array of all sessions with summary information
-
-- **`get_branch_history`**: Get the thought history for a specific reasoning branch
- - **Parameters:**
- - `branchId` (required): Branch ID to get history for
- - **Returns:** Complete branch data with all thoughts and metadata
-
-- **`clear_session`**: Clear a thinking session and all its branches
- - **Parameters:**
- - `sessionId` (required): Session ID to clear
- - **Returns:** Confirmation message with cleared session details
-
-## Thinking Frameworks
-
-### Problem Types
-- **Technical Problems**: Software design, architecture decisions, debugging
-- **Business Problems**: Strategic decisions, process optimization, market analysis
-- **Creative Problems**: Brainstorming, innovation, design thinking
-- **Analytical Problems**: Data analysis, research, hypothesis testing
-
-### Depth Levels
-1. **Surface (1)**: Basic overview and immediate considerations
-2. **Standard (2)**: Common approach with key factors identified
-3. **Detailed (3)**: Comprehensive analysis with multiple perspectives (default)
-4. **Deep (4)**: Thorough examination with edge cases and implications
-5. **Exhaustive (5)**: Complete analysis with all possible angles and contingencies
-
-### Focus Areas
-- **Technical**: Implementation details, architecture, performance, scalability
-- **Business**: ROI, market impact, stakeholder concerns, strategic alignment
-- **Creative**: Innovation, user experience, design alternatives, brainstorming
-- **Analytical**: Data-driven insights, metrics, testing, validation
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "sequential-thinking": {
- "command": "/usr/local/bin/mcp-sequential-thinking"
- }
- }
-}
-```
-
-### With Session Persistence
-```json
-{
- "mcpServers": {
- "sequential-thinking": {
- "command": "/usr/local/bin/mcp-sequential-thinking",
- "args": ["--session-file", "/home/user/.mcp/thinking-sessions.json"]
- }
- }
-}
-```
-
-## Example Workflows
-
-### Basic Sequential Thinking
-```bash
-# Start a new thinking session
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "I need to decide whether to implement caching for our API", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 4}}}' | mcp-sequential-thinking
-
-# Continue the thinking process
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Current performance metrics show 500ms average response time with 10K requests/min", "nextThoughtNeeded": true, "thoughtNumber": 2, "totalThoughts": 4, "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-
-# Revise a previous thought
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Actually, let me reconsider - the 500ms includes database queries, not just API processing", "nextThoughtNeeded": true, "thoughtNumber": 3, "totalThoughts": 4, "isRevision": true, "revisesThought": 2, "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-```
-
-### Branching Alternative Approaches
-```bash
-# Create a branch for alternative reasoning
-echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "What if we optimize the database queries instead of adding caching?", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 3, "branchFromThought": 2, "branchId": "db-optimization", "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-
-# Continue in the branch
-echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Database optimization would require indexing and query restructuring", "nextThoughtNeeded": false, "thoughtNumber": 2, "totalThoughts": 3, "branchId": "db-optimization", "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-```
-
-### Session Management
-```bash
-# List all active sessions
-echo '{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "list_sessions", "arguments": {}}}' | mcp-sequential-thinking
-
-# Get complete history of a session
-echo '{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "get_session_history", "arguments": {"sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-
-# Get history of a specific branch
-echo '{"jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": {"name": "get_branch_history", "arguments": {"branchId": "db-optimization"}}}' | mcp-sequential-thinking
-
-# Clear a completed session
-echo '{"jsonrpc": "2.0", "id": 9, "method": "tools/call", "params": {"name": "clear_session", "arguments": {"sessionId": "session_1735056789"}}}' | mcp-sequential-thinking
-```
-
-## Advanced Features
-
-### Session Persistence
-- **Cross-Session Continuity**: Thinking sessions persist across server restarts
-- **JSON File Storage**: Sessions stored in human-readable JSON format
-- **Automatic Session IDs**: Unique session identifiers generated automatically
-- **Thread-Safe Operations**: Concurrent access to sessions handled safely
-
-### Branch Tracking
-- **Alternative Reasoning Paths**: Create branches from any thought in the main sequence
-- **Branch Isolation**: Each branch maintains its own thought sequence
-- **Branch Relationships**: Track which thought each branch originated from
-- **Cross-Branch Navigation**: Access both main session and branch histories
-
-### Enhanced Output Format
-- **Rich Visual Formatting**: Progress bars, emojis, and structured sections
-- **Session Context**: Always shows current session ID and branch information
-- **Structured JSON Data**: Programmatic access to all thinking data
-- **Solution Extraction**: Automatic extraction of solutions from final thoughts
-
-### Revision Support
-- **Thought Revision**: Mark thoughts as revisions of previous thoughts
-- **Revision Tracking**: Keep track of which thoughts were revised
-- **Context Preservation**: Revisions maintain context of original reasoning
-- **Dynamic Estimation**: Adjust total thought count as thinking evolves
-
-## Use Cases
-
-### Software Development
-- Architecture design decisions
-- Technology stack selection
-- Performance optimization strategies
-- Code review and refactoring plans
-- Testing strategy development
-
-### Product Management
-- Feature prioritization
-- User story analysis
-- Competitive analysis
-- Go-to-market strategy
-- Product roadmap planning
-
-### Business Strategy
-- Market entry decisions
-- Investment evaluations
-- Risk assessment
-- Process optimization
-- Team structure planning
-
-### Research and Development
-- Hypothesis formation
-- Experimental design
-- Literature review structure
-- Data analysis approaches
-- Innovation opportunities
-
-## Performance
-
-- **Startup Time**: <100ms (with session loading)
-- **Memory Usage**: <5MB (scales with session count)
-- **Response Time**: <50ms per tool call (excluding thinking time)
-- **Persistence**: Efficient JSON serialization for session storage
-- **Scalability**: Handles hundreds of concurrent sessions with branch tracking
-
-## Best Practices
-
-### Session Management
-1. **Plan Thought Sequence**: Estimate total thoughts needed at the start
-2. **Use Descriptive Thoughts**: Each thought should be self-contained and clear
-3. **Leverage Sessions**: Keep related thoughts in the same session
-4. **Clean Up Sessions**: Clear completed sessions to manage memory
-
-### Branch Strategy
-1. **Branch Strategically**: Create branches for major alternative approaches
-2. **Name Branches Clearly**: Use descriptive branch IDs like "cost-analysis" or "tech-alternative"
-3. **Track Branch Origins**: Note which thought triggered the need for branching
-4. **Compare Branches**: Use branch history to compare different reasoning paths
-
-### Revision Best Practices
-1. **Mark Revisions Clearly**: Always use `isRevision: true` when reconsidering
-2. **Reference Original**: Specify which thought is being revised
-3. **Explain Changes**: Make the revision reasoning explicit
-4. **Update Estimates**: Adjust total thoughts if revision changes the scope
-
-## Data Structures
-
-### Session Data
-```json
-{
- "id": "session_1735056789",
- "thoughts": [
- {
- "number": 1,
- "content": "Initial thought content",
- "isRevision": false,
- "needsMoreThoughts": false
- }
- ],
- "currentThought": 3,
- "totalThoughts": 5,
- "status": "active",
- "createdAt": "2024-12-25T10:30:00Z",
- "lastActivity": "2024-12-25T10:35:00Z",
- "activeBranches": ["branch-1", "branch-2"]
-}
-```
-
-### Branch Data
-```json
-{
- "id": "optimization-branch",
- "sessionId": "session_1735056789",
- "fromThought": 2,
- "thoughts": [
- {
- "number": 1,
- "content": "Alternative approach thought",
- "branchFromThought": 2,
- "branchId": "optimization-branch"
- }
- ],
- "createdAt": "2024-12-25T10:32:00Z",
- "lastActivity": "2024-12-25T10:34:00Z"
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Session not persisting**
- ```bash
- # Ensure session file is specified and writable
- mcp-sequential-thinking --session-file /writable/path/sessions.json
-
- # Check file permissions
- ls -la /path/to/sessions.json
- ```
-
-2. **Missing required parameters**
- ```bash
- # All these parameters are required for sequentialthinking tool:
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "My analysis of the problem", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 3}}}' | mcp-sequential-thinking
- ```
-
-3. **Branch creation without sessionId**
- ```bash
- # Branches require an existing session
- # First create/continue a session, get the sessionId from response
- # Then use that sessionId for branch creation
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Alternative approach", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 2, "branchFromThought": 3, "branchId": "alt-approach", "sessionId": "session_123456789"}}}' | mcp-sequential-thinking
- ```
-
-4. **Session ID not found**
- ```bash
- # List sessions to find correct ID
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_sessions", "arguments": {}}}' | mcp-sequential-thinking
-
- # Or check if persistence file exists and is readable
- cat /path/to/sessions.json
- ```
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file
cmd/signal/README.md
@@ -1,229 +0,0 @@
-# Signal MCP Server
-
-This MCP server provides secure access to Signal Desktop's encrypted database for reading conversations, searching messages, and analyzing communication history.
-
-## Features
-
-- **Encrypted Database Access**: Automatically handles Signal's SQLCipher encryption
-- **Cross-Platform Support**: Works on macOS, Linux, and Windows
-- **Conversation Management**: List and browse all conversations
-- **Message Search**: Full-text search across all messages
-- **Attachment Support**: Access to message attachments and media
-- **Statistics**: Database insights and usage statistics
-
-## Installation
-
-Build and install the Signal MCP server:
-
-```bash
-make signal
-sudo make install
-```
-
-This will install `mcp-signal` to `/usr/local/bin/`.
-
-## Prerequisites
-
-### Signal Desktop
-- Signal Desktop must be installed and configured
-- Database is automatically located in standard Signal paths:
- - **macOS**: `~/Library/Application Support/Signal/`
- - **Linux**: `~/.config/Signal/` (or Flatpak/Snap variants)
- - **Windows**: `%APPDATA%/Signal/`
-
-### Database Access
-- Signal Desktop should be closed for reliable database access
-- Requires system keychain access for encrypted key retrieval:
- - **macOS**: Uses Keychain Access via `security` command
- - **Linux**: Uses `secret-tool` or KDE wallet
-
-### Dependencies
-- SQLCipher support (handled by Go driver)
-- System keychain tools (platform-specific)
-
-## Usage
-
-### Basic Usage
-```bash
-# Auto-detect Signal installation
-mcp-signal
-
-# Specify custom Signal path
-mcp-signal --signal-path ~/.config/Signal
-```
-
-### Available Tools
-
-#### `signal_list_conversations`
-Lists all conversations with contact information.
-
-```json
-{
- "name": "signal_list_conversations",
- "arguments": {}
-}
-```
-
-#### `signal_search_messages`
-Search messages by text content with optional limits.
-
-```json
-{
- "name": "signal_search_messages",
- "arguments": {
- "query": "search term",
- "limit": "50"
- }
-}
-```
-
-#### `signal_get_conversation`
-Retrieve messages from a specific conversation.
-
-```json
-{
- "name": "signal_get_conversation",
- "arguments": {
- "conversation_id": "conversation-uuid",
- "limit": "100"
- }
-}
-```
-
-#### `signal_get_stats`
-Show database statistics and information.
-
-```json
-{
- "name": "signal_get_stats",
- "arguments": {}
-}
-```
-
-### Configuration Example
-
-Add to your Claude configuration (`~/.claude.json`):
-
-```json
-{
- "mcpServers": {
- "signal": {
- "command": "/usr/local/bin/mcp-signal"
- }
- }
-}
-```
-
-Or with custom Signal path:
-
-```json
-{
- "mcpServers": {
- "signal": {
- "command": "/usr/local/bin/mcp-signal",
- "args": ["--signal-path", "/custom/path/to/Signal"]
- }
- }
-}
-```
-
-## Security Considerations
-
-### Encryption
-- Signal database is encrypted with SQLCipher
-- Encryption keys are retrieved from:
- 1. `config.json` (plain text key)
- 2. System keychain (encrypted key)
-
-### Permissions
-- Requires read access to Signal application directory
-- May require keychain/credential manager access
-- Database should not be accessed while Signal is running
-
-### Privacy
-- All data remains local - no network access
-- Respects Signal's security model
-- Read-only access to database
-
-## Database Schema
-
-The Signal database contains several key tables:
-
-- **conversations**: Contact/group information
-- **messages**: Message content and metadata
-- **attachments**: File attachments and media
-
-Messages contain rich JSON data including:
-- Attachments and media files
-- Message reactions
-- Quoted messages
-- Stickers and GIFs
-
-## Troubleshooting
-
-### Database Access Issues
-```
-Error: failed to read encrypted database
-```
-- Ensure Signal Desktop is completely closed
-- Verify keychain access permissions
-- Check Signal path is correct
-
-### Key Decryption Issues
-```
-Error: failed to get Signal key
-```
-- **macOS**: Grant Terminal access to Keychain
-- **Linux**: Install and configure `secret-tool`
-- Check Signal configuration exists
-
-### Platform-Specific Issues
-
-#### macOS
-- May require granting Terminal access to Keychain
-- Use `security find-generic-password -ws "Signal Safe Storage"` to test
-
-#### Linux
-- Install secret-service tools: `sudo apt install libsecret-tools`
-- For KDE: May need KDE wallet integration
-
-#### Windows
-- Windows support may require additional credential manager integration
-
-## Development
-
-### Adding New Tools
-Follow the existing pattern in `pkg/signal/server.go`:
-
-```go
-server.RegisterTool("signal_new_tool", server.handleNewTool)
-```
-
-### Database Queries
-All database access should:
-- Check connection with `ensureConnection()`
-- Use prepared statements
-- Handle SQLCipher encryption properly
-- Filter out system messages
-
-### Testing
-```bash
-# Test database connection
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "signal_get_stats", "arguments": {}}}' | mcp-signal
-
-# Test message search
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "signal_search_messages", "arguments": {"query": "hello", "limit": "5"}}}' | mcp-signal
-```
-
-## Contributing
-
-This Signal MCP server is part of the larger MCP project. Contributions welcome:
-
-1. Follow existing code patterns
-2. Add appropriate error handling
-3. Update documentation
-4. Test across platforms
-
-## License
-
-Same license as the parent MCP project.
\ No newline at end of file
cmd/time/README.md
@@ -1,309 +0,0 @@
-# Time MCP Server
-
-A Model Context Protocol (MCP) server that provides comprehensive time and date utilities for AI assistants.
-
-## Overview
-
-The Time MCP server enables AI assistants to work with time-related operations through a standardized protocol. It provides tools for getting current time, converting between time zones, parsing dates, and performing time calculations.
-
-## Installation
-
-### From Source
-```bash
-# Build the binary
-make time
-
-# Install system-wide (requires sudo)
-sudo make install
-```
-
-### Direct Build
-```bash
-go build -o mcp-time ./cmd/time
-```
-
-## Usage
-
-### Command Line Arguments
-
-```bash
-mcp-time
-```
-
-**No arguments required** - The server provides time utilities without any configuration.
-
-### Examples
-
-#### Basic Testing
-```bash
-# Test server initialization
-echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-time
-
-# List available tools
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-time
-
-# Get current time
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | timeout 5s mcp-time
-```
-
-#### Time Operations Testing
-```bash
-# Get current time in specific timezone
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | timeout 5s mcp-time
-
-# Convert time between timezones
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00Z", "from_timezone": "UTC", "to_timezone": "America/Los_Angeles"}}}' | timeout 5s mcp-time
-
-# Get current time in multiple formats
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "RFC3339"}}}' | timeout 5s mcp-time
-```
-
-## Available Tools
-
-### Current Time
-- **`get_current_time`**: Get current date and time
- - **Parameters:**
- - `timezone` (optional): Target timezone (e.g., "America/New_York", "Europe/London")
- - `format` (optional): Output format ("RFC3339", "Unix", "ISO8601", "Human")
- - **Returns:** Current time in specified timezone and format
-
-### Time Conversion
-- **`convert_time`**: Convert time between different timezones and formats
- - **Parameters:**
- - `time` (required): Input time string or Unix timestamp
- - `from_timezone` (optional): Source timezone (defaults to UTC)
- - `to_timezone` (required): Target timezone
- - `format` (optional): Output format
- - **Returns:** Converted time in target timezone and format
-
-## Supported Timezones
-
-### Major Timezones
-- **UTC**: Coordinated Universal Time
-- **America/New_York**: Eastern Time (US & Canada)
-- **America/Chicago**: Central Time (US & Canada)
-- **America/Denver**: Mountain Time (US & Canada)
-- **America/Los_Angeles**: Pacific Time (US & Canada)
-- **Europe/London**: Greenwich Mean Time / British Summer Time
-- **Europe/Paris**: Central European Time
-- **Europe/Berlin**: Central European Time
-- **Asia/Tokyo**: Japan Standard Time
-- **Asia/Shanghai**: China Standard Time
-- **Asia/Kolkata**: India Standard Time
-- **Australia/Sydney**: Australian Eastern Time
-
-### Full IANA Support
-The server supports all IANA timezone identifiers. Common patterns:
-- **Continent/City**: `America/New_York`, `Europe/London`, `Asia/Tokyo`
-- **Regional**: `US/Eastern`, `US/Pacific`, `GMT`, `UTC`
-
-## Supported Formats
-
-### Input Formats
-- **RFC3339**: `2023-12-01T15:30:00Z`
-- **ISO8601**: `2023-12-01T15:30:00+00:00`
-- **Unix Timestamp**: `1701439800` (seconds since epoch)
-- **Human Readable**: `December 1, 2023 3:30 PM`
-
-### Output Formats
-- **RFC3339**: `2023-12-01T15:30:00Z`
-- **ISO8601**: `2023-12-01T15:30:00-08:00`
-- **Unix**: `1701439800`
-- **Human**: `Friday, December 1, 2023 at 3:30 PM PST`
-
-## Configuration Examples
-
-### Claude Desktop Integration
-```json
-{
- "mcpServers": {
- "time": {
- "command": "/usr/local/bin/mcp-time"
- }
- }
-}
-```
-
-### Multiple Time Services
-```json
-{
- "mcpServers": {
- "time-utils": {
- "command": "/usr/local/bin/mcp-time"
- }
- }
-}
-```
-
-## Example Workflows
-
-### Current Time Operations
-```bash
-# Get current UTC time
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | mcp-time
-
-# Get current time in New York
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | mcp-time
-
-# Get current time in multiple formats
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Europe/London", "format": "Human"}}}' | mcp-time
-
-# Get Unix timestamp
-echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
-```
-
-### Time Zone Conversions
-```bash
-# Convert UTC to Eastern Time
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T20:30:00Z", "from_timezone": "UTC", "to_timezone": "America/New_York"}}}' | mcp-time
-
-# Convert Eastern to Pacific Time
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00", "from_timezone": "America/New_York", "to_timezone": "America/Los_Angeles"}}}' | mcp-time
-
-# Convert to multiple timezones
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T12:00:00Z", "to_timezone": "Asia/Tokyo", "format": "Human"}}}' | mcp-time
-```
-
-### Business Hours Calculations
-```bash
-# Check if it's business hours in New York
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York", "format": "Human"}}}' | mcp-time
-
-# Get meeting time across timezones
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T14:00:00", "from_timezone": "America/New_York", "to_timezone": "Europe/London"}}}' | mcp-time
-
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T14:00:00", "from_timezone": "America/New_York", "to_timezone": "Asia/Tokyo"}}}' | mcp-time
-```
-
-### Unix Timestamp Operations
-```bash
-# Convert Unix timestamp to human readable
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "America/Los_Angeles", "format": "Human"}}}' | mcp-time
-
-# Get current Unix timestamp
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
-```
-
-## Advanced Features
-
-### Automatic Format Detection
-- **Smart Parsing**: Automatically detects input time format
-- **Flexible Input**: Accepts various common time formats
-- **Error Handling**: Clear error messages for invalid formats
-
-### Daylight Saving Time
-- **Automatic DST**: Handles daylight saving time transitions
-- **Historical Accuracy**: Correct DST rules for historical dates
-- **Future Dates**: Accurate predictions for future DST changes
-
-### High Precision
-- **Nanosecond Precision**: Full Go time precision support
-- **Leap Seconds**: Proper handling of leap seconds
-- **Time Zones**: Complete IANA timezone database support
-
-## Use Cases
-
-### Scheduling and Coordination
-```bash
-# Plan international meeting
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-05T09:00:00", "from_timezone": "America/New_York", "to_timezone": "Europe/London"}}}' | mcp-time
-
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-05T09:00:00", "from_timezone": "America/New_York", "to_timezone": "Asia/Tokyo"}}}' | mcp-time
-```
-
-### Log Analysis
-```bash
-# Convert log timestamps
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "America/Denver", "format": "Human"}}}' | mcp-time
-```
-
-### Business Operations
-```bash
-# Check current time in office locations
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York", "format": "Human"}}}' | mcp-time
-
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Europe/London", "format": "Human"}}}' | mcp-time
-
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Asia/Singapore", "format": "Human"}}}' | mcp-time
-```
-
-## Performance
-
-- **Startup Time**: ~1ms
-- **Memory Usage**: <5MB
-- **Response Time**: <1ms for time operations
-- **Timezone Data**: Built-in IANA timezone database
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Invalid timezone" errors**
- ```bash
- # Check valid timezone format
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "UTC"}}}' | mcp-time
-
- # Use IANA format: Continent/City
- echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | mcp-time
- ```
-
-2. **"Invalid time format" errors**
- ```bash
- # Use RFC3339 format for reliability
- echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00Z", "to_timezone": "UTC"}}}' | mcp-time
-
- # Or Unix timestamp
- echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "UTC"}}}' | mcp-time
- ```
-
-### Testing Time Operations
-```bash
-# Test basic functionality
-echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | mcp-time
-
-# Test timezone conversion
-echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-01-01T00:00:00Z", "to_timezone": "America/New_York"}}}' | mcp-time
-
-# Test format conversion
-echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
-```
-
-## Best Practices
-
-1. **Use IANA Timezones**: Always use standard IANA timezone identifiers
-2. **Specify Formats**: Explicitly specify input/output formats when possible
-3. **Handle DST**: Be aware of daylight saving time transitions
-4. **UTC for Storage**: Store times in UTC and convert for display
-5. **Validate Inputs**: Check timezone and format validity before processing
-
-## Timezone Reference
-
-### Common US Timezones
-- `America/New_York` (EST/EDT)
-- `America/Chicago` (CST/CDT)
-- `America/Denver` (MST/MDT)
-- `America/Los_Angeles` (PST/PDT)
-- `America/Anchorage` (AKST/AKDT)
-- `Pacific/Honolulu` (HST)
-
-### Common European Timezones
-- `Europe/London` (GMT/BST)
-- `Europe/Paris` (CET/CEST)
-- `Europe/Berlin` (CET/CEST)
-- `Europe/Rome` (CET/CEST)
-- `Europe/Madrid` (CET/CEST)
-
-### Common Asian Timezones
-- `Asia/Tokyo` (JST)
-- `Asia/Shanghai` (CST)
-- `Asia/Kolkata` (IST)
-- `Asia/Dubai` (GST)
-- `Asia/Singapore` (SGT)
-
-## Contributing
-
-See the main project README for contribution guidelines.
-
-## License
-
-This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file