@opichi/helios-mcp-server

A powerful MCP server providing deep code intelligence through semantic search and LSP integration.

Features

• Semantic Code Search: Natural language queries to find relevant code across your codebase
• LSP Integration: Precise code intelligence (definitions, references, hover info, symbols)
• Multi-Language Support: JavaScript, TypeScript, Python, Java, Go, Rust, C/C++
• MCP Protocol: Standardized interface for AI assistants to access code intelligence
• Tree-sitter Parsing: Accurate code structure extraction for better search results
• ChromaDB Integration: Vector database for semantic similarity search

Installation

# Global installation
npm install -g @opichi/helios-mcp-server

# Or run directly with npx
npx @opichi/helios-mcp-server

Usage

Command Line

# Start with default settings
helios-mcp-server

# Auto-detect project type and enable verbose logging
helios-mcp-server --auto-detect --verbose

# Use a custom port
helios-mcp-server --port 4000

# Disable LSP integration (semantic search only)
helios-mcp-server --no-lsp

Options

• --auto-detect: Automatically detect project type and configure LSP servers
• --verbose: Enable verbose logging
• --no-lsp: Disable LSP integration (semantic search only)
• --port, -p: Specify port number (default: 3000)
• --help, -h: Show help message

MCP Configuration

Add to your .kilocode/mcp.json:

{
  "servers": [
    {
      "name": "helios",
      "command": "npx @opichi/helios-mcp-server",
      "type": "stdio"
    }
  ]
}

MCP Tools

The server provides the following MCP tools:

semantic_search

Search for code using natural language queries.

{
  "query": "function to authenticate users",
  "limit": 5,
  "language": "javascript"
}

get_definition

Get the definition location of a symbol.

{
  "filePath": "src/auth.js",
  "line": 42,
  "character": 15
}

find_references

Find all references to a symbol.

{
  "filePath": "src/auth.js",
  "line": 42,
  "character": 15,
  "includeDeclaration": true
}

get_hover_info

Get hover information for a symbol.

{
  "filePath": "src/auth.js",
  "line": 42,
  "character": 15
}

list_symbols

List symbols in a file or workspace.

{
  "filePath": "src/auth.js",
  "query": "auth"
}

analyze_dependencies

Analyze project dependencies.

{
  "projectPath": "./my-project"
}

suggest_refactoring

Suggest refactoring opportunities.

{
  "filePath": "src/auth.js"
}

Programmatic Usage

import { HeliosMCPServer } from '@opichi/helios-mcp-server';

const server = new HeliosMCPServer({
  projectPath: './my-project',
  verbose: true,
  autoDetect: true
});

await server.start();

// Later, when shutting down
await server.stop();

Architecture

The server consists of several components:

• Indexer: Tree-sitter parsing and code structure extraction
• Pathfinder: Semantic search with sentence transformers and ChromaDB
• Surgeon: LSP integration for precise code intelligence
• ProjectManager: Project detection and metadata management
• Server: MCP protocol integration and tool handlers

Requirements

• Node.js 18 or higher
• Supported languages require their respective language servers installed

License

MIT