# CodeCompass > CodeCompass: AI-powered Vibe Coding with MCP. Connects Git repositories to AI assistants like Claude, using Ollama for privacy or OpenAI for cloud. Integrates with VSCode, Cursor, and more. - **Type:** MCP server - **Install:** `agentstack add mcp-alvinveroy-codecompass` - **Verified:** Pending review - **Seller:** [alvinveroy](https://agentstack.voostack.com/s/alvinveroy) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [alvinveroy](https://github.com/alvinveroy) - **Source:** https://github.com/alvinveroy/CodeCompass ## Install ```sh agentstack add mcp-alvinveroy-codecompass ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # CodeCompass CodeCompass helps developers tackle legacy or existing codebases by giving AI coding assistants the context they need to deliver spot-on suggestions. Legacy code is tough for AI—it’s often messy, outdated, and lacks clear documentation. CodeCompass solves this by analyzing your codebase with Qdrant Vector Store and powering AI with Ollama (local) or cloud agents like DeepSeek, using its Agentic RAG feature to make suggestions smarter and more relevant. It’s like giving your AI a roadmap to your code, so you can vibe code effortlessly. --- ## Features - **Codebase Analysis**: Maps your repository's structure and dependencies, now with support for indexing very large files through automated chunking. - **Smart AI Context with Agentic RAG**: Utilizes a sophisticated Retrieval Augmented Generation (RAG) approach. The central `agent_query` tool intelligently orchestrates internal capabilities to gather comprehensive context. This includes analyzing `git diff` information (summarized if large), dynamically summarizing extensive file lists or code snippets, and more, ensuring AI suggestions are highly relevant. - **Intelligent Agent Orchestration**: The core `agent_query` tool allows the AI to plan and execute multi-step tasks. It can proactively use a suite of internal capabilities to: - Search code (`capability_searchCodeSnippets`) - Retrieve full file content (`capability_getFullFileContent`), with summarization for large files. - List directory contents (`capability_listDirectory`). - Fetch adjacent code chunks (`capability_getAdjacentFileChunks`). - Analyze repository overviews including diffs and relevant snippets (`capability_getRepositoryOverview`). - Request more search results (`capability_fetchMoreSearchResults`) or more processing time if a query is complex. - **Flexible Setup**: Runs locally with Ollama or connects to cloud AI like DeepSeek. - **Highly Configurable**: Offers extensive environment variables to fine-tune indexing parameters, agent behavior (like loop steps and refinement iterations), context processing limits, and specific LLM models for tasks like summarization. ## Project Status and Roadmap **Current Status:** CodeCompass has successfully implemented its core features, including: - Codebase analysis using Qdrant Vector Store. - Agentic RAG (Retrieval Augmented Generation) for intelligent AI suggestions. - Flexible integration with local LLMs via Ollama (e.g., `llama3.1:8b`, `nomic-embed-text:v1.5`) and cloud-based LLMs like DeepSeek. The project is actively maintained and considered stable for its current feature set. **Future Enhancements (Under Consideration):** While the core functionality is robust, potential future directions include: - Support for a broader range of LLM providers (e.g., OpenAI, Gemini, Claude). - More sophisticated agent capabilities and additional tool integrations. - Enhanced repository indexing techniques for even more precise context retrieval. - Streamlined user configuration and an even smoother setup experience. - Deeper integrations with various IDEs and development workflows. We welcome community contributions and suggestions for future development! Please see our [CONTRIBUTING.md](https://github.com/alvinveroy/CodeCompass/blob/main/CONTRIBUTING.md). ## Prerequisites - **Node.js** v20+ ([nodejs.org](https://nodejs.org)) - **Docker** for Qdrant ([docker.com](https://www.docker.com)) - **Ollama** ([ollama.com](https://ollama.com)): For local LLM and embedding capabilities. - Required models (can be configured via environment variables, see Configuration section): - Embedding Model: `nomic-embed-text:v1.5` (default) - Suggestion Model (if using Ollama for suggestions): `llama3.1:8b` (default) - **DeepSeek API Key** (optional, for cloud-based suggestions; get from [Deepseek](https://platform.deepseek.com)) ## Installation 1. **Install Ollama**: - **Linux**: ```bash curl -fsSL https://ollama.com/install.sh | sh ``` - **macOS/Windows**: Download from [ollama.com](https://ollama.com/download). - Ensure the Ollama application is running (or run `ollama serve` in your terminal if you installed the CLI version). - Pull the default models (or the models you intend to configure): ```bash ollama pull nomic-embed-text:v1.5 # Default embedding model ollama pull llama3.1:8b # Default Ollama suggestion model ``` You can verify installed models with `ollama list`. 2. **Install Qdrant**: ```bash docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant ``` Verify at [http://localhost:6333/dashboard](http://localhost:6333/dashboard). 3. **Install CodeCompass**: ```bash npx -y @alvinveroy/codecompass@latest ``` This installs CodeCompass globally. You can then run it from any directory. ## Usage CodeCompass can be run in two main modes: as a server (default) or as a client to execute specific tools against a running server. **1. Running the CodeCompass Server:** To start the CodeCompass server, navigate to the root of your git repository and run: ```bash codecompass [repoPath] [--port ] ``` - `[repoPath]` (optional): Path to the repository you want CodeCompass to analyze. If omitted, it defaults to the current directory (`.`). - `--port ` (optional): Specify the HTTP port for the server. This overrides the `HTTP_PORT` environment variable and the default port (3001). Examples: ```bash # Start server for the current directory on the default port codecompass # Start server for a specific repository codecompass /path/to/your/project # Start server for the current directory on port 3005 codecompass --port 3005 ``` Once started, CodeCompass will begin indexing your repository (if it hasn't already). MCP communication is primarily handled via `stdio`. A utility HTTP server also runs on the configured port (default 3001) for health checks, indexing status, and to receive repository update notifications from Git hooks. **Port Conflicts for Utility HTTP Server:** If the configured utility HTTP port is in use by another CodeCompass instance, the new instance will disable its own utility HTTP server and run with `stdio` MCP. Its utility-related MCP tools (like `get_indexing_status`, `trigger_repository_update`) will automatically relay requests to the existing instance's HTTP utility endpoints. If the port is taken by a non-CodeCompass service, the new instance will log an error and exit. Git hooks should generally target the HTTP port of the primary running CodeCompass instance. **2. Executing Tools via CLI Client Mode:** To execute specific tools, CodeCompass CLI spawns a dedicated server instance and communicates with it via `stdio` using the Model Context Protocol (MCP). ```bash codecompass [json_parameters] [--repo ] [--json] [--port ] ``` - ``: The name of the tool to execute (see list below). - `[json_parameters]` (optional): A JSON string containing parameters for the tool. For tools that take no parameters, this can be omitted or an empty JSON object `{}` can be used. - `--repo ` or `-r ` (optional): Specify the repository path for the tool's context. Defaults to the current directory (`.`). The spawned server will use this repository. - `--json` or `-j` (optional): Output the raw JSON response from the tool. Useful for scripting or debugging. - `--port ` (optional): Specify the utility HTTP port for the spawned server instance. This is primarily for consistency if the spawned server needs to interact with other instances or if its utility port needs to be specific, though core MCP communication for the tool is via `stdio`. **Available Tools for CLI Client Execution:** * `agent_query `: Orchestrates capabilities to answer complex queries. * Example: `codecompass agent_query '{"query": "How is user authentication handled?", "sessionId": "my-session-123"}'` * With JSON output: `codecompass agent_query '{"query": "Show me user models"}' --json` * `search_code `: Performs semantic code search. * Example: `codecompass search_code '{"query": "database connection setup"}'` * `get_changelog`: Retrieves the project's `CHANGELOG.md`. * Example: `codecompass get_changelog` * `get_indexing_status`: Gets the current status of repository indexing. (May be relayed if another CC instance is primary) * Example: `codecompass get_indexing_status --json` * `trigger_repository_update`: Triggers a re-indexing of the repository. (May be relayed) * Example: `codecompass trigger_repository_update` * `switch_suggestion_model `: Switches the suggestion model/provider. * Example: `codecompass switch_suggestion_model '{"model": "deepseek-coder", "provider": "deepseek"}'` * `get_session_history `: Retrieves history for a session ID. (Requires `sessionId` in params). * Example: `codecompass get_session_history '{"sessionId": "my-session-123"}'` * `generate_suggestion `: Generates code suggestions. * Example: `codecompass generate_suggestion '{"query": "optimize this database query"}'` * `get_repository_context `: Provides a high-level summary of repository context. * Example: `codecompass get_repository_context '{"query": "main API components"}'` **General CLI Commands:** * `codecompass --help` or `codecompass -h`: Show help message. * `codecompass --version` or `codecompass -v`: Show CodeCompass version. * `codecompass changelog [--verbose]`: Show the project changelog. --- With CodeCompass set up, use natural language prompts in Cursor or other AI tools to vibe code—interact with your codebase intuitively. The Agentic RAG feature, powered by Qdrant and Ollama/DeepSeek, ensures your AI understands your code’s context for precise results. The CLI client mode offers another way to interact with CodeCompass tools directly. ## Configuration CodeCompass relies on environment variables for its configuration. These variables can be set in several ways: 1. **Directly in your shell**: For the current session or persistently by adding them to your shell's profile script. 2. **System-wide**: Setting them at the operating system level. 3. **Through MCP client settings**: If you're using CodeCompass via an MCP client like Cursor or Cline, you can often define environment variables within their respective configuration files (e.g., `mcp.json` for Cursor). This is detailed in the "Setting Up with Cursor" section. 4. **Using a `.env` file**: For convenience, especially during local development, you can place a `.env` file in the root directory of the repository you are analyzing with CodeCompass. CodeCompass will load variables from this file. Below are instructions for setting environment variables directly in your shell or system-wide, followed by a list of common variables. ### Setting Environment Variables **For Linux and macOS:** You can set an environment variable for the current terminal session using the `export` command: ```bash export VAR_NAME="value" ``` For example: ```bash export LLM_PROVIDER="deepseek" export DEEPSEEK_API_KEY="your_deepseek_api_key_here" ``` These settings will only last for the current session. To make them permanent, add these `export` lines to your shell's configuration file: - For Bash (common default): `~/.bashrc` or `~/.bash_profile` - For Zsh (common on macOS): `~/.zshrc` After editing the file, reload it (e.g., `source ~/.bashrc` or `source ~/.zshrc`) or open a new terminal. **For Windows:** Using Command Prompt (cmd.exe): ```cmd set VAR_NAME="value" ``` For example: ```cmd set LLM_PROVIDER="deepseek" set DEEPSEEK_API_KEY="your_deepseek_api_key_here" ``` This sets the variable for the current Command Prompt session only. Using PowerShell: ```powershell $Env:VAR_NAME = "value" ``` For example: ```powershell $Env:LLM_PROVIDER = "deepseek" $Env:DEEPSEEK_API_KEY = "your_deepseek_api_key_here" ``` This sets the variable for the current PowerShell session only. To set environment variables permanently on Windows: 1. Search for "environment variables" in the Start Menu. 2. Click on "Edit the system environment variables". 3. In the System Properties window, click the "Environment Variables..." button. 4. You can set User variables (for the current user) or System variables (for all users). Click "New..." under the desired section. 5. Enter the variable name (e.g., `LLM_PROVIDER`) and value (e.g., `deepseek`). 6. Click OK on all windows. You may need to restart your Command Prompt, PowerShell, or even your computer for the changes to take full effect. Alternatively, to set a user environment variable permanently from Command Prompt (requires a new command prompt to see the effect): ```cmd setx VAR_NAME "value" ``` Example: ```cmd setx LLM_PROVIDER "deepseek" setx DEEPSEEK_API_KEY "your_deepseek_api_key_here" ``` ### Common Environment Variables (Reference) Here's a list of important environment variables. If you choose to use a `.env` file, you can copy this structure. ```env # --- General Configuration --- # LOG_LEVEL: Logging level (e.g., error, warn, info, verbose, debug, silly). Default: info # LOG_LEVEL=info # --- Qdrant Configuration --- # QDRANT_HOST: URL for the Qdrant vector store server. QDRANT_HOST=http://localhost:6333 # COLLECTION_NAME: Name of the Qdrant collection for this repository. # It's good practice to use a unique name per repository if you manage multiple. # COLLECTION_NAME=codecompass_default_collection # QDRANT_SEARCH_LIMIT_DEFAULT: Default number of results to fetch from Qdrant during standard searches. Default: 10 # QDRANT_SEARCH_LIMIT_DEFAULT=10 # --- Ollama Configuration (for local LLM and embeddings) --- # OLLAMA_HOST: URL for the Ollama server. OLLAMA_HOST=http://localhost:11434 # --- LLM Provider Configuration --- # LLM_PROVIDER: Specifies the primary LLM provider for generating suggestions. # Supported values: "ollama", "deepseek", "openai", "gemini", "claude". Default: "ollama" LLM_PROVIDER=ollama # SUGGESTION_MODEL: The specific model to use for suggestions. # If LLM_PROVIDER="ollama", example: "llama3.1:8b", "codellama:7b" # If LLM_PROVIDER="deepseek", example: "deepseek-coder" # If LLM_PROVIDER="openai", example: "gpt-4-turbo-preview", "gpt-3.5-turbo" # If LLM_PROVIDER="gemini", example: "gemini-pro" # If LLM_PROVIDER="claude", example: "claude-2", "claude-3-opus-20240229" # Default for Ollama: "llama3.1:8b" SUGGESTION_MODEL=llama3.1:8b # EMBEDDING_PROVIDER: Specifies the provider for generating embeddings. # Currently, "ollama" is the primary supported embedding provider. Default: "ollama" EMBEDDING_PROVIDER=ollama # EMBEDDING_MODEL: The specific model to use for embeddings via Ollama. # Default: "nomic-embed-text:v1.5" EMBEDDING_MODEL=nomic-embed-text:v1.5 # --- Cloud Provider API Keys (only needed if using respective providers) --- # DEEPSEEK_API_KEY: Your API key for DeepSeek. # DEEPSEEK_API_KEY=your_deepseek_api_key_here # OPENAI_API_KEY: Your API key for OpenAI. # OPENAI_API_KEY=your_openai_api_key_here # GEMINI_API_KEY: Your API key for Google Gemini. # GEMINI_API_KEY=your_gemini_api_key_here # CLAUDE_API_KEY: Your API key for Anthropic Claude. # CLAUDE_API_KEY=your_claude_api_key_here # --- DeepSeek Specific (Optional) --- # DEEPSEEK_API_URL: Custom API URL for DeepSeek if not using the default. # Default: "https://api.deepseek.com/chat/completions" # DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions # DEEPSEEK_RPM_LIMIT: Requests per minute limit for DeepSeek. Default: 20 # DEEPSEEK_RPM_LIMIT=20 # --- Agent Configuration --- # MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY: Maximum number of files to list directly in the generate_suggestion tool's context # before attempting to summarize the file list using an LLM. Default: 15 # MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY=15 # MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY: Maximum length of a code snippet to include in context without summarization. # Snippets longer than this will be summarized by an LLM if avail … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [alvinveroy](https://github.com/alvinveroy) - **Source:** [alvinveroy/CodeCompass](https://github.com/alvinveroy/CodeCompass) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-alvinveroy-codecompass - Seller: https://agentstack.voostack.com/s/alvinveroy - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.