Issue Fix MCP

问题修复MCP服务器

一种模型上下文协议（MCP）服务器，使编码代理能够使用语义搜索功能搜索和记录软件问题修复。问题与嵌入一起存储，用于使用自然语言查询进行基于相似性的智能检索。

特性

• 语义搜索：使用由本地嵌入支持的自然语言查询查找类似问题
• 本地嵌入：使用语句转换器（all-MiniLM-L6-v2）进行100%本地操作-不需要API密钥
• 矢量搜索：利用PostgreSQL和pgvector扩展进行高效的相似性搜索
• 丰富的问题数据：跟踪标题、描述、语言、项目、错误消息、重新创建步骤和修复
• 完整的CRUD操作：创建、读取、更新、删除、列出和搜索问题记录
• 过滤器支架：按编程语言或项目标识符筛选搜索和列表

建筑

• 语言python
• 数据库：带有pgvector扩展名的PostgreSQL
• 嵌入：局部句子变换器（384维向量）
• MCP-SDK：官方Anthropic MCP Python SDK

先决条件

• Python 3.8或更高版本
• PostgreSQL 12或更高版本，带pgvector扩展
• 至少500MB可用磁盘空间（用于嵌入式型号）

安装

1.克隆存储库

git clone 
cd issue-fix-mcp

2.安装Python依赖项

pip install -r requirements.txt

在第一次运行时，句子转换器将下载嵌入模型（~90MB）。

3.设置PostgreSQL

如果尚未安装PostgreSQL，请安装：

# 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.安装pgvector扩展

# 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.创建数据库

# 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.配置环境

复制示例环境文件并使用您的数据库凭据进行更新：

cp .env.example .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.初始化数据库架构

架构将在首次运行时自动初始化，或者您可以手动运行：

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

用法

运行服务器

MCP服务器通过stdio传输运行：

python server.py

从克劳德桌面连接

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在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"
      }
    }
  }
}

配置后重新启动Claude Desktop。

可用工具

1.创建_发行

通过自动嵌入生成创建新的问题修复记录。

参数：

• title （必填）：问题的简要标题
• issue_description （必填）：详细说明
• language （可选）：编程语言（例如“Python”、“JavaScript”）
• project_identifier （可选）：项目名称或标识符
• error_message （可选）：错误消息文本
• recreation_steps （可选）：重新创建问题的步骤
• fix_description （可选）：修复/解决方案的描述

例子：

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.搜索问题

使用自然语言语义搜索类似问题。

参数：

• query （必填）：自然语言搜索查询
• limit （可选）：最大结果（默认值：10）
• language （可选）：按编程语言筛选
• project_identifier （可选）：按项目筛选

例子：

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

3.获取问题

按ID检索特定问题。

参数：

• issue_id （必填）：问题ID号

例子：

Get issue #42

4.更新_问题

更新现有问题记录。如果可搜索字段发生变化，则自动重新生成嵌入。

参数：

• issue_id （必填）：要更新的问题ID
• create_issue中的任何其他字段（均为可选）

例子：

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

5.删除问题

永久删除问题记录。

参数：

• issue_id （必填）：要删除的问题ID

例子：

Delete issue #42

6.列表_问题

列出可选过滤的所有问题。

参数：

• language （可选）：按编程语言筛选
• project_identifier （可选）：按项目筛选
• limit （可选）：最大结果（默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）

例子：

List all Python issues in the api-client project

语义搜索的工作原理

1. 嵌入生成：在创建/更新问题时，系统从以下组合文本生成384维向量嵌入：

- 标题（权重2x） - 问题描述 - 错误消息（加权2x） - 修复说明

1. 查询处理：使用相同的模型将搜索查询转换为嵌入

1. 相似性匹配PostgreSQL的pgvector执行余弦相似性搜索，以找到最相关的问题

1. 排名：结果按相似性得分排名（0-100%）

数据库模式

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

业绩说明

• 首次运行：首次使用时，嵌入模型（~90MB）会自动下载
• 嵌入速度：在现代CPU上，每期约50-100ms
• 搜索速度：对于问题小于10万的数据库，低于1000毫秒
• 存储：每期约500字节（加上嵌入向量）

故障排除

“找不到pgvector扩展名”

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

“连接被拒绝”错误

• 确保PostgreSQL正在运行： sudo service postgresql status
• 检查中的数据库凭据 .env
• 验证数据库是否存在： psql -l

嵌入生成缓慢

• 第一次运行下载模型（~90MB）
• 仅CPU推理正常；不需要GPU
• 后续运行使用缓存模型

导入错误

# Reinstall dependencies
pip install --upgrade -r requirements.txt

发展

项目结构

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

添加新功能

1. 新领域：更新 schema.sql, database.py，以及 server.py
2. 不同的嵌入模型：更改 EMBEDDING_MODEL 在 .env （必须与向量维度匹配）
3. 自定义搜索逻辑：修改 DatabaseService.search_issues() 在 database.py

测试

该项目包括一个代码覆盖率超过90%的全面测试套件。

运行测试

# 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

测试套件

• 65个单元测试 跨越4个测试文件
• 100%模拟依赖关系 -无需外部服务
• 快速执行 -整套运行时间不超过10秒
• CI/CD集成 -push/PR的自动化测试

测试覆盖率

文档

• 测试.md -全面的测试指南
• 测试\_ SUMMARY.md -测试套件概述和指标

看 测试.md 获取详细的测试文档。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请打开问题或拉取请求。

支持

对于问题和疑问：

• 打开GitHub问题
• 检查现有问题的解决方案
• 查看PostgreSQL和pgvector文档