ui-ticket-mcp 0.1.0__tar.gz

ui_ticket_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: ui-ticket-mcp
+Version: 0.1.0
+Summary: Review system MCP server for UI prototypes. Humans write comments in browser, AI agents resolve them via MCP.
+Author: 0ics-srls
+License: MIT
+Project-URL: Homepage, https://github.com/0ics-srls/ui-ticket-mcp
+Project-URL: Repository, https://github.com/0ics-srls/ui-ticket-mcp
+Project-URL: Issues, https://github.com/0ics-srls/ui-ticket-mcp/issues
+Keywords: mcp,review,ui,prototype,ai-agent,fastapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: aiosqlite>=0.20.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+
+# ui-ticket-mcp
+
+Review system for UI prototypes. Humans write comments in the browser, AI agents resolve them via MCP.
+
+## Install
+
+```bash
+pip install ui-ticket-mcp
+```
+
+## MCP Server (for AI agents)
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "review-system": {
+      "command": "python",
+      "args": ["-m", "review_mcp.mcp_server"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Reviews are stored in `{PROJECT_ROOT}/.reviews/reviews.db` (auto-created, committable to git).
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_review_summary()` | Summary of pages with open/resolved counts |
+| `get_reviews(page_id?)` | List comments, optionally filtered by page |
+| `add_review(page_id, author, text)` | Add a new comment |
+| `resolve_review(review_id, resolved_by?)` | Mark as resolved |
+| `reopen_review(review_id)` | Reopen a resolved review |
+| `batch_resolve(page_id, resolved_by?)` | Resolve all open on a page |
+| `get_pending_work()` | Open reviews grouped by page (todo list) |
+| `find_source_file_tool(page_id)` | Find source files matching a page_id |
+
+## REST API (for browser UI)
+
+```bash
+PROJECT_ROOT=/path/to/your/project python -m review_mcp.api
+# → http://localhost:3200
+```
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/reviews/summary` | Per-page summary |
+| GET | `/api/reviews` | All reviews |
+| GET | `/api/reviews/{page_id}` | Reviews for a page |
+| POST | `/api/reviews/{page_id}` | Add review |
+| PATCH | `/api/review/{id}` | Update status/text |
+| DELETE | `/api/review/{id}` | Delete review |
+
+## More
+
+Full documentation: [github.com/0ics-srls/ui-ticket-mcp](https://github.com/0ics-srls/ui-ticket-mcp)

ui_ticket_mcp-0.1.0/README.md

@@ -0,0 +1,62 @@
+# ui-ticket-mcp
+
+Review system for UI prototypes. Humans write comments in the browser, AI agents resolve them via MCP.
+
+## Install
+
+```bash
+pip install ui-ticket-mcp
+```
+
+## MCP Server (for AI agents)
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "review-system": {
+      "command": "python",
+      "args": ["-m", "review_mcp.mcp_server"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Reviews are stored in `{PROJECT_ROOT}/.reviews/reviews.db` (auto-created, committable to git).
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_review_summary()` | Summary of pages with open/resolved counts |
+| `get_reviews(page_id?)` | List comments, optionally filtered by page |
+| `add_review(page_id, author, text)` | Add a new comment |
+| `resolve_review(review_id, resolved_by?)` | Mark as resolved |
+| `reopen_review(review_id)` | Reopen a resolved review |
+| `batch_resolve(page_id, resolved_by?)` | Resolve all open on a page |
+| `get_pending_work()` | Open reviews grouped by page (todo list) |
+| `find_source_file_tool(page_id)` | Find source files matching a page_id |
+
+## REST API (for browser UI)
+
+```bash
+PROJECT_ROOT=/path/to/your/project python -m review_mcp.api
+# → http://localhost:3200
+```
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/reviews/summary` | Per-page summary |
+| GET | `/api/reviews` | All reviews |
+| GET | `/api/reviews/{page_id}` | Reviews for a page |
+| POST | `/api/reviews/{page_id}` | Add review |
+| PATCH | `/api/review/{id}` | Update status/text |
+| DELETE | `/api/review/{id}` | Delete review |
+
+## More
+
+Full documentation: [github.com/0ics-srls/ui-ticket-mcp](https://github.com/0ics-srls/ui-ticket-mcp)

ui_ticket_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ui-ticket-mcp"
+version = "0.1.0"
+description = "Review system MCP server for UI prototypes. Humans write comments in browser, AI agents resolve them via MCP."
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "0ics-srls"}
+]
+readme = "README.md"
+keywords = ["mcp", "review", "ui", "prototype", "ai-agent", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "aiosqlite>=0.20.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/0ics-srls/ui-ticket-mcp"
+Repository = "https://github.com/0ics-srls/ui-ticket-mcp"
+Issues = "https://github.com/0ics-srls/ui-ticket-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "httpx",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.setuptools.packages.find]
+include = ["review_mcp*"]

ui_ticket_mcp-0.1.0/review_mcp/__init__.py

@@ -0,0 +1 @@
+"""Review system – MCP server + FastAPI REST API."""

ui_ticket_mcp-0.1.0/review_mcp/api.py

@@ -0,0 +1,105 @@
+"""FastAPI REST API for the review system (serves the Angular UI)."""
+
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from . import db
+
+REVIEW_PORT = int(os.environ.get("REVIEW_PORT", "3200"))
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    await db.init_db()
+    yield
+
+
+app = FastAPI(title="Review System API", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# --------------- Models ---------------
+
+
+class ReviewCreate(BaseModel):
+    author: str = "anonymous"
+    text: str
+
+
+class ReviewUpdate(BaseModel):
+    status: Optional[str] = None
+    text: Optional[str] = None
+    resolved_by: Optional[str] = None
+
+
+# --------------- Endpoints ---------------
+
+
+@app.get("/api/reviews/summary")
+async def summary():
+    return await db.get_summary()
+
+
+@app.get("/api/reviews")
+async def all_reviews():
+    return await db.get_reviews()
+
+
+@app.get("/api/reviews/{page_id:path}")
+async def page_reviews(page_id: str):
+    return await db.get_reviews(page_id)
+
+
+@app.post("/api/reviews/{page_id:path}", status_code=201)
+async def create_review(page_id: str, body: ReviewCreate):
+    return await db.insert_review(page_id, body.author, body.text)
+
+
+@app.patch("/api/review/{review_id}")
+async def patch_review(review_id: int, body: ReviewUpdate):
+    fields: dict = {}
+    if body.status is not None:
+        fields["status"] = body.status
+        if body.status == "resolved":
+            from datetime import datetime, timezone
+            fields["resolved_at"] = datetime.now(timezone.utc).isoformat()
+            fields["resolved_by"] = body.resolved_by or "user"
+        elif body.status == "open":
+            fields["resolved_at"] = None
+            fields["resolved_by"] = None
+    if body.text is not None:
+        fields["text"] = body.text
+
+    result = await db.update_review(review_id, **fields)
+    if result is None:
+        raise HTTPException(404, "Review not found")
+    return result
+
+
+@app.delete("/api/review/{review_id}")
+async def remove_review(review_id: int):
+    ok = await db.delete_review(review_id)
+    if not ok:
+        raise HTTPException(404, "Review not found")
+    return {"deleted": True}
+
+
+# --------------- Main ---------------
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=REVIEW_PORT)

ui_ticket_mcp-0.1.0/review_mcp/db.py

@@ -0,0 +1,206 @@
+"""SQLite database layer for review system (WAL mode, async)."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiosqlite
+
+REVIEWS_DIR = ".reviews"
+
+
+def _resolve_db_path() -> str:
+    """Resolve DB path: REVIEW_DB_PATH env > PROJECT_ROOT/.reviews/reviews.db > ./reviews.db"""
+    explicit = os.environ.get("REVIEW_DB_PATH")
+    if explicit:
+        return explicit
+
+    project_root = os.environ.get("PROJECT_ROOT")
+    if project_root:
+        return str(Path(project_root) / REVIEWS_DIR / "reviews.db")
+
+    return "./reviews.db"
+
+
+DB_PATH = _resolve_db_path()
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS reviews (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    page_id     TEXT    NOT NULL,
+    author      TEXT    NOT NULL DEFAULT 'anonymous',
+    text        TEXT    NOT NULL,
+    status      TEXT    NOT NULL DEFAULT 'open',
+    created_at  TEXT    NOT NULL,
+    resolved_at TEXT,
+    resolved_by TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_reviews_page_id ON reviews(page_id);
+CREATE INDEX IF NOT EXISTS idx_reviews_status  ON reviews(status);
+"""
+
+
+async def get_db() -> aiosqlite.Connection:
+    db = await aiosqlite.connect(DB_PATH)
+    await db.execute("PRAGMA journal_mode=WAL")
+    await db.execute("PRAGMA busy_timeout=5000")
+    db.row_factory = aiosqlite.Row
+    return db
+
+
+async def init_db() -> None:
+    _ensure_reviews_dir()
+    db = await get_db()
+    try:
+        await db.executescript(SCHEMA)
+        await db.commit()
+    finally:
+        await db.close()
+
+
+def _ensure_reviews_dir() -> None:
+    """Create .reviews/ directory with .gitkeep if it lives inside a PROJECT_ROOT."""
+    db_dir = Path(DB_PATH).parent
+    if db_dir.name != REVIEWS_DIR:
+        return
+
+    db_dir.mkdir(parents=True, exist_ok=True)
+
+    # .gitkeep so the directory is tracked in git
+    gitkeep = db_dir / ".gitkeep"
+    if not gitkeep.exists():
+        gitkeep.write_text("")
+
+    # .gitignore to track the DB but ignore WAL/SHM temp files
+    gitignore = db_dir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*.db-wal\n*.db-shm\n")
+
+
+# --------------- Queries ---------------
+
+
+async def get_summary() -> list[dict]:
+    """Return per-page summary with open/resolved counts."""
+    db = await get_db()
+    try:
+        sql = """
+            SELECT page_id,
+                   SUM(CASE WHEN status = 'open' THEN 1 ELSE 0 END) AS open,
+                   SUM(CASE WHEN status = 'resolved' THEN 1 ELSE 0 END) AS resolved,
+                   COUNT(*) AS total
+            FROM reviews
+            GROUP BY page_id
+            ORDER BY page_id
+        """
+        rows = await db.execute_fetchall(sql)
+        return [dict(r) for r in rows]
+    finally:
+        await db.close()
+
+
+async def get_reviews(page_id: str | None = None) -> list[dict]:
+    """Return reviews, optionally filtered by page_id."""
+    db = await get_db()
+    try:
+        if page_id:
+            rows = await db.execute_fetchall(
+                "SELECT * FROM reviews WHERE page_id = ? ORDER BY created_at DESC",
+                (page_id,),
+            )
+        else:
+            rows = await db.execute_fetchall(
+                "SELECT * FROM reviews ORDER BY created_at DESC"
+            )
+        return [dict(r) for r in rows]
+    finally:
+        await db.close()
+
+
+async def insert_review(page_id: str, author: str, text: str) -> dict:
+    """Insert a new review comment and return it."""
+    db = await get_db()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        cursor = await db.execute(
+            "INSERT INTO reviews (page_id, author, text, created_at) VALUES (?, ?, ?, ?)",
+            (page_id, author, text, now),
+        )
+        await db.commit()
+        row = await db.execute_fetchall(
+            "SELECT * FROM reviews WHERE id = ?", (cursor.lastrowid,)
+        )
+        return dict(row[0])
+    finally:
+        await db.close()
+
+
+async def update_review(review_id: int, **fields) -> dict | None:
+    """Update review fields (status, text, resolved_at, resolved_by)."""
+    db = await get_db()
+    try:
+        allowed = {"status", "text", "resolved_at", "resolved_by"}
+        updates = {k: v for k, v in fields.items() if k in allowed}
+        if not updates:
+            return None
+
+        set_clause = ", ".join(f"{k} = ?" for k in updates)
+        values = list(updates.values()) + [review_id]
+
+        await db.execute(
+            f"UPDATE reviews SET {set_clause} WHERE id = ?", values
+        )
+        await db.commit()
+
+        row = await db.execute_fetchall(
+            "SELECT * FROM reviews WHERE id = ?", (review_id,)
+        )
+        return dict(row[0]) if row else None
+    finally:
+        await db.close()
+
+
+async def delete_review(review_id: int) -> bool:
+    """Delete a review. Returns True if deleted."""
+    db = await get_db()
+    try:
+        cursor = await db.execute("DELETE FROM reviews WHERE id = ?", (review_id,))
+        await db.commit()
+        return cursor.rowcount > 0
+    finally:
+        await db.close()
+
+
+async def get_open_reviews_by_page() -> list[dict]:
+    """Return open reviews grouped by page_id (for pending work)."""
+    db = await get_db()
+    try:
+        rows = await db.execute_fetchall(
+            "SELECT * FROM reviews WHERE status = 'open' ORDER BY page_id, created_at"
+        )
+        pages: dict[str, list[dict]] = {}
+        for r in rows:
+            d = dict(r)
+            pages.setdefault(d["page_id"], []).append(d)
+        return [{"page_id": pid, "reviews": revs} for pid, revs in pages.items()]
+    finally:
+        await db.close()
+
+
+async def batch_resolve(page_id: str, resolved_by: str = "agent") -> int:
+    """Resolve all open reviews on a page. Returns count resolved."""
+    db = await get_db()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        cursor = await db.execute(
+            "UPDATE reviews SET status = 'resolved', resolved_at = ?, resolved_by = ? "
+            "WHERE page_id = ? AND status = 'open'",
+            (now, resolved_by, page_id),
+        )
+        await db.commit()
+        return cursor.rowcount
+    finally:
+        await db.close()

ui_ticket_mcp-0.1.0/review_mcp/file_finder.py

@@ -0,0 +1,72 @@
+"""Find source files matching a page_id within a project root."""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+
+
+def _to_segments(page_id: str) -> list[str]:
+    """Split page_id into meaningful segments (by '-', '_', '/')."""
+    return [s for s in re.split(r"[-_/]", page_id) if s]
+
+
+def _to_camel(segments: list[str]) -> str:
+    """Convert segments to CamelCase."""
+    return "".join(s.capitalize() for s in segments)
+
+
+def _to_kebab(segments: list[str]) -> str:
+    """Convert segments to kebab-case."""
+    return "-".join(s.lower() for s in segments)
+
+
+def find_source_file(page_id: str, project_root: str) -> list[str]:
+    """
+    Find source files matching a page_id.
+
+    Strategy:
+    1. Try glob with segments joined: **/*seg1*seg2*
+    2. Try CamelCase: **/*Seg1Seg2*
+    3. Try kebab-case: **/*seg1-seg2*
+    4. Try each segment individually if above fails
+
+    Returns list of matching file paths (relative to project_root).
+    """
+    if not project_root or not os.path.isdir(project_root):
+        return []
+
+    segments = _to_segments(page_id)
+    if not segments:
+        return []
+
+    candidates: set[str] = set()
+
+    # Pattern 1: segments joined with wildcards
+    joined_pattern = "*".join(s.lower() for s in segments)
+    # Pattern 2: CamelCase
+    camel = _to_camel(segments)
+    # Pattern 3: kebab-case
+    kebab = _to_kebab(segments)
+
+    patterns = [
+        f"**/*{joined_pattern}*",
+        f"**/*{camel}*",
+        f"**/*{kebab}*",
+    ]
+
+    for pattern in patterns:
+        for match in glob.glob(
+            os.path.join(project_root, pattern), recursive=True
+        ):
+            # Skip node_modules, dist, .git etc.
+            rel = os.path.relpath(match, project_root)
+            parts = rel.replace("\\", "/").split("/")
+            skip_dirs = {"node_modules", "dist", ".git", "__pycache__", ".angular"}
+            if any(p in skip_dirs for p in parts):
+                continue
+            if os.path.isfile(match):
+                candidates.add(rel.replace("\\", "/"))
+
+    return sorted(candidates)