Semantic Context Mcp
About
A Model Context Protocol (MCP) server that leverages a vector database to efficiently index and query the codebase.
Details
- Author
- zishengwu
- Downloads
- 254
- Categories
- Knowledge Base
Jump to
- Incremental indexing using a Merkle Tree for efficient updates.
- Multi-language AST parsing: Python, Java, C++, JavaScript, TypeScript, Go.
- Semantic code search via natural language queries.
- Background automation with periodic incremental updates every 5 minutes.
- Local-first storage: all data kept in ~/.chromadb.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Semantic Context McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install by cloning the repository and setting environment variables for an OpenAI-compatible API (OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL_NAME). Configure the MCP JSON file in your IDE with the command fastmcp run pointing to the server script. The server provides three tools: full_index, status, and query. It automatically performs an initial full index and then runs periodic incremental updates every 5 minutes.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"semantic context mcp": {
"Semantic Context MCP Server": {
"command": "fastmcp",
"args": [
"run",
"your_code_base/semantic-context-mcp/vector_search/fast_mcp_server.py:mcp"
],
"env": {
"OPENAI_API_KEY": "your_api_key",
"OPENAI_BASE_URL": "your_api_base_url",
"OPENAI_MODEL_NAME": "your_embedding_model_name"
}
}
}
}
}McpServers
{
"Semantic Context MCP Server": {
"command": "fastmcp",
"args": [
"run",
"your_code_base/semantic-context-mcp/vector_search/fast_mcp_server.py:mcp"
],
"env": {
"OPENAI_API_KEY": "your_api_key",
"OPENAI_BASE_URL": "your_api_base_url",
"OPENAI_MODEL_NAME": "your_embedding_model_name"
}
}
}中文
🚀 Overview
Semantic Context MCP Server is a Model Context Protocol (MCP) server that leverages a vector database to efficiently index and perform semantic searches across your codebase.
It intelligently parses your code into structural blocks (like functions and classes), converts them into vector embeddings, and stores them in a local vector database. This allows you to find semantically relevant code snippets using natural language queries, rather than just keyword matching.
The server runs in the background, automatically tracking file changes and incrementally updating its index, ensuring your code context is always up-to-date.
✨ Features
- Incremental Indexing: Uses a Merkle Tree to detect file changes, ensuring only modified files are re-indexed, which is highly efficient.
- Multi-Language Support: Employs AST (Abstract Syntax Tree) parsing to support a wide range of languages, including Python, Java, C++, JavaScript, TypeScript, and Go.
- Semantic Code Search: Find code based on meaning and context, not just keywords.
- Background Automation: Automatically performs an initial full index and then runs periodic incremental updates every 5 minutes.
- Simple MCP Interface: Provides easy-to-use tools (full_index, status, query) for integration with other systems.
- Local First: All data (vector database, index metadata) is stored locally in your user home directory (~/.chromadb).
🛠️ How It Works
1. Detect Changes: A Merkle Tree is built from file content hashes to quickly identify added, modified, or deleted files.
2. Parse Code: Changed files are parsed using an AST parser to extract meaningful code blocks (functions, classes, etc.).
3. Generate Embeddings: The extracted code blocks are converted into numerical representations (vector embeddings) using an embedding model (e.g., Jina, OpenAI).
4. Store in Vector DB: These embeddings and associated metadata are stored in a local ChromaDB instance.
5. Query: When a query is received, it's converted into an embedding and used to find the most similar code blocks in the vector database.
📂 Project Structure
.
├── vector_search/
│ ├── ast_parser.py # Smart AST parser for multiple languages
│ ├── code_change_tracker.py # Detects file changes using a Merkle Tree
│ ├── code_indexer.py # Main logic for incremental and full indexing
│ ├── fast_mcp_server.py # The MCP server exposing the tools
│ └── vector_db.py # Vector database manager (ChromaDB wrapper)
├── LICENSE
├── README_zh.md
└── README.md
⚙️ Prerequisites
- Python 3.8+
- An OpenAI-compatible API for generating embeddings. You need to set the following environment variables:
export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="your_api_base_url"
export OPENAI_MODEL_NAME="your_embedding_model_name"
📦 Installation
1. Clone the repository:
git clone https://github.com/zishengwu/semantic-context-mcp
cd semantic-context-mcp
🚀 Usage
1. config MCP JSON file in IDE:
{
"mcpServers": {
"Semantic Context MCP Server": {
"command": "fastmcp",
"args": [
"run",
"your_code_base/semantic-context-mcp/vector_search/fast_mcp_server.py:mcp"
],
"env": {
"OPENAI_API_KEY": "your_api_key",
"OPENAI_BASE_URL": "your_api_base_url",
"OPENAI_MODEL_NAME": "your_embedding_model_name"
}
}
}
}
Enjoy it！👏
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
