🧠 CodeSense MCP

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

---

🤔 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

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

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

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.

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

---

📄 License

MIT © Atta Elahi

---

🙏 Built With

• Model Context Protocol — Anthropic's open standard for tool use
• FastMCP — Pythonic MCP server framework
• LangChain — Chunking & retrieval pipeline
• ChromaDB — Local vector store
• HuggingFace Sentence Transformers — Local embeddings (no API key!)