npm package: @opichi/helios-mcp-server
Description: Opichi Helios MCP Server - Comprehensive code analysis and semantic search for AI coding assistants
Author: Opichi LLC
Latest version: 1.3.1

# Opichi Helios MCP Server

A comprehensive Model Context Protocol (MCP) server that provides advanced code analysis and semantic search capabilities for AI coding assistants.

## Features

🔍 **Semantic Search** - Find code using natural language queries  
📊 **Dependency Analysis** - Comprehensive dependency tracking and impact analysis  
🔗 **Import Tracing** - Track symbol definitions and usages across your codebase  
🏗️ **Project Structure Analysis** - Understand your project's architecture  
💾 **Persistent Indexing** - Fast startup with incremental updates  
🔄 **Multi-Repository Support** - Manage multiple projects simultaneously  
⚡ **Real-time Updates** - File watcher integration for live indexing  

## Installation

### From npm (Recommended)

```bash
npm install -g @opichi/helios-mcp
```

### From Source

```bash
git clone https://github.com/opichi/helios-mcp.git
cd helios-mcp
npm install
npm run build
npm link
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "opichi-helios": {
      "command": "opichi-helios",
      "args": []
    }
  }
}
```

### Windsurf/Other MCP Clients

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "opichi-helios": {
      "command": "npx",
      "args": ["@opichi/helios-mcp"]
    }
  }
}
```

## Usage

Once configured, the following tools will be available in your AI assistant:

### `semantic_search`
Search for code using natural language descriptions:

```
Find functions that handle user authentication
Search for database connection logic
Look for error handling patterns
```

### `analyze_dependencies`
Analyze file dependencies and relationships:

```
Analyze dependencies for src/auth/login.ts
Show me what depends on this utility function
```

### `trace_imports`
Track where symbols are defined and used:

```
Trace all usages of the UserService class
Find where the validateEmail function is called
```

### `get_project_structure`
Understand your project's organization:

```
Show me the structure of this project
Analyze the architecture of the frontend module
```

### `index_project`
Index projects for analysis:

```
Index the current project
Force re-index of /path/to/project
```

## How It Works

### Persistent Storage
Helios stores all analysis data in `~/.opichi-helios/` with the following structure:

```
~/.opichi-helios/
├── indices/
│   ├── project-{hash}/
│   │   ├── metadata.db      # File metadata and symbols
│   │   ├── embeddings.db    # Vector embeddings
│   │   └── ast-cache/       # Parsed AST data
├── config.json
└── logs/
```

### Incremental Updates
- **File Checksums**: Only reprocess changed files
- **Real-time Watching**: Automatic updates when files change
- **Smart Caching**: Fast startup after initial indexing

### Multi-Language Support
- TypeScript/JavaScript
- Python
- Rust
- Go
- Java
- C/C++

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│  Helios MCP     │◄──►│  Local Storage  │
│  (Claude, etc.) │    │     Server      │    │   (~/.opichi)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   Your Code     │
                       │   Repositories  │
                       └─────────────────┘
```

### Core Components

- **HeliosCore**: Central orchestrator for multi-repository management
- **StorageManager**: SQLite-based persistent storage
- **IndexManager**: Code parsing and indexing with file watching
- **CodeAnalyzer**: AST parsing and symbol extraction
- **EmbeddingGenerator**: Local semantic embeddings using transformers
- **MCP Tools**: Five specialized tools for different analysis needs

## Performance

- **Cold Start**: ~100ms to load existing indices
- **Incremental Updates**: Only changed files are reprocessed
- **Memory Efficient**: Streams data from disk, doesn't load everything
- **Local Processing**: No API calls, everything runs on your machine

## Privacy

- **100% Local**: All code analysis happens on your machine
- **No Cloud Dependencies**: No external API calls or data transmission
- **Secure Storage**: All data stored locally in your home directory

## Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Testing

```bash
npm test
```

## Troubleshooting

### Common Issues

**"Command not found: opichi-helios"**
- Ensure the package is installed globally: `npm install -g @opichi/helios-mcp`
- Check that npm global bin directory is in your PATH

**"Failed to load embedding model"**
- The first run downloads the embedding model (~25MB)
- Ensure you have internet connection for the initial download
- Subsequent runs work offline

**"Project indexing is slow"**
- Large projects (>1000 files) may take a few minutes on first index
- Subsequent updates are much faster (incremental)
- Consider excluding build directories in `.gitignore`

### Debug Mode

Set environment variable for verbose logging:

```bash
HELIOS_DEBUG=true opichi-helios
```

### Reset Index

To completely reset and re-index:

```bash
rm -rf ~/.opichi-helios/indices
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

---

**Built by Opichi LLC** - Empowering developers with intelligent code analysis.