Issue Fix

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

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

2. Install Python Dependencies

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:

# 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

# 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

# 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:

cp .env.example .env

Edit .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:

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

Usage

Running the Server

The MCP server runs via stdio transport:

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):

{
  "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

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"

# 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

# 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

# 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 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