# code-context

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/code-context/)

MCP (Model Context Protocol) server for managing API endpoints and code context for AI coding assistants.

## Problem

When using AI coding assistants like Claude Code, you often need to reference API endpoints while writing code. This requires:
- Repeatedly searching through codebases
- High token consumption from context switching
- Risk of using outdated API information
- Manual tracking of endpoint specifications

## Solution

**code-context** automatically scans and stores your API endpoints in a vector database, enabling:
- ✅ **Instant lookup** by endpoint name or route
- ✅ **Semantic search** by describing what the endpoint does
- ✅ **Complete specifications** (headers, parameters, responses)
- ✅ **Always up-to-date** with your codebase

## Features

- 🔍 **Automatic scanning** of Python FastAPI/Flask projects
- 💾 **Vector storage** with Qdrant (embedded mode)
- 🔧 **MCP integration** with Claude Code/Desktop
- 📝 **CRUD operations** for endpoint management
- 🚀 **Zero-config setup** with `pipx install`
- 🎯 **Extensible** architecture for more languages

## Installation

### Quick Start (Recommended)

```bash
# Step 1: Install code-context
pipx install code-context

# Step 2: Initialize configuration (run once)
code-context init

# Step 3: Install MCP client integration
code-context install-mcp
```

The `install-mcp` wizard will guide you through:
- Selecting your AI coding assistant platform
- Automatically configuring the MCP integration
- Testing the connection

### Manual Installation (Development)

```bash
# Clone repository
git clone https://github.com/jieyefriic/code-context
cd code-context

# Install in development mode
pip install -e .

# Initialize configuration
code-context init

# Install MCP client
code-context install-mcp
```

## MCP Client Installation

code-context works with **12+ AI coding assistants** through the Model Context Protocol (MCP):

**Supported Platforms:** Claude Code • Cursor • Antigravity • Windsurf • Warp • Cline • VS Code Copilot • Copilot CLI • Amp • Gemini CLI • Codex • Factory CLI

### Quick Install

```bash
code-context install-mcp
```

This interactive wizard will automatically configure your AI assistant.

### Manual Installation

For detailed platform-specific instructions, see **[INSTALLATION.md](INSTALLATION.md)**

**Quick Links:**
- [Claude Code Setup](INSTALLATION.md#claude-code-recommended)
- [Cursor Setup](INSTALLATION.md#cursor)
- [Antigravity Setup](INSTALLATION.md#google-antigravity)
- [Windsurf Setup](INSTALLATION.md#windsurf)
- [Warp Terminal Setup](INSTALLATION.md#warp-terminal)
- [All Platforms & Troubleshooting](INSTALLATION.md)

## Usage

### 1. Initialize (Run Once)

```bash
code-context init
```

This wizard will:
- Guide you through selecting LLM provider (OpenAI, Gemini, DeepSeek, etc.)
- Configure API keys securely
- Set up embedding configuration
- Create data directory at `~/.code-context/`
- Initialize embedded Qdrant database

**Important**: This step must be completed before using the MCP server.

### 2. Scan Your Codebase

In Claude Code, ask:

```
Scan my project directory for API endpoints
```

Or manually:

```bash
# In Python REPL
from code_context import tools
tools.scan_codebase("/path/to/your/project", language="python")
```

### 3. Query Endpoints

In Claude Code, you can now ask:

```
What's the user login endpoint specification?
```

```
Show me all endpoints related to authentication
```

```
What parameters does the /api/users/:id endpoint accept?
```

## MCP Tools

The following tools are available to Claude Code:

### `search_endpoint`
Search for endpoints by name or route
```json
{
  "name": "get_user",      // Optional: exact name match
  "route": "/api/users"    // Optional: exact route match
}
```

### `add_endpoint`
Manually add an endpoint
```json
{
  "name": "create_user",
  "route": "/api/users",
  "method": "POST",
  "file_path": "/path/to/api.py",
  "description": "Create a new user",
  "parameters": {...},
  "response_format": {...}
}
```

### `scan_codebase`
Scan a directory for endpoints
```json
{
  "directory": "/path/to/project",
  "language": "python"
}
```

### `update_endpoint`
Update an existing endpoint
```json
{
  "endpoint_id": "uuid-here",
  "updates": {
    "description": "Updated description"
  }
}
```

### `delete_endpoint`
Delete an endpoint
```json
{
  "endpoint_id": "uuid-here"
}
```

### `list_endpoints`
List all stored endpoints
```json
{
  "limit": 100
}
```

## Supported Frameworks

### Current
- ✅ Python: FastAPI, Flask

### Planned
- 🔜 Node.js: Express, NestJS
- 🔜 Go: Gin, Echo, Chi
- 🔜 Rust: Axum, Actix

## Architecture

```
code-context/
├── src/code_context/
│   ├── server.py           # MCP server core
│   ├── config.py           # Configuration management
│   ├── tools/              # MCP tool implementations
│   ├── scanner/            # Code scanners (extensible)
│   │   ├── python.py       # Python scanner
│   │   └── [future: go.py, rust.py, etc.]
│   └── database/           # Qdrant client wrapper
└── tests/
```

## Configuration

### Environment Variables

```bash
# Custom data directory
export CODE_CONTEXT_DATA_DIR=~/.my-code-context

# Use remote Qdrant
export CODE_CONTEXT_QDRANT_URL=http://localhost:6333
export CODE_CONTEXT_QDRANT_API_KEY=your-key

# Collection settings
export CODE_CONTEXT_COLLECTION_NAME=my_endpoints
export CODE_CONTEXT_VECTOR_SIZE=1536
```

### View Current Config

```bash
code-context info
```

## Development

### Setup

```bash
# Clone and install with dev dependencies
git clone https://github.com/jieyefriic/code-context
cd code-context
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest tests/
```

### Code Formatting

```bash
black src/
ruff check src/
```

## Extending

### Add a New Language Scanner

Create `src/code_context/scanner/golang.py`:

```python
from . import BaseScanner
from ..database import Endpoint

class GoScanner(BaseScanner):
    def can_handle(self, file_path):
        return file_path.suffix == ".go"

    def scan_file(self, file_path):
        # Implement Go-specific scanning
        endpoints = []
        # ... parse Go code ...
        return endpoints
```

Register in `scanner/python.py`:

```python
def get_scanner(language: str):
    scanners = {
        "python": PythonScanner,
        "go": GoScanner,  # Add here
    }
    # ...
```

## Roadmap

- [x] Basic MCP server
- [x] Python FastAPI/Flask scanner
- [x] Embedded Qdrant storage
- [ ] LLM integration for semantic search
- [ ] Support for more languages (Go, Rust, Node.js)
- [ ] Web UI for endpoint management
- [ ] VS Code extension
- [ ] Automatic re-scanning on file changes
- [ ] Cloud-hosted version for teams

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## FAQ

### Q: Does this work with Claude Desktop?
A: Yes! It works with both Claude Code and Claude Desktop.

### Q: Can I use a remote Qdrant server?
A: Yes, set `CODE_CONTEXT_QDRANT_URL` environment variable.

### Q: How do I update endpoints when code changes?
A: Re-run `scan_codebase` on the directory. Future versions will support auto-refresh.

### Q: Can I use this with non-Python projects?
A: Not yet, but Go/Rust/Node.js support is planned. You can manually add endpoints with `add_endpoint`.

### Q: Does this send my code to external services?
A: No. Everything runs locally unless you configure a remote Qdrant server. LLM integration (optional) will use your API keys.

## Support

- 📖 [Documentation](https://github.com/jieyefriic/code-context/wiki)
- 🐛 [Issues](https://github.com/jieyefriic/code-context/issues)
- 💬 [Discussions](https://github.com/jieyefriic/code-context/discussions)

---

Made with ❤️ for the AI coding community