metadata

title: Defect Solver MCP
emoji: 🛠️
colorFrom: purple
colorTo: yellow
sdk: docker
pinned: false
short_description: Defect Solver - MCP Server

Defect Solver MCP Server

This project implements a Model Context Protocol (MCP) server for defect solver bug localization using FastMCP. It provides multiple bug localization tools that forward bug report data to remote endpoints for prediction and analysis.

Features

Exposes three MCP tools for bug localization:
- multi_module_bug_localization: Localizes bugs across the entire microservice architecture
- single_module_bug_localization: Localizes bugs within a specific module
- search_space_routing: Identifies likely microservices (search spaces) for a reported bug
Forwards issue data (key, summary, description, and optionally module) to configurable remote endpoints
Returns predicted source code locations and detailed workflow prompts
Uses async HTTP requests and robust error handling
Includes workflow and prompt templates for end-to-end bug localization and resolution

Requirements

Python >= 3.13
See pyproject.toml for dependencies:
- fastmcp
- httpx
- loguru
- pydantic
- dotenv
- uv

Note: The tools implemented in this server require a DEFECT SOLVER API KEY to send requests. To get your key, please contact Lokum AI.

Setup

Clone the repository:

git clone <your-repo-url>
cd defect_solver_mcp_server

Install dependencies using uv:
```
uv sync
```
Configure environment variables:
- Copy .env.example to .env and set the following as needed:
  - DS_API_BASE_URL
  - DS_API_MULTIMODULE_ENDPOINT
  - DS_API_SINGLEMODULE_ENDPOINT
  - DS_API_SEARCHSPACE_ENDPOINT
  - HF_ACCESS_TOKEN (optional)
  - TIMEOUT (optional)

Usage

Run the MCP server:

python main.py

The server will start and expose the bug localization tools via MCP.

Available Tools

multi_module_bug_localization: Use when the responsible microservice is unknown. Returns likely microservices and localized files.
single_module_bug_localization: Use when the affected module is known. Returns localized files within the specified module.
search_space_routing: Use to identify the most likely microservices (search spaces) for a reported bug.

Prompts & Workflow

The server provides prompt templates for:

Tool selection and workflow planning
Bug report augmentation
Bug localization and result explanation
Automated bug fixing and full resolution workflow

NOTE: There is a `chatmode.md` file personalized for DNext development that provides detailed instructions and rules on how to use the MCP server with chat-based interactions in IDEs like VSCode, Cursor, Windsurf and etc. Please refer to the dnext-chatmode.md for more information.

Configuration

API base URL and endpoints are configured in utils/config.py and via environment variables:
- DS_API_BASE_URL, DS_API_MULTIMODULE_ENDPOINT, DS_API_SINGLEMODULE_ENDPOINT, DS_API_SEARCHSPACE_ENDPOINT
Timeout and HuggingFace access token are also configurable.

MCP Inspector

The MCP Inspector is a tool to help you visualize and debug the interactions with the MCP server. To use the MCP Inspector, simply run the command below in your terminal:

npx @modelcontextprotocol/inspector

The GUI will open in your default web browser, allowing you to monitor the communication with the MCP server in real-time:

Project Structure

main.py                # Entry point and MCP server with tool and prompt definitions
utils/config.py        # API configuration and environment variable loading
utils/model.py         # Pydantic models for request payloads
pyproject.toml         # Project metadata and dependencies
README.md              # Project documentation
.env.example           # Example environment configuration

`mcp.json` Configuration Example for Client Usage

To use this MCP server in a client application that supports MCP, you add the config below to mcp.json.

PRIVATE MCP SERVER: This config is required for when deploying the MCP server in a private Hugging Face Space that requires authentication.

{
    "servers": {
        "ds": {
            "url": "https://dnext-ds-mcp-server.hf.space/mcp/",
            "type": "http",
            "headers": {
                "DS-API-Key": "${input:defect-solver-api-key}",
                "Authorization": "Bearer ${input:hf-access-token}"
            }
        }
    },
    "inputs": [
            {
                "type": "promptString",
                "id": "defect-solver-api-key",
                "description": "Enter your Defect Solver API Key",
                "password": true
            },
            {
                "type": "promptString",
                "id": "hf-access-token",
                "description": "Enter your Hugging Face Access Token",
                "password": true
            }
    ]   
}

PUBLIC MCP SERVER: For public spaces, you can omit the `hf-access-token` input or `Authorization` header.

{
    "servers": {
        "ds": {
            "url": "https://dnext-ds-mcp-server.hf.space/mcp/",
            "type": "http",
            "headers": {
                "DS-API-Key": "${input:defect-solver-api-key}"
            }
        }
    },
    "inputs": [
        {
            "type": "promptString",
            "id": "defect-solver-api-key",
            "description": "Enter your Defect Solver API Key",
            "password": true
        }
    ]
}