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)

npm install -g @opichi/helios-mcp

From Source

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):

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

Windsurf/Other MCP Clients

Add to your MCP configuration:

{
  "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

npm run build

Development Mode

npm run dev

Testing

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:

HELIOS_DEBUG=true opichi-helios

Reset Index

To completely reset and re-index:

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 file for details.

Changelog

See CHANGELOG.md for version history and changes.

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