mcp-keep-feedback 0.1.2__tar.gz

mcp_keep_feedback-0.1.2/.bumpversion.cfg

@@ -0,0 +1,15 @@
+[bumpversion]
+current_version = 2.6.0
+commit = False
+tag = False
+allow_dirty = True
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
+serialize = {major}.{minor}.{patch}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file:src/mcp_feedback_enhanced/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"

mcp_keep_feedback-0.1.2/.env.example

@@ -0,0 +1,3 @@
+# PyPI API Token
+# 获取方式: https://pypi.org/manage/account/token/
+PYPI_TOKEN=pypi-xxx

mcp_keep_feedback-0.1.2/.gitignore

@@ -0,0 +1,91 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Development tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv*/
+venv*/
+
+
+
+# Logs
+*.log
+
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+*~
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Others
+.cursor/rules/
+uv.lock
+.mcp_feedback_settings.json
+test_reports/
+
+# Temporary test files
+test_*.py
+
+# User configuration files
+ui_settings.json
+.config/
+
+# Backup files
+*.bak
+*.backup
+*.orig
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Rust/Tauri build artifacts
+src-tauri/target/
+src-tauri/Cargo.lock
+src-tauri/WixTools/
+src-tauri/gen/
+
+
+
+
+# Tauri bundle outputs
+src-tauri/target/bundle/
+src-tauri/target/release/bundle/
+
+# Node.js (if using Tauri with frontend framework)
+node_modules/
+package-lock.json
+yarn.lock
+
+# Temporary build files
+*.tmp
+*.temp
+
+.sisyphus
+src/mcp_keep_feedback/desktop_release

mcp_keep_feedback-0.1.2/.python-version

@@ -0,0 +1 @@
+3.11

mcp_keep_feedback-0.1.2/AGENTS.md

@@ -0,0 +1,305 @@
+# AGENTS.md - AI Agent Development Guide
+
+> This file provides essential information for AI coding agents working in this repository.
+
+## Project Overview
+
+**mcp-keep-feedback** is an MCP (Model Context Protocol) server for interactive user feedback in AI-assisted development. It provides a dual-interface architecture (Web UI and Desktop Application) with intelligent environment detection.
+
+- **Language**: Python 3.11+
+- **Package Manager**: uv
+- **Build Backend**: Hatchling with Maturin (for Rust extensions)
+- **Framework**: FastMCP, FastAPI, Tauri (desktop)
+
+---
+
+## Code Style Guidelines
+
+### Python Version
+- Target: Python 3.11+
+- Use modern type syntax: `list[str]`, `dict[str, Any]`, `str | None` (not `Optional[str]`)
+
+### Imports
+Imports are managed by ruff/isort with these rules:
+- `known-first-party = ["mcp_keep_feedback"]`
+- `lines-after-imports = 2`
+- Order: standard library → third-party → local imports
+
+```python
+# Standard library
+import asyncio
+import os
+from pathlib import Path
+from typing import Any
+
+# Third-party
+from fastapi import WebSocket
+from pydantic import Field
+
+# Local imports
+from .debug import debug_log
+from .utils.error_handler import ErrorHandler, ErrorType
+```
+
+### Formatting (Ruff)
+- Line length: 88 characters
+- Indent: 4 spaces
+- Quotes: double quotes (`"`)
+- Line ending: auto
+
+### Type Annotations
+Always use type annotations for function parameters and return types:
+
+```python
+def process_images(self, images: list[dict]) -> list[dict]:
+    """Process image data with type safety."""
+    ...
+
+async def submit_feedback(
+    self,
+    feedback: str,
+    images: list[dict[str, Any]],
+    settings: dict[str, Any] | None = None,
+) -> None:
+    """Submit feedback and images."""
+    ...
+```
+
+### Naming Conventions
+- **Classes**: PascalCase (`WebFeedbackSession`, `ErrorHandler`)
+- **Functions/Methods**: snake_case (`process_images`, `get_error_solutions`)
+- **Constants**: UPPER_SNAKE_CASE (`MAX_IMAGE_SIZE`, `SUPPORTED_IMAGE_TYPES`)
+- **Private methods**: prefix with underscore (`_process_images`, `_safe_close_websocket`)
+- **Module-level private**: prefix with underscore (`_encoding_initialized`)
+
+### Docstrings
+Use Chinese (Traditional) for docstrings in this project:
+
+```python
+def classify_error(error: Exception) -> ErrorType:
+    """
+    根據異常類型自動分類錯誤
+
+    Args:
+        error: Python 異常對象
+
+    Returns:
+        ErrorType: 錯誤類型
+    """
+    ...
+```
+
+---
+
+## Error Handling
+
+### Use the ErrorHandler Framework
+Do not use bare `except` or print errors directly. Use the unified `ErrorHandler`:
+
+```python
+from .utils.error_handler import ErrorHandler, ErrorType
+
+try:
+    # ... operation
+    pass
+except Exception as e:
+    error_id = ErrorHandler.log_error_with_context(
+        e,
+        context={"operation": "描述操作", "file_path": path},
+        error_type=ErrorType.FILE_IO,
+    )
+    user_message = ErrorHandler.format_user_error(e, include_technical=False)
+```
+
+### Error Types Available
+- `NETWORK` - Network-related errors
+- `FILE_IO` - File I/O errors
+- `PROCESS` - Process-related errors
+- `TIMEOUT` - Timeout errors
+- `USER_CANCEL` - User cancelled operation
+- `SYSTEM` - System errors
+- `PERMISSION` - Permission errors
+- `VALIDATION` - Data validation errors
+- `DEPENDENCY` - Dependency errors
+- `CONFIGURATION` - Configuration errors
+
+---
+
+## Async Patterns
+
+### Use async/await properly
+```python
+# Correct: async context manager for WebSocket
+async with self.websocket:
+    await self.websocket.send_json({"type": "message"})
+
+# Correct: async task creation
+asyncio.create_task(read_output())
+
+# Correct: run blocking code in executor
+await asyncio.get_event_loop().run_in_executor(None, blocking_function)
+```
+
+---
+
+## Internationalization (i18n)
+
+The project supports three languages:
+- `zh-TW` - Traditional Chinese (default)
+- `zh-CN` - Simplified Chinese
+- `en` - English
+
+Use the i18n manager for user-facing messages:
+
+```python
+from .i18n import get_i18n_manager
+
+i18n = get_i18n_manager()
+message = i18n.t("key.path.to.message")
+```
+
+---
+
+## MCP Tool Definition Pattern
+
+Use FastMCP decorators with Pydantic Field for parameter descriptions:
+
+```python
+from fastmcp import FastMCP
+from pydantic import Field
+from typing import Annotated
+
+mcp = FastMCP("Server Name")
+
+@mcp.tool()
+async def interactive_feedback(
+    project_directory: Annotated[str, Field(description="項目目錄路徑")],
+    full_report_and_output: Annotated[str, Field(description="完整報告內容")],
+) -> list:
+    """Tool description here."""
+    ...
+```
+
+---
+
+## Pre-commit Hooks
+
+Pre-commit hooks run automatically on commit. Key hooks:
+- `trailing-whitespace` - Remove trailing whitespace
+- `end-of-file-fixer` - Ensure files end with newline
+- `check-yaml` / `check-toml` / `check-json` - Validate config files
+- `ruff` - Linting with auto-fix
+- `ruff-format` - Code formatting
+
+Manual commands:
+```bash
+uv run pre-commit run           # Run on staged files
+uv run pre-commit run --all-files  # Run on all files
+```
+
+---
+
+## Key Directories
+
+```
+src/mcp_keep_feedback/
+├── __init__.py           # Package exports
+├── __main__.py           # CLI entry point
+├── server.py             # MCP server and tools
+├── debug.py              # Debug logging utilities
+├── i18n.py               # Internationalization
+├── web/                  # Web UI module
+│   ├── main.py           # WebUIManager
+│   ├── routes/           # FastAPI routes
+│   ├── models/           # Data models
+│   ├── utils/            # Web utilities
+│   └── constants/        # Message codes
+├── utils/                # Shared utilities
+│   ├── error_handler.py  # Error handling framework
+│   └── resource_manager.py # Resource cleanup
+└── desktop_app/          # Tauri desktop integration
+
+tests/
+├── conftest.py           # Pytest fixtures
+├── unit/                 # Unit tests
+├── integration/          # Integration tests
+├── fixtures/             # Test data
+└── helpers/              # Test utilities
+```
+
+---
+
+## Ruff Linting Rules
+
+Key enabled rules:
+- `E`, `W` - pycodestyle errors/warnings
+- `F` - Pyflakes
+- `I` - isort
+- `B` - flake8-bugbear
+- `UP` - pyupgrade
+- `S` - bandit (security)
+- `PL` - Pylint
+- `RUF` - Ruff-specific
+
+Key ignored rules (see pyproject.toml for full list):
+- `E501` - Line length (handled by formatter)
+- `S101` - Allow assert in tests
+- `T201` - Allow print for debugging
+- `RUF001-003` - Allow Chinese characters
+
+---
+
+## Important Notes
+
+1. **Never suppress type errors** with `# type: ignore` or `as any` without justification
+2. **Never use bare `except:`** - always specify exception types
+3. **Always clean up resources** - use the resource manager for processes, files, etc.
+4. **JSON RPC safety** - Error handling must not affect stdout (used for MCP communication)
+5. **WebSocket lifecycle** - Use `_safe_close_websocket()` for proper cleanup
+6. **Subprocess security** - Use `shlex.split()` and `shell=False` for command execution
+
+---
+
+## Publishing
+
+```bash
+# 发布到 PyPI
+make publish
+
+# 发布到 TestPyPI
+make publish-test
+```
+
+环境变量：在 `.env` 文件中设置 `PYPI_TOKEN=pypi-xxx`
+
+---
+
+## Tunable Prompts (可调优提示词)
+
+项目中包含四个核心提示词，用于控制 AI 行为协议。修改时需注意保持一致性。
+
+### 1. prompt-engineering.md (提示工程文档)
+
+- **位置**: `docs/prompt-engineering.md`
+- **用途**: 用户参考文档，包含完整的 MCP 模式规则和示例
+- **核心内容**: 绝对视觉隔离、强制闭环调用、无限循环、超时重试等规则
+
+### 2. AUTO_REPLY_MESSAGE (自动回复消息)
+
+- **位置**: `src/mcp_keep_feedback/web/models/feedback_session.py` (约第 69-80 行)
+- **用途**: 当用户在 `MCP_AUTO_REPLY_TIMEOUT` 设定时间内未响应时，系统自动发送此消息
+- **核心内容**: 引导 AI 继续调用 `mcp-keep-feedback` 工具，不放弃、不派发子代理
+
+### 3. append_message (强制提醒协议)
+
+- **位置**: 
+  - `src/mcp_keep_feedback/web/models/feedback_session.py` (约第 441-465 行)
+  - `src/mcp_keep_feedback/web/main.py` (约第 500-524 行) - 重复定义，需同步修改
+- **用途**: 每次用户提交反馈后，自动附加此协议提醒到反馈内容末尾
+- **核心内容**: 强制闭环调用、无限循环、超时重试、禁止子代理派发等规则
+
+### 修改注意事项
+
+1. **两处 `append_message` 必须同步修改** - `feedback_session.py` 和 `main.py` 中的定义需保持一致
+2. **协议逻辑关联** - 四个 prompt 共同构成完整的闭环协议，修改一处需考虑其他三处的语义一致性
+3. **关键词保持** - `[MUST]`、`[STRICTLY FORBIDDEN]`、`[NEVER]` 等强调词对 AI 行为有显著影响

mcp_keep_feedback-0.1.2/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2024 Fábio Ferreira
+
+Portions of this software are modifications and enhancements
+Copyright (c) 2024 Minidoracat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_keep_feedback-0.1.2/Makefile

@@ -0,0 +1,205 @@
+# Makefile for mcp-keep-feedback development
+# 適用於 mcp-keep-feedback 專案開發
+# Compatible with Windows PowerShell and Unix systems
+# 兼容 Windows PowerShell 和 Unix 系統
+
+.PHONY: help install install-dev install-hooks lint format type-check test clean pre-commit-run pre-commit-all update-deps check-rust build-desktop build-desktop-release test-desktop clean-desktop build-all test-all test-func test-web test-desktop-func publish publish-test
+
+# 預設目標 - 顯示幫助訊息
+help: ## Show this help message
+	@echo "Available commands:"
+	@echo ""
+	@echo "  dev-setup            Complete development setup"
+	@echo "  install              Install the package"
+	@echo "  install-dev          Install development dependencies"
+	@echo "  install-hooks        Install pre-commit hooks"
+	@echo "  lint                 Run linting with Ruff"
+	@echo "  lint-fix             Run linting with auto-fix"
+	@echo "  format               Format code with Ruff"
+	@echo "  format-check         Check code formatting"
+	@echo "  type-check           Run type checking with mypy"
+	@echo "  check                Run all code quality checks"
+	@echo "  check-fix            Run all checks with auto-fix"
+	@echo "  pre-commit-run       Run pre-commit on staged files"
+	@echo "  pre-commit-all       Run pre-commit on all files"
+	@echo "  pre-commit-update    Update pre-commit hooks"
+	@echo "  test                 Run tests"
+	@echo "  test-cov             Run tests with coverage"
+	@echo "  test-fast            Run tests without slow tests"
+	@echo "  test-func            Run functional tests (standard)"
+	@echo "  test-web             Run Web UI tests (continuous)"
+	@echo "  test-desktop-func    Run desktop application functional tests"
+	@echo "  clean                Clean up cache and temporary files"
+	@echo "  ps-clean             PowerShell version of clean (Windows)"
+	@echo "  update-deps          Update dependencies"
+	@echo "  build                Build the package"
+	@echo "  build-check          Check the built package"
+	@echo "  bump-patch           Bump patch version"
+	@echo "  bump-minor           Bump minor version"
+	@echo "  bump-major           Bump major version"
+	@echo "  publish              Publish to PyPI"
+	@echo "  publish-test         Publish to TestPyPI"
+	@echo "  ci                   Simulate CI pipeline locally"
+	@echo "  quick-check          Quick check with auto-fix"
+	@echo ""
+	@echo "Desktop Application Commands:"
+	@echo "  build-desktop        Build desktop application (debug)"
+	@echo "  build-desktop-release Build desktop application (release)"
+	@echo "  test-desktop         Test desktop application"
+	@echo "  clean-desktop        Clean desktop build artifacts"
+	@echo "  check-rust           Check Rust development environment"
+
+# 安裝相關命令
+install: ## Install the package
+	uv sync
+
+install-dev: ## Install development dependencies
+	uv sync --dev
+
+install-hooks: ## Install pre-commit hooks
+	uv run pre-commit install
+	@echo "✅ Pre-commit hooks installed successfully!"
+
+# 程式碼品質檢查命令
+lint: ## Run linting with Ruff
+	uv run ruff check .
+
+lint-fix: ## Run linting with auto-fix
+	uv run ruff check . --fix
+
+format: ## Format code with Ruff
+	uv run ruff format .
+
+format-check: ## Check code formatting
+	uv run ruff format . --check
+
+type-check: ## Run type checking with mypy
+	uv run mypy
+
+# 組合品質檢查命令
+check: lint format-check type-check ## Run all code quality checks
+
+check-fix: lint-fix format type-check ## Run all checks with auto-fix
+
+# Pre-commit 相關命令
+pre-commit-run: ## Run pre-commit on staged files
+	uv run pre-commit run
+
+pre-commit-all: ## Run pre-commit on all files
+	uv run pre-commit run --all-files
+
+pre-commit-update: ## Update pre-commit hooks
+	uv run pre-commit autoupdate
+
+# 測試相關命令
+test: ## Run tests
+	uv run pytest
+
+test-cov: ## Run tests with coverage
+	uv run pytest --cov=src/mcp_keep_feedback --cov-report=html --cov-report=term
+
+test-fast: ## Run tests without slow tests
+	uv run pytest -m "not slow"
+
+# 功能測試命令
+test-func: ## Run functional tests (standard)
+	uv run python -m mcp_keep_feedback test
+
+test-web: ## Run Web UI tests (continuous)
+	uvx --no-cache --with-editable . mcp-keep-feedback test --web
+
+test-desktop-func: ## Run desktop application functional tests
+	uvx --no-cache --with-editable . mcp-keep-feedback test --desktop
+
+# 維護相關命令
+clean: ## Clean up cache and temporary files
+	@echo "Cleaning up..."
+	@if exist ".mypy_cache" rmdir /s /q ".mypy_cache" 2>nul || true
+	@if exist ".ruff_cache" rmdir /s /q ".ruff_cache" 2>nul || true
+	@if exist ".pytest_cache" rmdir /s /q ".pytest_cache" 2>nul || true
+	@if exist "htmlcov" rmdir /s /q "htmlcov" 2>nul || true
+	@if exist "dist" rmdir /s /q "dist" 2>nul || true
+	@if exist "build" rmdir /s /q "build" 2>nul || true
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -name "*.pyc" -delete 2>/dev/null || true
+	@find . -name "*.pyo" -delete 2>/dev/null || true
+	@find . -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	@echo "✅ Cleanup completed!"
+
+update-deps: ## Update dependencies
+	uv sync --upgrade
+
+# 建置相關命令
+build: ## Build the package
+	uv build
+
+build-check: ## Check the built package
+	uv run twine check dist/*
+
+# 版本發布命令
+bump-patch: ## Bump patch version
+	uv run bump2version patch
+
+bump-minor: ## Bump minor version
+	uv run bump2version minor
+
+bump-major: ## Bump major version
+	uv run bump2version major
+
+# PyPI 发布命令
+publish: ## Publish to PyPI
+	@./scripts/publish.sh
+
+publish-test: ## Publish to TestPyPI
+	@./scripts/publish.sh --test
+
+# 開發工作流程
+dev-setup: install-dev install-hooks ## Complete development setup
+	@echo "🎉 Development environment setup complete!"
+	@echo ""
+	@echo "Next steps:"
+	@echo "  1. Run 'make check' to verify everything works"
+	@echo "  2. Start coding! Pre-commit hooks will run automatically"
+	@echo "  3. Use 'make help' to see all available commands"
+
+# CI 流程模擬
+ci: clean install-dev pre-commit-all test ## Simulate CI pipeline locally
+
+# 快速開發命令
+quick-check: lint-fix format type-check ## Quick check with auto-fix (recommended for development)
+
+# Windows PowerShell 專用命令
+ps-clean: ## PowerShell version of clean (Windows)
+	powershell -Command "Get-ChildItem -Path . -Recurse -Name '__pycache__' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue; Get-ChildItem -Path . -Recurse -Name '*.pyc' | Remove-Item -Force -ErrorAction SilentlyContinue; @('.mypy_cache', '.ruff_cache', '.pytest_cache', 'htmlcov', 'dist', 'build') | ForEach-Object { if (Test-Path $$_) { Remove-Item $$_ -Recurse -Force } }"
+
+# 桌面應用程式相關命令
+check-rust: ## Check Rust development environment
+	@echo "🔍 Checking Rust environment..."
+	@rustc --version || (echo "❌ Rust not installed. Please visit https://rustup.rs/" && exit 1)
+	@cargo --version || (echo "❌ Cargo not installed" && exit 1)
+	@cargo install --list | grep tauri-cli || (echo "⚠️ Tauri CLI not installed, installing..." && cargo install tauri-cli)
+	@echo "✅ Rust environment check completed"
+
+build-desktop: ## Build desktop application (debug mode)
+	@echo "🔨 Building desktop application (debug)..."
+	uv run python scripts/build_desktop.py
+
+build-desktop-release: ## Build desktop application (release mode)
+	@echo "🚀 Building desktop application (release)..."
+	uv run python scripts/build_desktop.py --release
+
+test-desktop: build-desktop ## Test desktop application
+	@echo "🖥️ Testing desktop application..."
+	uv run python -m mcp_keep_feedback test --desktop
+
+clean-desktop: ## Clean desktop build artifacts
+	@echo "🧹 Cleaning desktop build artifacts..."
+	uv run python scripts/build_desktop.py --clean
+
+# 完整構建流程（包含桌面應用程式）
+build-all: clean build-desktop-release build ## Build complete package with desktop app
+	@echo "🎉 Complete build finished!"
+
+# 測試所有功能
+test-all: test test-func test-desktop ## Run all tests including desktop and functional tests
+	@echo "✅ All tests completed!"