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

# No installation needed - just use directly
npx @opichi/smartcode

Option 2: Global Install

npm install -g @opichi/smartcode

Configuration

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

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

Or if globally installed:

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

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
Install: npm install -g @opichi/smartcode
Use: npx @opichi/smartcode

🔧 Development

Local Development

git clone [email protected]: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 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. 🧠✨