@opichi/smartcode/README.md

Universal code intelligence MCP server - analyze any codebase with TypeScript excellence and multi-language support

# 🧠 Opichi Smartcode

**Universal Code Intelligence MCP Server** - Analyze any codebase with TypeScript excellence and multi-language support.

Transform your AI coding assistant from confused to brilliant with instant codebase understanding.

## 🌟 What Makes This Special

- **🌍 Universal File Support**: Works with any file type - TypeScript, Python, Go, PHP, Ruby, JSON, Markdown, and more
- **⚡ Lightning Fast**: Instant project indexing with smart caching  
- **🎯 Surgical Analysis**: Precise symbol finding and code structure analysis
- **🔍 Smart Search**: Find functions, classes, API routes across any language
- **📊 Rich Context**: Get complete file analysis with imports, exports, and relationships
- **🛠️ Zero Config**: Auto-detects project languages and patterns

## 🚀 Quick Start

### Installation

**Option 1: NPX (Recommended)**
```bash
# No installation needed - just use directly
npx @opichi/smartcode
```

**Option 2: Global Install**
```bash
npm install -g @opichi/smartcode
```

### Configuration

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

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

**Or if globally installed:**
```json
{
  "mcpServers": {
    "opichi-smartcode": {
      "command": "opichi-smartcode"
    }
  }
}
```

### Usage

1. **Restart Claude Desktop** after configuration
2. In any project directory, try this **recommended workflow**:
   - *"Give me a project overview"* - Start with lightweight summary
   - *"Search for authentication functions"* - Find specific functionality
   - *"Show me functions in auth.service.ts"* - Drill down to file details
   - *"Get full code index"* - Complete analysis when needed

## 🛠️ Available Tools

### 🎯 **Tier 1: Quick Navigation** (Start Here)

#### 📋 **get_project_overview**
Lightweight project summary - perfect for initial understanding.
```
"Give me a project overview"
"What's the structure of this codebase?"
"Show me the key files and entry points"
```
*Returns: Directory structure, key files, entry points, and quick stats*

### 🔍 **Tier 2: Focused Queries** (Drill Down)

#### ⚡ **search_functions**
Find functions by name, documentation, or signature.
```
"Search for authentication functions"
"Find functions containing 'validate'"
"Show me async functions"
```
*Returns: Matching functions with signatures and documentation*

#### 📄 **get_functions_by_file**
Get all functions in a specific file with full details.
```
"Show me functions in auth.service.ts"
"What functions are in the user controller?"
```
*Returns: Complete function list with signatures, docs, and export status*

#### 🏗️ **get_types_by_pattern**
Find types, interfaces, and classes by pattern.
```
"Find all User types"
"Show me types matching 'Config*'"
"Get all interfaces ending with 'Service'"
```
*Returns: Matching types with properties and documentation*

#### 🧩 **get_components_by_pattern**
Find React components by name or file pattern.
```
"Find components matching 'Button*'"
"Show me all form components"
```
*Returns: Component details with props and documentation*

#### 🛳️ **get_routes_by_pattern**
Find API routes by method, path, or handler pattern.
```
"Find all POST routes"
"Show me routes containing 'auth'"
"Get routes handled by userController"
```
*Returns: Route details with methods, paths, and handlers*

### 🔎 **Tier 3: Deep Analysis** (When You Need Everything)

#### 📊 **get_code_index**
Complete overview of entire project (use sparingly).
```
"Show me the full code index"
"I need to see everything in this project"
```
*Returns: Complete table of contents with all functions, types, routes, and components*

#### 🔍 **find_symbol**
Find functions, classes, variables by exact name.
```
"Find symbol getUserName"
"Where is the User class defined?"
"Locate all functions named handleSubmit"
```
*Works across: TypeScript, JavaScript, Python, Go, PHP, Ruby, and more*

#### 🔎 **search_code**
Search for patterns and text across all files.
```
"Search for authentication patterns"
"Find all API endpoints"
"Show me error handling code"
```
*Supports: Regex patterns, file type filtering, case sensitivity*

#### 📄 **analyze_file**
Get complete analysis of any file.
```
"Analyze package.json"
"Show me the structure of user.service.ts"
"What's in the README.md?"
```
*Supports: TypeScript, JavaScript, JSON, Python, Go, PHP, Ruby, Markdown*

#### 🏗️ **get_project_structure**
Understand your project's architecture.
```
"Show me the project structure"
"What type of project is this?"
"What frameworks are being used?"
```
*Auto-detects: React, Node.js, Python, Go projects and their patterns*

#### 🗯️ **list_api_routes**
Discover all API endpoints automatically.
```
"List all API routes"
"Show me the REST endpoints"
"What APIs does this project expose?"
```
*Detects: Express, Next.js, Python Flask/Django, Go, PHP, Ruby routes*

## ⚡ Why This 3-Tier Approach?

### **Context Window Efficiency**
- **Tier 1** uses ~300 tokens vs 5000+ for full analysis
- **Tier 2** gives precise results without overwhelming detail
- **Tier 3** provides complete information only when needed

### **Smart Navigation Pattern**
```
1. Start Light → get_project_overview (quick understanding)
2. Focus Search → search_functions("auth") (find what you need)
3. Drill Down → get_functions_by_file (detailed analysis)
4. Go Deep → get_code_index (comprehensive view)
```

### **Perfect for AI Assistants**
- **Faster responses** - No more waiting for massive index dumps
- **Better accuracy** - AI gets relevant info without noise
- **Scalable** - Works on small scripts and enterprise codebases
- **Progressive disclosure** - Information when you need it

## 🧠 How It Works

### 1. **Universal File Support**
- **TypeScript/JavaScript**: Advanced AST parsing with full type information
- **Other Languages**: Smart regex patterns for Python, Go, PHP, Ruby, etc.
- **Config Files**: Proper JSON parsing, Markdown extraction
- **Auto-detection**: Identifies project languages and adapts accordingly

### 2. **Efficient Architecture**
- **Smart Caching**: Persistent indexing with timestamp validation
- **Minimal Dependencies**: No ML models or vector databases required
- **Fast Startup**: Sub-second project analysis
- **Surgical Extraction**: Only processes what you request

### 3. **Language Intelligence**
- **Pattern Recognition**: Detects API routes across different frameworks
- **Symbol Resolution**: Finds functions, classes, variables by name
- **Context Awareness**: Understands imports, exports, and relationships
- **Project Detection**: Identifies React, Node.js, Python, Go patterns

## 🎯 Example Usage

**Get Project Overview:**
> You: "Get code index"
> Agent: "Found 4 API routes, 6 exported functions, 38 types. Key functions: handleFindSymbol, handleAnalyzeFile, handleGetCodeIndex. Main types: TypeScriptAnalyzer, CodeIndexer, FileStructure."

**Analyze Any File:**
> You: "Analyze package.json"
> Agent: "This is @opichi/smartcode v1.0.0, a universal code intelligence MCP server. Dependencies: @modelcontextprotocol/sdk, typescript. Scripts: build, watch, start."

**Find Code Across Languages:**
> You: "Find symbol getUserName"
> Agent: "Found getUserName function in src/auth/service.ts:42 - async function getUserName(id: string): Promise<string>"

**Discover API Structure:**
> You: "List API routes"
> Agent: "Found Express routes: GET /users, POST /auth/login, PUT /users/:id. Also detected Flask routes in Python files: @app.route('/api/data')"

## 🏗️ Architecture

```
src/
├── analyzer/          # Core analysis engines
│   ├── typescript.ts  # TypeScript AST parsing
│   └── indexer.ts     # Universal file indexing
├── tools/             # MCP tool implementations
│   └── code-intelligence.ts  # All 6 core tools
└── index.ts           # MCP server entry point
```

**Key Features:**
- **Universal Parsing**: TypeScript AST + regex fallbacks
- **Smart Caching**: `.mcp-cache/code-index.json`
- **Multi-Language**: Auto-detects project file types
- **Zero Config**: Works out of the box

## 🚀 Published Package

**NPM**: [`@opichi/smartcode`](https://www.npmjs.com/package/@opichi/smartcode)  
**Install**: `npm install -g @opichi/smartcode`  
**Use**: `npx @opichi/smartcode`  

## 🔧 Development

### Local Development
```bash
git clone git@github.com:opichillc/expert-coder.git
cd expert-coder
npm install
npm run build
node dist/index.cjs
```

### Adding Language Support
1. Update `detectProjectFileTypes()` in `tools/code-intelligence.ts`
2. Add patterns to `apiPatterns` array
3. Extend `analyzeGenericFile()` regex patterns

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 📝 License

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

## 🙏 Acknowledgments

- **Tree-sitter** for language parsing
- **Qdrant** for vector search
- **Hugging Face Transformers** for embeddings
- **MCP SDK** for protocol implementation

---

**Transform your AI coding assistant from confused to brilliant.** 🧠✨