# Issue Fix MCP Server

A Model Context Protocol (MCP) server that enables coding agents to search for and record software issue fixes with semantic search capabilities. Issues are stored with embeddings for intelligent similarity-based retrieval using natural language queries.

## Features

- **Semantic Search**: Find similar issues using natural language queries powered by local embeddings
- **Local Embeddings**: Uses sentence-transformers (all-MiniLM-L6-v2) for 100% local operation - no API keys needed
- **Vector Search**: Leverages PostgreSQL with pgvector extension for efficient similarity search
- **Rich Issue Data**: Track title, description, language, project, error messages, recreation steps, and fixes
- **Full CRUD Operations**: Create, read, update, delete, list, and search issue records
- **Filter Support**: Filter searches and lists by programming language or project identifier

## Architecture

- **Language**: Python
- **Database**: PostgreSQL with pgvector extension
- **Embeddings**: Local sentence-transformers (384-dimensional vectors)
- **MCP SDK**: Official Anthropic MCP Python SDK

## Prerequisites

- Python 3.8 or higher
- PostgreSQL 12 or higher with pgvector extension
- At least 500MB free disk space (for embedding model)

## Installation

### 1. Clone the Repository

```bash
git clone <repository-url>
cd issue-fix-mcp
```

### 2. Install Python Dependencies

```bash
pip install -r requirements.txt
```

On first run, sentence-transformers will download the embedding model (~90MB).

### 3. Set Up PostgreSQL

Install PostgreSQL if not already installed:

```bash
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql

# Start PostgreSQL service
sudo service postgresql start  # Linux
brew services start postgresql  # macOS
```

### 4. Install pgvector Extension

```bash
# Ubuntu/Debian
sudo apt-get install postgresql-14-pgvector

# macOS
brew install pgvector

# Or build from source
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install
```

### 5. Create Database

```bash
# Connect to PostgreSQL
sudo -u postgres psql

# Create database and user
CREATE DATABASE issue_fixes;
CREATE USER issue_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE issue_fixes TO issue_user;
\q
```

### 6. Configure Environment

Copy the example environment file and update with your database credentials:

```bash
cp .env.example .env
```

Edit `.env`:

```env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=issue_fixes
DB_USER=issue_user
DB_PASSWORD=your_secure_password
EMBEDDING_MODEL=all-MiniLM-L6-v2
```

### 7. Initialize Database Schema

The schema will be automatically initialized on first run, or you can manually run:

```bash
psql -U issue_user -d issue_fixes -f schema.sql
```

## Usage

### Running the Server

The MCP server runs via stdio transport:

```bash
python server.py
```

### Connecting from Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "issue-fix": {
      "command": "python",
      "args": ["/absolute/path/to/issue-fix-mcp/server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "issue_fixes",
        "DB_USER": "issue_user",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}
```

Restart Claude Desktop after configuration.

## Available Tools

### 1. create_issue

Create a new issue fix record with automatic embedding generation.

**Parameters:**
- `title` (required): Brief title of the issue
- `issue_description` (required): Detailed description
- `language` (optional): Programming language (e.g., "Python", "JavaScript")
- `project_identifier` (optional): Project name or identifier
- `error_message` (optional): Error message text
- `recreation_steps` (optional): Steps to recreate the issue
- `fix_description` (optional): Description of the fix/solution

**Example:**
```
Create an issue fix record:
- Title: "TypeError when parsing JSON with null values"
- Description: "Application crashes when API returns JSON with null fields"
- Language: "Python"
- Project: "api-client"
- Error: "TypeError: 'NoneType' object is not subscriptable"
- Fix: "Added null checks before accessing dictionary keys"
```

### 2. search_issues

Semantically search for similar issues using natural language.

**Parameters:**
- `query` (required): Natural language search query
- `limit` (optional): Maximum results (default: 10)
- `language` (optional): Filter by programming language
- `project_identifier` (optional): Filter by project

**Example:**
```
Search for issues about: "JSON parsing errors with null values in Python"
```

### 3. get_issue

Retrieve a specific issue by ID.

**Parameters:**
- `issue_id` (required): The issue ID number

**Example:**
```
Get issue #42
```

### 4. update_issue

Update an existing issue record. Automatically regenerates embeddings if searchable fields change.

**Parameters:**
- `issue_id` (required): The issue ID to update
- Any other field from create_issue (all optional)

**Example:**
```
Update issue #42 with a better fix description:
"Added comprehensive null checks and default values for all optional fields"
```

### 5. delete_issue

Permanently delete an issue record.

**Parameters:**
- `issue_id` (required): The issue ID to delete

**Example:**
```
Delete issue #42
```

### 6. list_issues

List all issues with optional filtering.

**Parameters:**
- `language` (optional): Filter by programming language
- `project_identifier` (optional): Filter by project
- `limit` (optional): Maximum results (default: 100)
- `offset` (optional): Number of results to skip (default: 0)

**Example:**
```
List all Python issues in the api-client project
```

## How Semantic Search Works

1. **Embedding Generation**: When creating/updating an issue, the system generates a 384-dimensional vector embedding from the combined text of:
   - Title (weighted 2x)
   - Issue description
   - Error message (weighted 2x)
   - Fix description

2. **Query Processing**: Search queries are converted to embeddings using the same model

3. **Similarity Matching**: PostgreSQL's pgvector performs cosine similarity search to find the most relevant issues

4. **Ranking**: Results are ranked by similarity score (0-100%)

## Database Schema

```sql
CREATE TABLE issues (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    issue_description TEXT NOT NULL,
    language TEXT,
    project_identifier TEXT,
    error_message TEXT,
    recreation_steps TEXT,
    fix_description TEXT,
    embedding vector(384),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## Performance Notes

- **First Run**: The embedding model (~90MB) downloads automatically on first use
- **Embedding Speed**: ~50-100ms per issue on modern CPUs
- **Search Speed**: Sub-100ms for databases with <100k issues
- **Storage**: ~500 bytes per issue (plus embedding vector)

## Troubleshooting

### "pgvector extension not found"
```bash
# Install pgvector extension
sudo apt-get install postgresql-14-pgvector
# Then reconnect to database and run:
CREATE EXTENSION vector;
```

### "Connection refused" errors
- Ensure PostgreSQL is running: `sudo service postgresql status`
- Check database credentials in `.env`
- Verify database exists: `psql -l`

### Slow embedding generation
- First run downloads the model (~90MB)
- CPU-only inference is normal; GPU not required
- Subsequent runs use cached model

### Import errors
```bash
# Reinstall dependencies
pip install --upgrade -r requirements.txt
```

## Development

### Project Structure

```
issue-fix-mcp/
├── server.py           # Main MCP server implementation
├── database.py         # Database operations layer
├── embeddings.py       # Local embedding service
├── config.py          # Configuration management
├── schema.sql         # Database schema
├── requirements.txt   # Python dependencies
├── .env.example      # Environment template
└── README.md         # This file
```

### Adding New Features

1. **New fields**: Update `schema.sql`, `database.py`, and `server.py`
2. **Different embedding model**: Change `EMBEDDING_MODEL` in `.env` (must match vector dimension)
3. **Custom search logic**: Modify `DatabaseService.search_issues()` in `database.py`

## Testing

The project includes a comprehensive test suite with >90% code coverage.

### Running Tests

```bash
# Quick verification
python verify_tests.py

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run with coverage report
make test-cov

# Use interactive test runner
./run_tests.sh -v -c
```

### Test Suite

- **65 unit tests** across 4 test files
- **100% mocked dependencies** - no external services required
- **Fast execution** - full suite runs in <10 seconds
- **CI/CD integration** - automated testing on push/PR

### Test Coverage

| Module | Coverage Target |
|--------|-----------------|
| config.py | 100% |
| embeddings.py | >95% |
| database.py | >90% |
| server.py | >85% |
| **Overall** | **>90%** |

### Documentation

- **TESTING.md** - Comprehensive testing guide
- **TEST_SUMMARY.md** - Test suite overview and metrics

See [TESTING.md](TESTING.md) for detailed testing documentation.

## License

MIT License - See LICENSE file for details

## Contributing

Contributions welcome! Please open an issue or pull request.

## Support

For issues and questions:
- Open a GitHub issue
- Check existing issues for solutions
- Review PostgreSQL and pgvector documentation