### Developer Installation of MCP Feedback Enhanced

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Steps to clone the repository, navigate to the directory, and install dependencies using uv sync for developer setup.

```bash
git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
```

```bash
cd mcp-feedback-enhanced
```

```bash
uv sync
```

--------------------------------

### MCP Server Configuration Examples

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Examples of mcp.json configurations for different operating modes: Web UI, Desktop Application, and SSH Remote.

```APIDOC
## MCP Server Configuration (pyproject.toml / MCP JSON)

The server is distributed as the `mcp-feedback-enhanced` PyPI package and is typically run via `uvx`. The MCP host (e.g., Cursor) is configured with a JSON block that sets environment variables controlling interface mode, host binding, port, and debug output.

```json
// ~/.cursor/mcp.json  (Web UI mode — default, SSH/WSL-safe)
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

```json
// Desktop application mode (Windows / macOS / Linux with a display)
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

```json
// SSH Remote mode — expose the web server on all interfaces
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "false",
        "MCP_WEB_HOST": "0.0.0.0",
        "MCP_WEB_PORT": "8765"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```
```

--------------------------------

### Install mcp-feedback-enhanced

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/release_body.md

Use these commands to install the latest version or a specific version of the mcp-feedback-enhanced package using uvx.

```bash
# Latest version / 最新版本
uvx mcp-feedback-enhanced@latest
```

```bash
# This specific version / 此特定版本
uvx mcp-feedback-enhanced@v2.6.0
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Installs the uv package manager, which is required for the project. Ensure you have Python installed.

```bash
pip install uv
```

--------------------------------

### WebUIManager Class Initialization and Server Start

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Manually instantiate and start the WebUIManager, which manages the FastAPI application and Uvicorn server thread. Prefer `get_web_ui_manager()` for lazy instantiation.

```python
from mcp_feedback_enhanced.web import WebUIManager, get_web_ui_manager, stop_web_ui
import asyncio

# --- Manual instantiation (rarely needed; prefer get_web_ui_manager()) ---
manager = WebUIManager(host="127.0.0.1", port=8765)
manager.start_server()          # starts Uvicorn in a background daemon thread
```

--------------------------------

### GET /api/load-settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Loads and returns the persisted user interface settings.

```APIDOC
## GET /api/load-settings

### Description
Retrieves the previously saved UI settings from the configuration file.

### Method
GET

### Endpoint
/api/load-settings

### Response
#### Success Response (200)
An object containing the persisted UI settings, such as `layoutMode`, `language`, etc.

### Response Example
```json
{
  "layoutMode": "combined-vertical",
  "language": "en",
  ...
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/load-settings
```
```

--------------------------------

### Get System Information with `get_system_info` Tool

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

This Python snippet shows how to use the `get_system_info` MCP tool to retrieve a JSON snapshot of the current runtime environment. It's useful for verifying environment detection (local, SSH, WSL, Docker) before interface selection.

```python
from fastmcp import Client
import asyncio, json

async def demo():
    async with Client("mcp-feedback-enhanced") as client:
        raw = await client.call_tool("get_system_info", {})
        info = json.loads(raw[0].text)
        print(json.dumps(info, ensure_ascii=False, indent=2))

asyncio.run(demo())
# Expected output (example on a local macOS machine):
# {
#   "平台": "darwin",
#   "Python 版本": "3.11.9",
#   "WSL 環境": false,
#   "遠端環境": false,
#   "介面類型": "Web UI",
#   "環境變數": {
#     "SSH_CONNECTION": null,
#     "DISPLAY": null,
#     "WSL_DISTRO_NAME": null,
#     ...
#   }
# }
```

--------------------------------

### launch_web_feedback_ui Function

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

The `launch_web_feedback_ui` coroutine orchestrates the feedback process. It creates or reuses the `WebUIManager`, starts the Uvicorn server, opens the browser or desktop app, and waits for user input. It returns a dictionary containing interactive feedback, logs, images, and settings.

```APIDOC
## `launch_web_feedback_ui` Function

### Description
This function orchestrates the full feedback cycle: creates/reuses the singleton `WebUIManager`, starts the Uvicorn server if not already running, opens the browser or desktop app (skipping if a live WebSocket tab is detected), and awaits user input.

### Parameters
- **project_directory** (string) - Required - The root directory of the project.
- **summary** (string) - Required - A markdown-formatted summary of the current state or action.
- **timeout** (integer) - Optional - The maximum time in seconds to wait for user feedback. Defaults to 600.

### Returns
A dictionary containing:
- **interactive_feedback** (string) - The text feedback provided by the user.
- **logs** (string) - Command logs generated during the feedback process.
- **images** (list) - A list of dictionaries, where each dictionary represents an image with keys 'name' (string), 'data' (bytes), and 'size' (integer).
- **settings** (dict) - User-submitted settings.

### Request Example
```python
import asyncio, os
from mcp_feedback_enhanced.web import launch_web_feedback_ui

async def main():
    result = await launch_web_feedback_ui(
        project_directory=os.getcwd(),
        summary=(
            "## ✅ Refactoring Complete\n\n"
            "- Extracted `UserService` from `models.py`\n"
            "- Added 12 unit tests (all passing)\n\n"
            "Please review and tell me what to tackle next."
        ),
        timeout=600,
    )

    print("Text feedback :", result["interactive_feedback"])
    print("Command logs  :", result["logs"])
    print("Images count  :", len(result["images"]))
    # Each image: {"name": "screenshot.png", "data": b"<bytes>", "size": 204800}

    # Access raw image bytes
    for img in result["images"]:
        with open(f"/tmp/{img['name']}", "wb") as f:
            f.write(img["data"])

    # Settings submitted by the user (e.g. image_size_limit)
    print("Settings:", result["settings"])

asyncio.run(main())
```

### Response Example (Success)
```json
{
  "interactive_feedback": "Looks good, proceed with the next step.",
  "logs": "... command logs ...",
  "images": [
    {
      "name": "screenshot.png",
      "data": b"<bytes>",
      "size": 204800
    }
  ],
  "settings": {
    "image_size_limit": 512000
  }
}
```
```

--------------------------------

### Get All Sessions Sorted by Creation Time

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieve a list of all available sessions, sorted with the newest sessions appearing first. Includes session ID and status.

```bash
# GET /api/all-sessions — all sessions sorted by creation time (newest first)
curl http://127.0.0.1:8765/api/all-sessions
# {"sessions": [{"session_id": "...", "status": "waiting", "is_current": true, ...}]}
```

--------------------------------

### Check MCP Feedback Enhanced Version

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Command to check the installed version of mcp-feedback-enhanced using uvx.

```bash
uvx mcp-feedback-enhanced@latest version
```

--------------------------------

### Get All i18n Strings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Fetch all internationalization (i18n) strings for specified languages, including Traditional Chinese (zh-TW), Simplified Chinese (zh-CN), and English (en).

```bash
# GET /api/translations — all i18n strings for zh-TW, zh-CN, en
curl http://127.0.0.1:8765/api/translations
```

--------------------------------

### Get Full Details of Active Session

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieve comprehensive details for the currently active session, including its ID, project directory, summary, and feedback status.

```bash
# GET /api/current-session — full details of the active session
curl http://127.0.0.1:8765/api/current-session
# {
#   "session_id": "3f2a...",
#   "project_directory": "/home/user/project",
#   "summary": "...",
#   "feedback_completed": false,
#   "command_logs": [],
#   "images_count": 0
# }
```

--------------------------------

### GET / — HTML Feedback Page

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieves the main HTML feedback page. If no active session exists, it displays a waiting page.

```APIDOC
## GET /

### Description
Serves the primary HTML interface for user feedback. If an active session is available, it displays the feedback UI; otherwise, it shows a waiting page.

### Method
GET

### Endpoint
/

### Request Example
```bash
curl http://127.0.0.1:8765/
```
```

--------------------------------

### GET /api/all-sessions

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieves a list of all available sessions, sorted by creation time with the newest first.

```APIDOC
## GET /api/all-sessions

### Description
Fetches a list of all recorded feedback sessions, ordered chronologically with the most recently created sessions appearing first.

### Method
GET

### Endpoint
/api/all-sessions

### Response
#### Success Response (200)
- **sessions** (array) - An array of session objects, each containing details like `session_id`, `status`, and `is_current`.

### Response Example
```json
{
  "sessions": [
    {
      "session_id": "...",
      "status": "waiting",
      "is_current": true,
      ...
    }
  ]
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/all-sessions
```
```

--------------------------------

### Build Desktop Application

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Commands for building the desktop application. Use `make build-desktop` for debug mode and `make build-desktop-release` for release mode. `make test-desktop` runs tests, and `make clean-desktop` removes build artifacts.

```bash
make build-desktop
```

```bash
make build-desktop-release
```

```bash
make test-desktop
```

```bash
make clean-desktop
```

--------------------------------

### Launch Web Feedback UI and Process Results

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Launches the web UI for interactive feedback, processes the results including text feedback, logs, and images. Saves raw image bytes to disk. Requires asyncio and os imports.

```python
import asyncio, os
from mcp_feedback_enhanced.web import launch_web_feedback_ui, stop_web_ui

async def main():
    # Web UI mode
    result = await launch_web_feedback_ui(
        project_directory=os.getcwd(),
        summary=(
            "## ✅ Refactoring Complete\n\n"
            "- Extracted `UserService` from `models.py`\n"
            "- Added 12 unit tests (all passing)\n\n"
            "Please review and tell me what to tackle next."
        ),
        timeout=600,    # seconds; MCP default is 600
    )

    print("Text feedback :", result["interactive_feedback"])
    print("Command logs  :", result["logs"])
    print("Images count  :", len(result["images"]))
    # Each image: {"name": "screenshot.png", "data": b"<bytes>", "size": 204800}

    # Access raw image bytes
    for img in result["images"]:
        with open(f"/tmp/{img['name']}", "wb") as f:
            f.write(img["data"])

    # Settings submitted by the user (e.g. image_size_limit)
    print("Settings:", result["settings"])

asyncio.run(main())

# To stop the server when done (optional — the server is designed to persist)
stop_web_ui()
```

--------------------------------

### GET /api/load-session-history

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Loads the session history from a file.

```APIDOC
## GET /api/load-session-history

### Description
Retrieves the history of feedback sessions from a persistent storage file.

### Method
GET

### Endpoint
/api/load-session-history

### Response
#### Success Response (200)
- **sessions** (array) - An array containing historical session data.
- **lastCleanup** (integer) - Timestamp of the last cleanup operation.

### Response Example
```json
{
  "sessions": [...],
  "lastCleanup": 1718000000000
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/load-session-history
```
```

--------------------------------

### Create and Inspect WebFeedbackSession

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Instantiate a WebFeedbackSession directly or via WebUIManager.create_session(). Inspect its status, activity, and terminal state. Requires session_id and project_directory.

```python
session = WebFeedbackSession(
    session_id="abc-123",
    project_directory="/home/user/project",
    summary="Refactored DB layer.",
    auto_cleanup_delay=3600,   # seconds before auto-expire
    max_idle_time=1800,        # seconds of inactivity before is_expired() → True
)

# Inspect state
print(session.status)                   # SessionStatus.WAITING
print(session.is_active())              # True
print(session.is_terminal())            # False
print(session.get_status_info())
# {'status': 'waiting', 'message': '等待用戶回饋', 'feedback_completed': False, ...}
```

--------------------------------

### GET /api/log-level

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Reads the current log level setting.

```APIDOC
## GET /api/log-level

### Description
Retrieves the currently configured log level for the application.

### Method
GET

### Endpoint
/api/log-level

### Response
#### Success Response (200)
- **logLevel** (string) - The current log level (e.g., "INFO").

### Response Example
```json
{
  "logLevel": "INFO"
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/log-level
```
```

--------------------------------

### GET /api/translations

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Fetches all internationalization (i18n) strings for supported languages.

```APIDOC
## GET /api/translations

### Description
Retrieves all available internationalization strings used by the application for the specified languages (e.g., zh-TW, zh-CN, en).

### Method
GET

### Endpoint
/api/translations

### Response
#### Success Response (200)
Contains key-value pairs of i18n strings for each supported language.

### Request Example
```bash
curl http://127.0.0.1:8765/api/translations
```
```

--------------------------------

### GET /api/current-session

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieves detailed information about the currently active feedback session.

```APIDOC
## GET /api/current-session

### Description
Fetches comprehensive details of the active feedback session, including its ID, project directory, summary, and feedback status.

### Method
GET

### Endpoint
/api/current-session

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier of the session.
- **project_directory** (string) - The path to the project associated with the session.
- **summary** (string) - A summary description of the session.
- **feedback_completed** (boolean) - Indicates if feedback has been completed for this session.
- **command_logs** (array) - Logs of commands executed during the session.
- **images_count** (integer) - The number of images associated with the session.

### Response Example
```json
{
  "session_id": "3f2a...",
  "project_directory": "/home/user/project",
  "summary": "...",
  "feedback_completed": false,
  "command_logs": [],
  "images_count": 0
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/current-session
```
```

--------------------------------

### GET /api/session-status

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Fetches the current session's presence and basic state information.

```APIDOC
## GET /api/session-status

### Description
Retrieves the current status of the feedback session, indicating whether a session is active and its basic state.

### Method
GET

### Endpoint
/api/session-status

### Response
#### Success Response (200)
- **has_session** (boolean) - Indicates if an active session exists.
- **status** (string) - The current status of the session (e.g., "active").
- **session_info** (object) - Basic information about the session.

### Response Example
```json
{
  "has_session": true,
  "status": "active",
  "session_info": {}
}
```

### Request Example
```bash
curl http://127.0.0.1:8765/api/session-status
```
```

--------------------------------

### Web Feedback Session Initialization

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Demonstrates how to initialize a WebFeedbackSession directly, bypassing the WebUIManager. Provides parameters for session configuration.

```APIDOC
## WebFeedbackSession Initialization

### Description
Initializes a new feedback session with specified parameters. This can be used directly or is typically created by `WebUIManager.create_session()`.

### Parameters
- **session_id** (str) - Unique identifier for the session.
- **project_directory** (str) - Path to the project directory.
- **summary** (str) - A brief summary of the session's purpose.
- **auto_cleanup_delay** (int, optional) - Delay in seconds before automatic cleanup. Defaults to 3600.
- **max_idle_time** (int, optional) - Maximum idle time in seconds before the session is considered expired. Defaults to 1800.

### Code Example
```python
session = WebFeedbackSession(
    session_id="abc-123",
    project_directory="/home/user/project",
    summary="Refactored DB layer.",
    auto_cleanup_delay=3600,
    max_idle_time=1800,
)
```
```

--------------------------------

### WebUIManager: Creating and Managing Feedback Sessions

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Create a new feedback session, retrieve the current session, and access its ID. This demonstrates the workflow for initiating an AI-user interaction round-trip.

```python
# Create a feedback session
session_id = manager.create_session(
    project_directory="/home/user/project",
    summary="I added a login endpoint. Please review."
)
session = manager.get_current_session()
print(session.session_id)       # UUID string
```

--------------------------------

### Running Shell Commands

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Details how to execute shell commands and stream their output through the WebSocket.

```APIDOC
## Run Shell Command

### Description
Executes a given shell command and streams its output (stdout and stderr) and completion status over the WebSocket connection.

### Method
- **session.run_command(command: str)**: Executes the specified command.
  - **command** (str): The shell command to execute.

### Behavior
- Sends `{"type": "command_output", "output": "..."}` messages for command output.
- Sends `{"type": "command_complete", "exit_code": 0}` when the command finishes.

### Code Example
```python
async def run():
    await session.run_command("pytest tests/ -v")
```
```

--------------------------------

### Load UI Settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieve persisted UI settings from the configuration file. This endpoint allows loading previously saved user preferences.

```bash
# GET /api/load-settings — load persisted UI settings
curl http://127.0.0.1:8765/api/load-settings
# {"layoutMode": "combined-vertical", "language": "en", ...}
```

--------------------------------

### Get Current Log Level

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Read the current log level setting from the configuration. The log level determines the verbosity of application logs.

```bash
# GET /api/log-level — read current log level from settings
curl http://127.0.0.1:8765/api/log-level
# {"logLevel": "INFO"}
```

--------------------------------

### Manual Resource Cleanup

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Demonstrates how to manually trigger the cleanup of session resources.

```APIDOC
## Manual Resource Cleanup

### Description
Manually initiates the cleanup process for the session's resources. This is an internal method but can be called directly for specific scenarios.

### Method
- **session._cleanup_resources_enhanced(reason: CleanupReason)**: Cleans up resources.
  - **reason** (CleanupReason): The reason for cleanup (e.g., `CleanupReason.MANUAL`).

### Code Example
```python
asyncio.run(session._cleanup_resources_enhanced(CleanupReason.MANUAL))
```
```

--------------------------------

### Get Current Session Status

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieve the presence and basic state of the current session. The response includes session activity and status information.

```bash
# GET /api/session-status — current session presence and basic state
curl http://127.0.0.1:8765/api/session-status
# {"has_session": true, "status": "active", "session_info": {...}}
```

--------------------------------

### WebUIManager: Opening Browser and Waiting for Feedback

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Open the web UI in the browser or desktop app and wait for user feedback. This includes retrieving the server URL and handling the feedback result, including text, images, and logs.

```python
# Open the browser (or desktop app if MCP_DESKTOP_MODE=true)
url = manager.get_server_url()  # "http://127.0.0.1:8765"
asyncio.run(manager.smart_open_browser(url))

# Wait for user feedback with a 5-minute timeout
result = asyncio.run(session.wait_for_feedback(timeout=300))
print(result["interactive_feedback"])   # user's text
print(len(result["images"]))            # number of attached images
print(result["logs"])                   # concatenated command output logs
```

--------------------------------

### Run Functional Tests Directly

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Alternative commands to run functional tests directly. Use `--web` for web UI testing and `--desktop` for desktop application testing.

```bash
uv run python -m mcp_feedback_enhanced test
```

```bash
uvx --no-cache --with-editable . mcp-feedback-enhanced test --web
```

```bash
uvx --no-cache --with-editable . mcp-feedback-enhanced test --desktop
```

--------------------------------

### Run Unit Tests

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Execute unit tests. `make test` runs all tests, `make test-fast` skips slow tests, and `make test-cov` generates a coverage report.

```bash
make test
```

```bash
make test-fast
```

```bash
make test-cov
```

--------------------------------

### get_system_info

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

A diagnostic MCP tool that provides a JSON snapshot of the current runtime environment. This is useful for verifying the server's detection of the execution context (SSH, WSL, Docker, local) and its interface selection logic.

```APIDOC
## get_system_info

### Description
This diagnostic tool returns a JSON object containing detailed information about the runtime environment. It helps in confirming the server's accurate detection of the execution context (e.g., SSH, WSL, Docker, local) and its chosen interface.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **{}** (object) - An empty object, as this tool does not require any parameters.

### Request Example
```python
from fastmcp import Client
import asyncio, json

async def demo():
    async with Client("mcp-feedback-enhanced") as client:
        raw = await client.call_tool("get_system_info", {{}})
        info = json.loads(raw[0].text)
        print(json.dumps(info, ensure_ascii=False, indent=2))

asyncio.run(demo())
```

### Response
#### Success Response (200)
- **raw** (string) - A string containing a JSON representation of the system information. The first element of the returned list is a TextContent object holding this JSON string.

#### Response Example
```json
{
  "平台": "darwin",
  "Python 版本": "3.11.9",
  "WSL 環境": false,
  "遠端環境": false,
  "介面類型": "Web UI",
  "環境變數": {
    "SSH_CONNECTION": null,
    "DISPLAY": null,
    "WSL_DISTRO_NAME": null,
    ...
  }
}
```
```

--------------------------------

### Desktop Application Configuration

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Configuration for using the native desktop application mode. It enables desktop mode and sets environment variables for web host, port, and debug settings.

```json
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

--------------------------------

### POST /api/save-settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Persists the user interface settings to a configuration file.

```APIDOC
## POST /api/save-settings

### Description
Saves the current UI settings, such as layout mode and language preferences, to a persistent configuration file located at `~/.config/mcp-feedback-enhanced/ui_settings.json`.

### Method
POST

### Endpoint
/api/save-settings

### Parameters
#### Request Body
- **layoutMode** (string) - The preferred layout mode (e.g., "combined-vertical").
- **language** (string) - The preferred language for the UI (e.g., "en").
- **logLevel** (string) - The preferred logging level (e.g., "INFO").

### Request Example
```json
{
  "layoutMode": "combined-vertical",
  "language": "en",
  "logLevel": "INFO"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").
- **messageCode** (string) - A code for internationalized messages (e.g., "settings.saved").

### Response Example
```json
{
  "status": "success",
  "messageCode": "settings.saved"
}
```

### Request Example
```bash
curl -X POST http://127.0.0.1:8765/api/save-settings \
  -H "Content-Type: application/json" \
  -d '{"layoutMode": "combined-vertical", "language": "en", "logLevel": "INFO"}'
```
```

--------------------------------

### Project-Provided Cache Cleanup Tool

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/docs/en/cache-management.md

Utilize the project's Python script for advanced cache management. Options include checking size, previewing cleanup, executing cleanup, and forcing cleanup.

```python
# Check cache size
python scripts/cleanup_cache.py --size

# Preview cleanup content
python scripts/cleanup_cache.py --dry-run

# Execute cleanup
python scripts/cleanup_cache.py --clean

# Force cleanup (attempts to close related processes)
python scripts/cleanup_cache.py --force
```

--------------------------------

### Basic MCP Configuration

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

A basic configuration suitable for most users. It defines the server command, arguments, timeout, and auto-approval settings.

```json
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

--------------------------------

### Check Cache Size

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/docs/en/cache-management.md

Monitor the cache size using either the project's cleanup script or native operating system commands. This helps in deciding when cleanup is necessary.

```bash
# Using cleanup tool
python scripts/cleanup_cache.py --size

# Or check directory size directly (Windows)
dir "%USERPROFILE%\AppData\Local\uv\cache" /s

# macOS/Linux
du -sh ~/.cache/uv
```

--------------------------------

### WebUIManager Class Usage

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Demonstrates how to use the WebUIManager class to manage the FastAPI application, Uvicorn server, feedback sessions, and browser opening.

```APIDOC
## `WebUIManager` Class

The singleton class that owns the FastAPI application, manages the Uvicorn server thread, tracks the single active `WebFeedbackSession`, and coordinates browser/desktop-app opening. Instantiated lazily via `get_web_ui_manager()`.

```python
from mcp_feedback_enhanced.web import WebUIManager, get_web_ui_manager, stop_web_ui
import asyncio

# --- Manual instantiation (rarely needed; prefer get_web_ui_manager()) ---
manager = WebUIManager(host="127.0.0.1", port=8765)
manager.start_server()          # starts Uvicorn in a background daemon thread

# Create a feedback session
session_id = manager.create_session(
    project_directory="/home/user/project",
    summary="I added a login endpoint. Please review."
)
session = manager.get_current_session()
print(session.session_id)       # UUID string

# Open the browser (or desktop app if MCP_DESKTOP_MODE=true)
url = manager.get_server_url()  # "http://127.0.0.1:8765"
asyncio.run(manager.smart_open_browser(url))

# Wait for user feedback with a 5-minute timeout
result = asyncio.run(session.wait_for_feedback(timeout=300))
print(result["interactive_feedback"])   # user's text
print(len(result["images"]))            # number of attached images
print(result["logs"])                   # concatenated command output logs

# Session cleanup stats
stats = manager.get_session_cleanup_stats()
print(stats["active_sessions"])         # int
print(stats["memory_usage_mb"])         # float

# Graceful shutdown
manager.cleanup_expired_sessions()     # remove sessions idle > max_idle_time
stop_web_ui()                          # stops server, clears all sessions
```
```

--------------------------------

### Save UI Settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Persist UI settings, such as layout mode and language, to a configuration file. Requires a POST request with a JSON payload.

```bash
# POST /api/save-settings — persist UI settings to ~/.config/mcp-feedback-enhanced/ui_settings.json
curl -X POST http://127.0.0.1:8765/api/save-settings \
  -H "Content-Type: application/json" \
  -d '{"layoutMode": "combined-vertical", "language": "en", "logLevel": "INFO"}'
# {"status": "success", "messageCode": "settings.saved"}
```

--------------------------------

### Run Code Quality Checks

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Perform code quality checks. `make check` runs a complete check, while `make quick-check` performs a quick check and attempts auto-fixing.

```bash
make check
```

```bash
make quick-check
```

--------------------------------

### Advanced MCP Configuration with Environment Variables

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

An advanced configuration that includes custom environment variables for debugging, web host, port, and language settings.

```json
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DEBUG": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_LANGUAGE": "en"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

--------------------------------

### Environment Detection Utilities

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Pure functions used to detect the execution environment (e.g., WSL, remote SSH, Docker) by inspecting system files and environment variables.

```APIDOC
## Environment Detection Utilities

### Description
These are pure functions located in `server.py` that are invoked prior to `interactive_feedback` to determine the current operating environment. They analyze system information such as `/proc/version`, specific WSL environment variables, SSH connection indicators, Docker sentinel files, and X11 display availability.

### WSL Detection
Detects if the current environment is Windows Subsystem for Linux (WSL).

```python
from mcp_feedback_enhanced.server import is_wsl_environment

if is_wsl_environment():
    print("Running in WSL")
```

### Remote Environment Detection
Detects if the current environment is a remote connection (e.g., via SSH).

```python
from mcp_feedback_enhanced.server import is_remote_environment

if is_remote_environment():
    print("Running in a remote environment")
```
```

--------------------------------

### WebFeedbackSession Class Imports

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Imports for the WebFeedbackSession class, including its status and cleanup reason enumerations. This class represents a single AI-user interaction round-trip.

```python
from mcp_feedback_enhanced.web.models.feedback_session import (
    WebFeedbackSession, SessionStatus, CleanupReason
)
import asyncio
```

--------------------------------

### Enable Desktop Application Mode

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

To enable the cross-platform desktop application support, set "MCP_DESKTOP_MODE" to "true" in your MCP configuration. This setting is part of the environment variables for a specific mcp server.

```json
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_PORT": "8765"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

--------------------------------

### Check and Clean UV Cache

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/docs/en/cache-management.md

Use built-in UV commands to check the cache directory and clean all cache files. This is the recommended method for cache management.

```bash
# Check cache location
uv cache dir

# Clean all cache
uv cache clean
```

--------------------------------

### Fetch HTML Feedback Page

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Retrieve the main HTML feedback page. If no active session exists, it displays a waiting page.

```bash
# GET / — HTML feedback page (or waiting page if no active session)
curl http://127.0.0.1:8765/
```

--------------------------------

### Programmatic Feedback Submission

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Demonstrates how to programmatically submit feedback, including text and image data, within a WebFeedbackSession.

```APIDOC
## Programmatic Feedback Submission

### Description
Allows for the submission of feedback data, including text content and a list of images, along with specific settings. This mirrors the functionality of the browser WebSocket.

### Method
- **session.submit_feedback(feedback: str, images: list, settings: dict)**: Submits the feedback.
  - **feedback** (str): The text content of the feedback.
  - **images** (list): A list of image objects, where each object is a dictionary with `name`, `data` (base64 encoded string), and `size`.
  - **settings** (dict): Configuration settings for the submission, such as `image_size_limit` and `enable_base64_detail`.

### Code Example
```python
async def simulate_submission():
    await session.submit_feedback(
        feedback="Looks great! Please add docstrings.",
        images=[],      # list of {"name": str, "data": base64_str, "size": int}
        settings={"image_size_limit": 1048576, "enable_base64_detail": False},
    )

asyncio.run(simulate_submission())
```
```

--------------------------------

### Manage UV Cache with Python Scripts

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

These Python scripts assist in managing the UV cache. Use `--size` to view cache details, `--dry-run` to preview cleanup, `--clean` for standard cleanup, and `--force` to attempt closing related programs for stubborn file occupation issues on Windows. Alternatively, use the `uv cache clean` command.

```bash
# View cache size and detailed information
python scripts/cleanup_cache.py --size
```

```bash
# Preview cleanup content (no actual cleanup)
python scripts/cleanup_cache.py --dry-run
```

```bash
# Execute standard cleanup
python scripts/cleanup_cache.py --clean
```

```bash
# Force cleanup (attempts to close related programs, solving Windows file occupation issues)
python scripts/cleanup_cache.py --force
```

```bash
# Or directly use uv command
uv cache clean
```

--------------------------------

### MCP Server Configuration (Desktop Application Mode)

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Configure the MCP server for desktop application mode on Windows, macOS, or Linux. This JSON block sets environment variables to enable the native window instead of a browser.

```json
// Desktop application mode (Windows / macOS / Linux with a display)
{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

--------------------------------

### Run Functional Tests

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Execute standard functional tests for the MCP tool. Use `make test-web` for continuous web UI testing or `make test-desktop-func` for desktop application functional testing.

```bash
make test-func
```

```bash
make test-web
```

```bash
make test-desktop-func
```

--------------------------------

### Advance WebFeedbackSession State

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Programmatically advance the session state using next_step(). The state transitions from WAITING to ACTIVE, and then to FEEDBACK_SUBMITTED upon receiving feedback.

```python
# Advance state
session.next_step()                     # WAITING → ACTIVE
session.next_step("Feedback received.") # ACTIVE → FEEDBACK_SUBMITTED
```

--------------------------------

### Test MCP Feedback Enhanced Desktop Application

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Command to test the native desktop application of mcp-feedback-enhanced. This feature is new in v2.5.0.

```bash
uvx mcp-feedback-enhanced@latest test --desktop
```

--------------------------------

### Simulate Programmatic Feedback Submission

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Simulate feedback submission, including text and image data, mirroring the behavior of the browser WebSocket. Supports image size limits and base64 encoding settings.

```python
# Programmatic feedback submission (mirrors what the browser WebSocket does)
async def simulate_submission():
    await session.submit_feedback(
        feedback="Looks great! Please add docstrings.",
        images=[],      # list of {"name": str, "data": base64_str, "size": int}
        settings={"image_size_limit": 1048576, "enable_base64_detail": False},
    )

asyncio.run(simulate_submission())
print(session.status)                   # SessionStatus.FEEDBACK_SUBMITTED
```

--------------------------------

### Test MCP Feedback Enhanced Web UI

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/README.md

Command to test the Web UI of mcp-feedback-enhanced. The test runs continuously.

```bash
uvx mcp-feedback-enhanced@latest test --web
```

--------------------------------

### Session State Advancement

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Illustrates how to advance the state of a WebFeedbackSession to the next step, optionally with a message.

```APIDOC
## Session State Advancement

### Description
Advances the feedback session to the next logical step in its lifecycle. This can be done without a message or with a specific message indicating the reason for advancement.

### Method
- **session.next_step(message: str = None)**: Advances the session state. If `message` is provided, it's associated with the state change.

### Code Example
```python
# Advance from WAITING to ACTIVE
session.next_step()

# Advance from ACTIVE to FEEDBACK_SUBMITTED with a message
session.next_step("Feedback received.")
```
```

--------------------------------

### Automated Cache Cleanup on Windows

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/docs/en/cache-management.md

Set up a Windows Scheduled Task to automate cache cleanup. This batch script navigates to the project directory and executes the cleanup script.

```batch
@echo off
cd /d "G:\github\interactive-feedback-mcp"
python scripts/cleanup_cache.py --clean
```

--------------------------------

### Clear UI Settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Delete the UI settings file. This action resets the UI configuration to its default state.

```bash
# POST /api/clear-settings — delete the settings file
curl -X POST http://127.0.0.1:8765/api/clear-settings
```

--------------------------------

### Manual Cleanup on Windows

Source: https://github.com/minidoracat/mcp-feedback-enhanced/blob/main/docs/en/cache-management.md

For manual cleanup on Windows, especially when encountering process occupation errors, you can use taskkill to terminate related processes before running `uv cache clean`.

```batch
# Windows
taskkill /f /im uvx.exe
taskkill /f /im python.exe /fi "WINDOWTITLE eq *mcp-feedback-enhanced*"

# Then execute cleanup
uv cache clean
```

--------------------------------

### Trigger Interactive Feedback with `interactive_feedback` Tool

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

This Python snippet demonstrates how an AI agent uses the `interactive_feedback` MCP tool to pause execution and collect user feedback, including text and images. It shows the client-side call and expected browser interaction.

```python
from fastmcp import FastMCP, Client
import asyncio

async def demo():
    async with Client("mcp-feedback-enhanced") as client:
        result = await client.call_tool(
            "interactive_feedback",
            {
                "project_directory": "/home/user/my-project",
                "summary": "## Task Complete\n\nI refactored `auth.py`:\n- Replaced MD5 with bcrypt\n- Added rate limiting\n\nPlease review and provide feedback.",
                "timeout": 600,
            }
        )
        # result is a list; first item is always TextContent
        text_feedback = result[0].text
        # Subsequent items may be MCPImage objects if the user attached images
        images = result[1:]
        print("User said:", text_feedback)

asyncio.run(demo())
# Expected: Web browser opens at http://127.0.0.1:8765
# User types feedback and (optionally) uploads images, then clicks Submit.
# text_feedback -> "=== 用戶回饋 ===\nLooks good, but please add unit tests."
```

--------------------------------

### Waiting for Feedback

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Explains how to use the `wait_for_feedback` method to block until feedback is submitted or a timeout occurs.

```APIDOC
## Wait for Feedback

### Description
Blocks the execution until feedback is submitted by the user or a specified timeout is reached.

### Method
- **session.wait_for_feedback(timeout: int)**: Waits for feedback submission.
  - **timeout** (int): The maximum time in seconds to wait.

### Return Value
Returns the result of the wait operation (details depend on implementation).

### Code Example
```python
async def wait():
    result = await session.wait_for_feedback(timeout=120)
    return result
```
```

--------------------------------

### Update Timeout Settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Shows how to configure user-controlled timeout settings for a session.

```APIDOC
## Update Timeout Settings

### Description
Configures the session's timeout behavior, allowing it to be enabled or disabled and setting a specific timeout duration in seconds.

### Method
- **session.update_timeout_settings(enabled: bool, timeout_seconds: int)**: Updates the timeout configuration.
  - **enabled** (bool): Whether the user-controlled timeout is enabled.
  - **timeout_seconds** (int): The duration of the timeout in seconds.

### Code Example
```python
session.update_timeout_settings(enabled=True, timeout_seconds=1800)
```
```

--------------------------------

### WebFeedbackSession Class Description

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Description of the WebFeedbackSession class, which represents a single AI-user interaction round-trip and manages its state machine.

```APIDOC
## `WebFeedbackSession` Class

Represents one AI→user interaction round-trip. Stores the AI summary, collects command logs and images, manages a `threading.Event` for synchronisation, and drives a one-way state machine: `WAITING → ACTIVE → FEEDBACK_SUBMITTED → COMPLETED` (with terminal states `ERROR`, `TIMEOUT`, `EXPIRED`).

```python
from mcp_feedback_enhanced.web.models.feedback_session import (
    WebFeedbackSession, SessionStatus, CleanupReason
)
import asyncio
```
```

--------------------------------

### POST /api/clear-settings

Source: https://context7.com/minidoracat/mcp-feedback-enhanced/llms.txt

Deletes the persisted user interface settings file.

```APIDOC
## POST /api/clear-settings

### Description
Removes the user interface settings file, effectively resetting UI preferences to their default values.

### Method
POST

### Endpoint
/api/clear-settings

### Request Example
```bash
curl -X POST http://127.0.0.1:8765/api/clear-settings
```
```