Merge pull request #401 from PlanExeOrg/feature/plan-feedback-tool

feat: implement plan_feedback MCP tool

Author: neoneye

database_api/model_feedback.py

@@ -0,0 +1,40 @@
+"""Feedback submitted by MCP clients about plan quality, workflow, or the interface."""
+import uuid
+from datetime import datetime, UTC
+from database_api.planexe_db_singleton import db
+
+
+class FeedbackItem(db.Model):
+    __tablename__ = "feedback_item"
+
+    # Server-generated UUID.
+    id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+
+    # When the feedback was received (UTC).
+    received_at = db.Column(db.DateTime, nullable=False, default=lambda: datetime.now(UTC), index=True)
+
+    # Feedback category (one of the 12 defined categories).
+    category = db.Column(db.String(32), nullable=False)
+
+    # Free-text feedback message.
+    message = db.Column(db.Text, nullable=False)
+
+    # Optional plan UUID this feedback is about.
+    plan_id = db.Column(db.String(36), nullable=True)
+
+    # Optional satisfaction score (1-5).
+    rating = db.Column(db.Integer, nullable=True)
+
+    # Optional severity for issue reports (low/medium/high).
+    severity = db.Column(db.String(8), nullable=True)
+
+    # User who submitted the feedback (resolved from auth context).
+    user_id = db.Column(db.String(36), nullable=True)
+
+    # Inline snapshot of the plan state at feedback time.
+    plan_progress_pct = db.Column(db.Float, nullable=True)
+    plan_state = db.Column(db.String(16), nullable=True)
+    plan_current_step = db.Column(db.String(128), nullable=True)
+
+    def __repr__(self):
+        return f"<FeedbackItem(id={self.id}, category='{self.category}', received_at='{self.received_at}')>"

docs/superpowers/specs/2026-03-28-plan-feedback-design.md

@@ -0,0 +1,128 @@
+# Design: `plan_feedback` MCP Tool
+
+**Date:** 2026-03-28
+**Proposal:** [127-mcp-feedback.md](../../proposals/127-mcp-feedback.md)
+
+## Summary
+
+Add a `plan_feedback` MCP tool that allows LLM consumers to submit structured feedback about the PlanExe MCP interface, plan quality, and workflow experiences. Feedback is stored in PostgreSQL for later analysis. The tool is non-blocking and fire-and-forget: it always returns success to the caller even if storage fails internally.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | enum | yes | One of: `sse_issue`, `status_staleness`, `queue_delay`, `file_visibility`, `plan_quality`, `tool_description`, `workflow`, `performance`, `error_handling`, `suggestion`, `compliment`, `other` |
+| `message` | string | yes | Free-text feedback (concise, actionable) |
+| `plan_id` | string\|null | no | UUID to attach feedback to a specific plan |
+| `rating` | integer 1-5\|null | no | Satisfaction score |
+| `severity` | enum\|null | no | `low`, `medium`, or `high` (for issue reports) |
+
+## Response
+
+### Success (always returned to caller)
+
+```json
+{
+  "feedback_id": "uuid",
+  "received_at": "2026-03-28T14:30:00Z",
+  "message": "Feedback received. Thank you."
+}
+```
+
+### Validation Errors
+
+```json
+{
+  "error": {
+    "code": "INVALID_FEEDBACK",
+    "message": "Human-readable validation error"
+  }
+}
+```
+
+```json
+{
+  "error": {
+    "code": "PLAN_NOT_FOUND",
+    "message": "Plan not found: <plan_id>"
+  }
+}
+```
+
+## Database Table: `feedback_item`
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | VARCHAR(36) | PK, UUID generated server-side |
+| `received_at` | TIMESTAMP | UTC, indexed, default now() |
+| `category` | VARCHAR(32) | One of 12 enum values |
+| `message` | TEXT | Free-text feedback |
+| `plan_id` | VARCHAR(36) | Nullable, references task_item(id) |
+| `rating` | INTEGER | Nullable, 1-5 |
+| `severity` | VARCHAR(8) | Nullable: low/medium/high |
+| `user_id` | VARCHAR(36) | Nullable, resolved from auth context |
+| `plan_progress_pct` | FLOAT | Nullable, snapshot at feedback time |
+| `plan_state` | VARCHAR(16) | Nullable, snapshot at feedback time |
+| `plan_current_step` | VARCHAR(128) | Nullable, snapshot at feedback time |
+
+No foreign key constraint on `plan_id` to keep writes simple and avoid blocking on plan table locks.
+
+## Files to Create/Modify
+
+### New File
+- `database_api/model_feedback.py` — SQLAlchemy model `FeedbackItem`
+
+### Modified Files
+- `mcp_cloud/tool_models.py` — Add `PlanFeedbackInput`, `PlanFeedbackOutput` Pydantic models
+- `mcp_cloud/schemas.py` — Add schema constants and `ToolDefinition` entry
+- `mcp_cloud/handlers.py` — Add `handle_plan_feedback()`, register in `TOOL_HANDLERS`
+- `mcp_cloud/db_setup.py` — Import model, add `PlanFeedbackRequest`, update `PLANEXE_SERVER_INSTRUCTIONS`
+- `mcp_cloud/db_queries.py` — Add `_create_feedback_sync()` and `_get_plan_snapshot_for_feedback_sync()`
+
+## Handler Logic
+
+1. Parse and validate input via `PlanFeedbackRequest` (Pydantic BaseModel)
+2. If `plan_id` provided:
+   - Look up plan via `_get_plan_snapshot_for_feedback_sync()`
+   - If not found, return `PLAN_NOT_FOUND` error (this is the only error visible to caller)
+   - If found, capture snapshot: `progress_percentage`, `state`, `current_step`
+3. Generate `feedback_id` (UUID4) and `received_at` (UTC now)
+4. Write to DB in try/except:
+   - On success: return `{feedback_id, received_at, message}`
+   - On failure: **log the error**, still return success response (fire-and-forget)
+5. Response is always `isError=False` except for `PLAN_NOT_FOUND` and `INVALID_FEEDBACK`
+
+## Tool Annotations
+
+```python
+annotations={
+    "readOnlyHint": False,   # writes to DB
+    "destructiveHint": False, # no destructive side effects
+    "idempotentHint": True,   # duplicate submissions are safe
+    "openWorldHint": False,   # no external calls
+}
+```
+
+## Server Instructions Update
+
+Add to `PLANEXE_SERVER_INSTRUCTIONS`:
+> "Use plan_feedback to report issues or share observations about plan quality, workflow friction, or the MCP interface. Feedback is fire-and-forget and never blocks the workflow."
+
+## Behavioral Guarantees
+
+- Non-blocking: handler returns in <1 second
+- Fire-and-forget: never gates workflow
+- No rate limiting on LLM consumers
+- Always returns success to caller (except validation/plan-not-found errors)
+- Internal storage failures are logged but not surfaced to caller
+
+## Testing
+
+Follow existing test patterns (e.g., `test_plan_create_tool.py`):
+- Valid feedback with all fields
+- Valid feedback with only required fields
+- Invalid category returns INVALID_FEEDBACK
+- Invalid plan_id returns PLAN_NOT_FOUND
+- Rating out of range returns INVALID_FEEDBACK
+- Invalid severity returns INVALID_FEEDBACK
+- DB write failure still returns success (fire-and-forget)

mcp_cloud/app.py

@@ -34,6 +34,7 @@
     PlanResumeRequest,
     PlanFileInfoRequest,
     PlanListRequest,
+    PlanFeedbackRequest,
     ModelProfilesRequest,
     PlanItem,
     PlanState,
@@ -63,6 +64,8 @@
     _resume_plan_sync,
     _get_plan_for_report_sync,
     _list_plans_sync,
+    _get_plan_snapshot_for_feedback_sync,
+    _create_feedback_sync,
     get_plan_state_mapping,
     _extract_plan_create_metadata_overrides,
     _merge_plan_create_config,
@@ -144,6 +147,8 @@
     EXAMPLE_PLANS_OUTPUT_SCHEMA,
     PLAN_LIST_INPUT_SCHEMA,
     PLAN_LIST_OUTPUT_SCHEMA,
+    PLAN_FEEDBACK_INPUT_SCHEMA,
+    PLAN_FEEDBACK_OUTPUT_SCHEMA,
     ToolDefinition,
     TOOL_DEFINITIONS,
 )
@@ -162,6 +167,7 @@
     handle_plan_resume,
     handle_plan_file_info,
     handle_plan_list,
+    handle_plan_feedback,
     TOOL_HANDLERS,
 )
 

mcp_cloud/db_queries.py

@@ -14,6 +14,7 @@
 
 from mcp_cloud.db_setup import app, db, PlanItem, PlanState, EventItem, EventType
 from database_api.model_credit_history import CreditHistory
+from database_api.model_feedback import FeedbackItem
 
 logger = logging.getLogger(__name__)
 
@@ -483,6 +484,67 @@ def _list_plans_sync(user_id: Optional[str], limit: int) -> list[dict[str, Any]]
         return results
 
 
+# ---------------------------------------------------------------------------
+# Feedback
+# ---------------------------------------------------------------------------
+
+def _get_plan_snapshot_for_feedback_sync(plan_id: str) -> Optional[dict[str, Any]]:
+    """Return a lightweight plan snapshot for embedding in feedback, or None if not found."""
+    with app.app_context():
+        try:
+            plan_uuid = uuid.UUID(plan_id)
+        except ValueError:
+            return None
+        row = (
+            db.session.query(
+                PlanItem.id,
+                PlanItem.state,
+                PlanItem.progress_percentage,
+                PlanItem.current_step,
+            )
+            .filter(PlanItem.id == plan_uuid)
+            .first()
+        )
+        if row is None:
+            return None
+        return {
+            "plan_id": str(row.id),
+            "state": get_plan_state_mapping(row.state),
+            "progress_percentage": float(row.progress_percentage or 0.0),
+            "current_step": row.current_step,
+        }
+
+
+def _create_feedback_sync(
+    feedback_id: str,
+    received_at: datetime,
+    category: str,
+    message: str,
+    plan_id: Optional[str],
+    rating: Optional[int],
+    severity: Optional[str],
+    user_id: Optional[str],
+    plan_snapshot: Optional[dict[str, Any]],
+) -> None:
+    """Persist a feedback entry to the database. Raises on failure."""
+    with app.app_context():
+        item = FeedbackItem(
+            id=feedback_id,
+            received_at=received_at,
+            category=category,
+            message=message,
+            plan_id=plan_id,
+            rating=rating,
+            severity=severity,
+            user_id=user_id,
+            plan_progress_pct=plan_snapshot["progress_percentage"] if plan_snapshot else None,
+            plan_state=plan_snapshot["state"] if plan_snapshot else None,
+            plan_current_step=plan_snapshot["current_step"] if plan_snapshot else None,
+        )
+        db.session.add(item)
+        db.session.commit()
+
+
 # ---------------------------------------------------------------------------
 # Utilities
 # ---------------------------------------------------------------------------

mcp_cloud/db_setup.py

@@ -38,6 +38,7 @@
 from database_api.model_user_api_key import UserApiKey
 from database_api.model_credit_history import CreditHistory  # noqa: F401
 from database_api.model_token_metrics import TokenMetrics  # noqa: F401
+from database_api.model_feedback import FeedbackItem  # noqa: F401
 
 print("[startup] db_setup.py: creating Flask app", file=sys.stderr, flush=True)
 app = Flask(__name__)
@@ -232,6 +233,8 @@ def ensure_last_progress_at_column() -> None:
     "In both cases, report the issue to PlanExe developers on GitHub: https://github.com/PlanExeOrg/PlanExe/issues . "
     "Main output: a self-contained interactive HTML report (~700KB) with collapsible sections and interactive Gantt charts — open in a browser. "
     "The zip contains the intermediary pipeline files (md, json, csv) that fed the report. "
+    "Use plan_feedback to report issues or share observations about plan quality, workflow friction, or the MCP interface. "
+    "Feedback is fire-and-forget and never blocks the workflow. "
     "New users: create an account and obtain an API key at https://home.planexe.org/ ."
 )
 
@@ -298,3 +301,10 @@ class PlanListRequest(BaseModel):
 class ModelProfilesRequest(BaseModel):
     """No input parameters."""
     pass
+
+class PlanFeedbackRequest(BaseModel):
+    category: str
+    message: str
+    plan_id: Optional[str] = None
+    rating: Optional[int] = None
+    severity: Optional[str] = None