CodeAgent

A powerful, hosted Model Context Protocol (MCP) server that gives LLMs (like Claude, Cursor, and Windsurf) the ability to understand, navigate, and query any public GitHub repository.

CodeAgent clones the repository, parses it using tree-sitter, generates lightning-fast vector embeddings via Hugging Face Serverless API / FastEmbed, and exposes a suite of advanced code-intelligence tools via Streamable HTTP.

---

🌟 Vision & What It Is

The Problem: LLMs are great at writing code, but they struggle to explore large codebases. Claude cannot hold a 500-file repository in context, nor can it efficiently build architecture diagrams or semantically search across thousands of functions natively.

The Solution: CodeAgent acts as the "eyes and hands" of the LLM with a 100% free, hosted backend.

1. The user tells the LLM: "Index this GitHub repo"
2. The LLM calls our index_github_repo tool.
3. CodeAgent performs a shallow clone, parses every file into an Abstract Syntax Tree (AST) using tree-sitter in parallel (< 0.1s), generates cloud vector embeddings via Hugging Face API (~0.3s, using 0% CPU & 0 MB RAM), and stores all symbols and imports in a PostgreSQL database via a single bulk transaction.
4. The LLM can now instantly generate architecture diagrams, perform semantic vector searches, and navigate the codebase precisely.

---

⚡ Performance Highlights & Upgrades

• 🚀 10x Fast Bulk Indexing: AST parsing and symbol collection happen entirely in memory, followed by 1 bulk database transaction (conn.transaction()) rather than hundreds of individual SQL roundtrips.
• ☁️ Zero-RAM Cloud Embeddings: Uses Hugging Face Serverless Inference API (BAAI/bge-small-en-v1.5) for 0% CPU and 0 MB RAM overhead on cloud hosts (Render/Railway), preventing 512MB memory crashes.
• 🛡 Multi-Tier Embedding Fallback: Seamless automatic failover: Hugging Face API → OpenRouter API → Local FastEmbed.
• 🎯 Full Session-Scoped Agent Loop: Multi-tenant session_id propagation across all code-intelligence tools including vector similarity search (semantic_search) and Mermaid.js architecture generation (generate_architecture).

---

🏗 Architecture

Here is exactly how CodeAgent works under the hood:

graph TD
    subgraph Client [MCP Client]
        LLM[Claude Desktop / Cursor / Windsurf]
    end

    subgraph CodeAgent [CodeAgent Server]
        FastMCP[FastMCP Server]
        SessionMgr[Session Manager]
        Indexer[Tree-Sitter Parallel AST Parser]
        Tools[Code Intelligence Tools]
    end

    subgraph External [Cloud Embeddings]
        HF[Hugging Face Serverless API]
    end

    subgraph Storage [Storage Layer]
        DB[(PostgreSQL + pgvector)]
        Disk[(Local Disk /tmp)]
    end

    LLM <-->|1. Streamable HTTP Transport| FastMCP
    FastMCP -->|2. Route Request| SessionMgr
    FastMCP -->|4. Execute Tool| Tools
    
    SessionMgr -->|3a. Git Clone| Disk
    SessionMgr -->|3b. Trigger Bulk Indexing| Indexer
    
    Indexer -->|Parse AST In-Memory| Disk
    Indexer -->|Batch Text| HF
    HF -->|384-dim Vectors| Indexer
    Indexer -->|Single Bulk Transaction| DB
    
    Tools -->|Query Metadata & Vectors| DB
    Tools -->|Read File Slices| Disk

Components

• FastMCP (Streamable HTTP): The transport layer. Listens for HTTP requests at /mcp and maintains a streaming connection with the LLM.
• Tree-Sitter Parallel Indexer: Scans the codebase, understands syntax (Python, JS, TS, TSX), and extracts symbols and imports in milliseconds.
• Hugging Face Serverless Embeddings: Computes 384-dimensional vector embeddings over HTTP via router.huggingface.co with fallback to OpenRouter / FastEmbed.
• Postgres + pgvector: Stores relational metadata and vector embeddings for lightning-fast semantic querying.

---

🛠 Available MCP Tools

CodeAgent equips the LLM with these exact capabilities:

Tool	Description
index_github_repo(github_url)	Clones and indexes a public repo in 1-pass bulk transaction. Returns a unique session_id.
generate_architecture_diagram(session_id)	Instantly returns a Mermaid.js class diagram of the entire repository's architecture.
semantic_search_tool(query, session_id)	Uses pgvector to find code based on meaning (e.g., "password hashing logic") rather than exact keyword match.
search_symbols(query, session_id)	Finds functions/classes by partial name using fast ILIKE search.
list_all_symbols(kind, session_id)	Lists all symbols filtered by kind (e.g., all classes).
find_callers_tool(function_name, session_id)	Greps the codebase for places where a function is called.
read_code(file_path, start_line, end_line, session_id)	Reads exact source code lines directly from disk with line numbers.
get_imports(file_path, session_id)	Lists all imports recorded for a specific file.

---

🚀 Quick Start (Using the Hosted Version)

Want to try it immediately? Add our public hosted endpoint to your MCP client!

Using Claude Desktop

1. Open Claude Desktop.
2. Go to Settings (Gear Icon) → Connectors (or Edit claude_desktop_config.json).
3. Click Add Connector → Add Custom Connector (or configure custom MCP HTTP endpoint).
4. Enter the Server URL: https://codeagent-mcp.onrender.com/mcp
5. Click Connect.

Note: Claude Web (Chrome/Safari) does not support MCP yet. You must use the Claude Desktop macOS/Windows app.

Using Cursor

1. Go to Cursor Settings → Features → MCP.
2. Click Add New MCP Server.
3. Choose Streamable HTTP / HTTP as the transport.
4. Enter URL: https://codeagent-mcp.onrender.com/mcp

Example Prompt:

"Index this repo: https://github.com/pallets/flask. Then, use the architecture tool to draw the complete class diagram. Finally, use semantic search to find where they handle request parsing."

---

💻 Self-Hosting & Deployment

CodeAgent is fully open-source and easy to host yourself.

Prerequisites

• Python 3.11+
• PostgreSQL database with pgvector extension enabled (e.g., Neon free tier)
• Git installed on the system

1. Local Development Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/CodeAgent-MCP.git
cd CodeAgent-MCP

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Configure environment
cp .env.example .env

Set your environment variables in .env:

OPENROUTER_API_KEY="sk-or-v1-your-key"
DATABASE_URL="postgresql://user:[email protected]/neondb?sslmode=require"
HF_TOKEN="hf_your_huggingface_token"

Run the server locally:

python -m code_server.server
# Server will start at http://0.0.0.0:8000/mcp

2. Deploy to Render or Railway

1. Push your code to GitHub.
2. Go to Render or Railway.
3. Create a new Web Service from your GitHub repo.
4. Set Environment Variables:
   • DATABASE_URL (PostgreSQL connection string)
   • HF_TOKEN (Free Hugging Face token for zero-RAM cloud embeddings)
   • OPENROUTER_API_KEY (OpenRouter API key)
5. Deploy! The platforms will automatically detect the Dockerfile and expose port 8000.

---

🤝 Instructions for Contributors

We love contributions! If you want to make CodeAgent smarter, faster, or add support for more languages, here is how you can help:

How to Contribute

1. Fork the repo and create your branch from main.
2. Set up locally using the Local Development Setup instructions above.
3. Make your changes. Ensure your code is well-commented and clean.
4. Test your changes by running the server locally and connecting your MCP client to http://localhost:8000/mcp.
5. Issue a Pull Request.

Areas to Improve (Ideas for PRs)

• Add Language Support: Currently, we parse Python, JS, TS, and TSX. Help us add Go, Rust, Java, or C++ by updating the indexer.py tree-sitter grammars!
• Autonomous Cloud PRs: Add WRITE capabilities (edit_file, create_pull_request) so Claude can act as an autonomous SWE-agent on GitHub repos.
• Smarter Chunking: Improve how read_code returns large files so the LLM context window doesn't get flooded.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.