Spaces:
Paused
Paused
| 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 | |
| } | |
| ] | |
| } | |
| ``` | |