# 🧠 CodeSense MCP

> **Semantic code intelligence for Claude** — search, understand, and analyze any codebase using plain English.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![smithery badge](https://smithery.ai/badge/codesense-mcp)](https://smithery.ai/server/codesense-mcp)

---

## 🤔 The Problem

You open a new codebase and ask Claude:

> *"Where is the user authentication handled?"*

Claude has no idea. It hasn't seen your code.

You could paste files manually — but that's slow, hits context limits, and doesn't scale.

**CodeSense MCP solves this.** Point it at your project once, and Claude can search, navigate and reason about your entire codebase without you doing anything else.

---

## ✨ What It Does

| Tool | What you can ask Claude |
|------|------------------------|
| `index_codebase` | *"Index my project at ~/projects/myapp"* |
| `search_code` | *"Find where JWT tokens are validated"* |
| `explain_architecture` | *"Give me an overview of how this project is structured"* |
| `find_bugs` | *"Scan for common bug patterns and hardcoded secrets"* |
| `find_dead_code` | *"Find functions that are defined but never used"* |
| `suggest_refactor` | *"What should I refactor in src/utils.py?"* |
| `get_file_summary` | *"Tell me about the models/user.py file"* |
| `list_indexed_files` | *"List all Python files in the project"* |

---

## 🚀 Quick Start

### 1. Install

```bash
# Lightweight (keyword search, no extra deps)
pip install codesense-mcp

# Full semantic search (recommended — uses local embeddings, no API key needed)
pip install "codesense-mcp[semantic]"
```

### 2. Add to Claude Desktop

Open your Claude Desktop config:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add this:

```json
{
  "mcpServers": {
    "codesense": {
      "command": "uvx",
      "args": ["codesense-mcp"]
    }
  }
}
```

Restart Claude Desktop. That's it. ✅

---

## 💬 Example Conversations

**Find authentication logic:**
> You: *"Search my codebase for where passwords are hashed"*
> Claude: Searches and returns the exact functions with file paths and line context.

**Understand a new project:**
> You: *"Explain the architecture of ~/projects/django-app"*
> Claude: Returns a structured breakdown of modules, entry points, key classes, and language distribution.

**Security audit:**
> You: *"Scan for hardcoded secrets and empty except blocks"*
> Claude: Lists every file and line with potential issues.

**Refactor guidance:**
> You: *"What should I refactor in services/payment.py?"*
> Claude: Flags long functions, deep nesting, magic numbers, and missing docstrings with line numbers.

---

## 🏗️ Architecture

```
codesense-mcp/
├── codesense_mcp/
│   ├── __init__.py
│   └── server.py          ← All tools live here (FastMCP)
├── tests/
│   └── test_server.py
├── pyproject.toml
└── README.md
```

**Search modes:**

| Mode | When | How |
|------|------|-----|
| 🧠 Semantic | `[semantic]` installed | HuggingFace `all-MiniLM-L6-v2` + ChromaDB (local, no API key) |
| 🔍 Keyword | Fallback | Token-overlap scoring across indexed chunks |

**Supported languages:** Python · JavaScript · TypeScript · PHP · Ruby · Go · Java · C# · C/C++ · Rust · Swift

---

## 🔍 Bug Detection Patterns

CodeSense scans for:

- 🔴 Hardcoded secrets / credentials
- ⚠️ Bare `except:` clauses
- ⚠️ Mutable default arguments
- ⚠️ Empty except blocks
- 🟡 Leftover `print()` debug statements
- 📝 TODO / FIXME / HACK comments
- 💡 Missing type annotations

---

## 🔧 Refactor Analysis

For each file, CodeSense checks:

- 📏 Functions longer than 50 lines
- 🪆 Nesting depth greater than 4 levels
- 🔢 Magic numbers (unnamed constants)
- 📦 Files larger than 300 lines
- ♻️ Duplicated code patterns
- 📝 Missing docstrings

---

## 🛠️ Development

```bash
git clone https://github.com/attaelahi/codesense-mcp
cd codesense-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[semantic]"

# Test the server directly
python -m codesense_mcp.server

# Run with MCP Inspector
npx @modelcontextprotocol/inspector python -m codesense_mcp.server
```

---

## 🗺️ Roadmap

- [ ] Git diff analysis — *"What changed in the last 10 commits?"*
- [ ] Dependency graph visualization
- [ ] Cross-file call graph tracing
- [ ] Laravel/PHP-specific analysis (routes, controllers, models)
- [ ] CI/CD integration (GitHub Actions)
- [ ] Persistent index (survive restarts)
- [ ] Remote codebase support (GitHub URLs)

---

## 🤝 Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

If you find this useful, a ⭐ star goes a long way.

---

## 📄 License

MIT © [Atta Elahi](https://github.com/attaelahi)

---

## 🙏 Built With

- [Model Context Protocol](https://modelcontextprotocol.io) — Anthropic's open standard for tool use
- [FastMCP](https://github.com/jlowin/fastmcp) — Pythonic MCP server framework  
- [LangChain](https://langchain.com) — Chunking & retrieval pipeline
- [ChromaDB](https://www.trychroma.com) — Local vector store
- [HuggingFace Sentence Transformers](https://sbert.net) — Local embeddings (no API key!)