README.md

---
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](https://github.com/lokumai).

## Setup
1. Clone the repository:
    ```sh
    git clone <your-repo-url>
    cd defect_solver_mcp_server
    ```
2. Install dependencies using uv:
    ```sh
    uv sync
    ```
3. 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:
```sh
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](https://github.com/pia-team/defect_solver_api/blob/main/.github/chatmodes/dnext-defect-solver.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:

```sh
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:

<img src="https://raw.githubusercontent.com/modelcontextprotocol/inspector/main/mcp-inspector.png" alt="MCP Inspector">

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

```json
{
    "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.

```json
{
    "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
        }
    ]
}
```