README.md•5.92 kB
# Persistent-Code MCP Server with LlamaIndex
A Model Context Protocol (MCP) server that creates and maintains a semantic knowledge graph of code generated by Claude. Powered by LlamaIndex, this allows maintaining context across sessions with advanced semantic search capabilities without requiring the entire codebase to be present in the context window.
## Problem & Solution
When developing software with Claude:
- Context windows are limited, making it difficult to work with large codebases
- Previous code context is lost between sessions
- Claude lacks persistent understanding of project structure
- Redundant explanation of code is required in each session
- Maintaining implementation consistency is challenging
Persistent-Code solves these problems by:
- Creating a knowledge graph of code components and their relationships
- Tracking implementation status of each component
- Providing tools to navigate, query, and understand the codebase
- Assembling minimal necessary context for specific coding tasks
- Maintaining persistent knowledge across chat sessions
## LlamaIndex Integration
Persistent-Code leverages LlamaIndex to provide enhanced semantic understanding:
1. **Semantic Search**: Find code components based on meaning, not just keywords
2. **Vector Embeddings**: Code is embedded into vector space for similarity matching
3. **Knowledge Graph**: Relationships between components are tracked semantically
4. **Contextual Retrieval**: Related code is retrieved based on semantic relevance
This integration allows Claude to understand your codebase at a deeper level:
- Find functions based on what they do, not just what they're called
- Get more relevant code components when preparing context
- Better understand the relationships between components
- More accurately retrieve examples of similar implementations
## Installation
### Prerequisites
- Python 3.10 or higher
- UV package manager (recommended) or pip
### Setting Up
```bash
# Clone repository
git clone https://github.com/your-username/persistent-code-mcp.git
cd persistent-code-mcp
# Set up environment with UV
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
# Or with pip
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
## Usage
### Initializing a Project
```bash
python -m persistent_code init --project-name "YourProject"
```
### Starting the Server
```bash
python -m persistent_code serve --project-name "YourProject"
```
### Configuring Claude for Desktop
1. Edit your Claude for Desktop config file:
- Location: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Add the following configuration:
```json
{
"mcpServers": {
"persistent-code": {
"command": "path to python in venv",
"args": [
"-m",
"persistent_code",
"serve",
"--project-name",
"default"
],
"cwd": "persistent-code-mcp",
"env": {
"PYTHONPATH": "abs path to persistent-code-mcp"
}
}
}
}
```
2. Restart Claude for Desktop
3. Connect to your MCP server by asking Claude about your code
## Available Tools
### Knowledge Graph Management
- `add_component`: Add a new code component to the graph
- `update_component`: Update an existing component
- `add_relationship`: Create a relationship between components
### Code Retrieval and Navigation
- `get_component`: Retrieve a component by ID or name
- `find_related_components`: Find components related to a given component
- `search_code`: Search the codebase semantically
### Status Management
- `update_status`: Update implementation status of a component
- `get_project_status`: Retrieve implementation status across the project
- `find_next_tasks`: Suggest logical next components to implement
### Context Assembly
- `prepare_context`: Assemble minimal context for a specific task
- `continue_implementation`: Provide context to continue implementing a component
- `get_implementation_plan`: Generate a plan for implementing pending components
### Code Analysis
- `analyze_code`: Analyze code and update the knowledge graph
## Example Workflow
1. Initialize a project:
```bash
python -m persistent_code init --project-name "TodoApp"
```
2. Start the server:
```bash
python -m persistent_code serve --project-name "TodoApp"
```
3. Ask Claude to design your project:
```
Can you help me design a Todo app with Python and FastAPI? Let's start with the core data models.
```
4. Claude will create components and track them in the knowledge graph
5. Continue development in a later session:
```
Let's continue working on the Todo app. What's our implementation status?
```
6. Claude will retrieve the current status and suggest next steps
7. Implement specific components:
```
Let's implement the task completion endpoint for our Todo app
```
8. Claude will retrieve relevant context and provide consistent implementation
## Using Semantic Search
With the LlamaIndex integration, you can now use more natural language to find components:
```
Find me all code related to handling task completion
```
Claude will use semantic search to find relevant components, even if they don't explicitly contain the words "task completion".
## Running the LlamaIndex Demo
We've included a demo script to showcase the semantic capabilities:
```bash
# Activate your virtual environment
source .venv/bin/activate # or source venv/bin/activate
# Run the demo
python examples/llama_index_demo.py
```
This will demonstrate analyzing a Calendar application and performing semantic searches for functionality.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.