Codebase

You run an MCP server that analyzes Python codebases, extracts structural elements, stores embeddings in a vector store, and exposes querying and analysis capabilities through an MCP client. It enables efficient code understanding, cross-codebase search, and visualizations of call relationships, all while running behind the scenes to enrich data with semantic descriptions and embeddings when enabled.

How to use

Start by connecting your MCP client to the codebase MCP server. You will load your active codebase context, trigger a code scan, and then perform natural-language questions or element lookups against the stored code elements. You can refine results by leveraging cross-codebase dependencies and the file-watcher to keep data up-to-date. Use the query tools to locate elements like functions, classes, and their relationships, or ask natural-language questions to get synthesized explanations or summaries.

Typical workflows you can follow:

• Scan a codebase to extract Python elements and relationships, then switch to a new codebase context if needed.

• Use find_element to search for specific elements across the active codebase and declared dependencies.

• Ask questions (ask_question) to get contextual, NL-based answers that reference relevant code elements and their relationships.

• Generate MermaidJS diagrams from stored relationships to visualize call graphs.

• Add manual notes to code elements to capture domain-specific insights or clarifications.

How to install

Prerequisites you need before starting:

• Python 3.10 or newer

• Docker and Docker Compose

• An API key for Gemini or equivalent LLM services (as configured in the .env file)

Follow these steps to set up and run the MCP server locally.

# Start Weaviate (vector store)
docker-compose up -d

# Install Python dependencies
pip install -r requirements.txt

# Create and configure environment variables
# GEMINI_API_KEY=YOUR_API_KEY_HERE
# Optional settings can be set in the .env file

Notes and configuration

Environment variables control the behavior of the server, including enabling background LLM processing, concurrency, and Weaviate connection details. Set a Gemini API key and adjust optional settings in a .env file in the project root.

Run the MCP server using the Python module that hosts the MCP server entry point. The server runs in a separate terminal to keep tools available while you interact with it.

Example start command used by the server is shown here for reference.

Security and maintenance

Keep your Gemini API key secret and rotate it periodically. Regularly check for updates to the code scanner, vector storage adapter, and MCP server logic to benefit from improved parsing, richer descriptions, and bug fixes.

Available tools

scan_codebase

Parses Python files to extract functions, classes, imports, calls, assignments, and docstrings using AST, and prepares data for Weaviate.

select_codebase

Sets the active codebase context to enable targeted querying and analysis.

delete_codebase

Removes a codebase from the MCP registry and stops related watching and analysis tasks.

add_codebase_dependency

Defines dependencies between scanned codebases so queries can span related projects.

remove_codebase_dependency

Removes a declared dependency for cross-codebase querying.

find_element

Searches for code elements across the active codebase and its dependencies and returns matching results.

ask_question

Asks natural language questions about the codebase and receives synthesized answers with references to code elements.

list_codebases

Lists all known codebases with their status and dependencies.

start_watcher

Starts the integrated file watcher to monitor changes in the active codebase.

stop_watcher

Stops the file watcher for the active codebase.