Merge remote-tracking branch 'origin/main' into feat/mcp-prompts-revise

README.md

@@ -10,53 +10,88 @@ 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 forwards bug description data (ticket) to a remote endpoint for prediction and analysis.
+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 an MCP tool `ds_bug_localization` for bug localization
-- Forwards issue data (key, summary, description) to a configurable remote endpoint
-- Returns predicted source code locations and the prompt used in the process
+- 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
+   - fastmcp
+   - httpx
+   - loguru
+   - pydantic
+   - dotenv
+   - uv
 
 ## Setup
 1. Clone the repository:
-   ```sh
-   git clone <your-repo-url>
-   cd defect-solver-mcp-server
-   ```
+    ```sh
+    git clone <your-repo-url>
+    cd defect_solver_mcp_server
+    ```
 2. Install dependencies using uv:
-   ```sh
-   uv sync
-   ```
+    ```sh
+    uv sync
+    ```
 3. Configure environment variables:
-   - Copy `.env.example` to `.env` and set `DS_API_BASE_URL` and `DS_API_ENDPOINT` if needed.
+    - 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 `ds_bug_localization` tool via MCP.
+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
 
 ## Configuration
-- API base URL and endpoint are configured in `utils/config.py` and via environment variables (`DS_API_BASE_URL`, `DS_API_ENDPOINT`).
-- Timeout is also configurable in `utils/config.py`.
+- 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
-utils/config.py        # API configuration
-utils/model.py         # Pydantic models for requests
+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