Orellis: Local Codebase AI Assistant

Orellis is a Model Context Protocol (MCP) server that lets engineers query and explore their local Python codebase via natural language. It embeds code files, indexes them with FAISS, and runs a local LLM (Ollama) on CPU for secure, private onboarding assistance. All inference remains CPU optimized and runs on your local machine—your codebase never leaves your laptop

---

🚀 Features

• Embeddings & Search: Uses sentence-transformers + FAISS to embed and retrieve the most relevant code chunks.
• Local LLM Inference: Runs your quantized code model (e.g. deepseek-coder:1.3b-instruct) locally via Ollama.
• MCP Server: Exposes two tools over the MCP protocol:
  • ask_codebase(project_path, question): Query the codebase.
  • onboarding_walkthrough(project_path): Generate a guided overview of every file.
• Async Support: Parallelized LLM calls for fast walkthroughs.

---

📋 Prerequisites

1. Python 3.10+
2. Ollama CLI (for local model host):

   # macOS/Linux
   brew install ollama/ollama/ollama
   # Windows
   choco install ollama
   

3. Ollama Model: Pull your code model once:

   ollama pull deepseek-coder:1.3b-instruct
   

4. Python Dependencies:

   git clone <this-repo>
   cd <this-repo>/src
   python -m venv .venv
   source .venv/bin/activate    # or .venv\Scripts\activate on Windows
   pip install -r requirements.txt
   

---

💻 Running with Claude Desktop

1. Install Claude Desktop

   • Download & install from https://claude.ai/desktop

2. Setting Up The Configuration

   • Start with making config file:

   mcp install server.py
   

   • Change the contents of the config file:
   • Open Claude Desktop and go to File → Settings → Developer.
   • Click on Edit Config
   • Open claude_desktop_config.json file
   • Copy this in:

   {
     "mcpServers": {
       "orellis": {
         "command": "<full path to the project you cloned>\\.venv\\Scripts\\python.exe",
         "args": [
           "<full path to the project you cloned>\\src\\server.py"
           ]
         }
       }
   }
   

3. Interact

   • Restart claude desktop completely

   • Wait till you see this:
     

   • Provide full path of python projecct and ask a question about it or ask for a walkthrough

   • After you provide the path once you dont need to provide it again only if you want to switch projects

---

🔄 Changing the Model

Orellis uses a local Ollama‑hosted model (deepseek-coder:1.3b-instruct) by default. To switch models:

1. Pull or quantize a new model:

   ollama pull <model-name>
   

2. Update llm.py:
   • Change MODEL to your new <model-name>.
3. Restart the server:
   • Restart claude desktop completely