triage-mcp 1.0.0__tar.gz

triage_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Al Amin Bashir Afara
+
+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.

triage_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: triage-mcp
+Version: 1.0.0
+Summary: MCP server over a support ticket triage queue: four read-only tools for pending reviews and the decision log
+Author: Al Amin Bashir Afara
+License: MIT
+Project-URL: Homepage, https://github.com/aminafara123/triage-mcp
+Project-URL: Repository, https://github.com/aminafara123/triage-mcp
+Keywords: mcp,ticket-triage,support-tickets,helpdesk,human-in-the-loop,audit-log
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Dynamic: license-file
+
+# triage-mcp
+
+An MCP server over my [ai-triage-agent](https://github.com/aminafara123/ai-triage-agent) queue. A local LLM classifies support tickets and drafts replies, a human approves or rejects every one, and this server lets any MCP-capable AI client read that queue and the decision log.
+
+It answers questions like "whats waiting for review?" or "what did I reject this week and why?" straight from the files the agent writes. Four tools, all read-only. The model can look at the queue but it cant approve, reject or send anything.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `queue_status()` | Counts for inbox, pending review by priority, outbox and logged decisions |
+| `pending_items(priority)` | Tickets waiting for review, most urgent first, optional priority filter |
+| `recent_decisions(limit)` | Latest human decisions from the audit log, newest first |
+| `search_decisions(query)` | Search the decision log by id, outcome, category, priority or reject reason |
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install mcp
+```
+
+It reads `~/aiProjects/aminWork/automation-portfolio/ai-triage-agent/`. Change `DATA_DIR` at the top of `triage_mcp.py` if your copy lives somewhere else.
+
+Wire it into Claude Code:
+
+```bash
+claude mcp add triage -- /path/to/triage-mcp/.venv/bin/python /path/to/triage-mcp/triage_mcp.py
+```
+
+## Demo
+
+What it looks like from Claude Code:
+
+```
+> anything urgent sitting in the triage queue?
+
+⏺ triage · pending_items()
+
+  2 pending item(s):
+  demo-014 P1 security_incident -> security-team (high): User entered their password on a fake helpdesk link and asks what to do next.
+  demo-017 P3 software_issue -> service-desk (medium): Spreadsheet app crashes when opening one monthly report file.
+
+⏺ One P1. demo-014 looks like a phishing hit and is routed to security.
+  Id review that one first. The Excel crash can wait.
+```
+
+The tickets above are demo data. The format is exactly what the server returns.
+
+## Design notes
+
+- **Read-only by construction.** No tool writes to the queue, the outbox or the log. Approving stays in `review.py` with a human at the keyboard.
+- **Only metadata crosses the protocol.** Ticket bodies, extracted entities and reply text never leave the server. Summaries and reject reasons are cut to 100 characters with emails and home paths masked.
+- **Small on purpose.** One file, standard library plus the `mcp` SDK.
+
+## Honest notes
+
+- It only reads what ai-triage-agent has already written. With an empty `pending/` folder most answers are zeros, which is normal between triage runs.
+- The masking is regex based. It catches emails and home paths, not names written into a summary.
+- All ticket content in the demo and the tests is made up. The logic is tested against a synthetic queue in `test_server.py`. Run `python test_server.py`.
+
+## About
+
+Al Amin Bashir Afara, Dubai · [github.com/aminafara123](https://github.com/aminafara123) · [linkedin.com/in/aminafara](https://www.linkedin.com/in/aminafara)

triage_mcp-1.0.0/README.md

@@ -0,0 +1,64 @@
+# triage-mcp
+
+An MCP server over my [ai-triage-agent](https://github.com/aminafara123/ai-triage-agent) queue. A local LLM classifies support tickets and drafts replies, a human approves or rejects every one, and this server lets any MCP-capable AI client read that queue and the decision log.
+
+It answers questions like "whats waiting for review?" or "what did I reject this week and why?" straight from the files the agent writes. Four tools, all read-only. The model can look at the queue but it cant approve, reject or send anything.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `queue_status()` | Counts for inbox, pending review by priority, outbox and logged decisions |
+| `pending_items(priority)` | Tickets waiting for review, most urgent first, optional priority filter |
+| `recent_decisions(limit)` | Latest human decisions from the audit log, newest first |
+| `search_decisions(query)` | Search the decision log by id, outcome, category, priority or reject reason |
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install mcp
+```
+
+It reads `~/aiProjects/aminWork/automation-portfolio/ai-triage-agent/`. Change `DATA_DIR` at the top of `triage_mcp.py` if your copy lives somewhere else.
+
+Wire it into Claude Code:
+
+```bash
+claude mcp add triage -- /path/to/triage-mcp/.venv/bin/python /path/to/triage-mcp/triage_mcp.py
+```
+
+## Demo
+
+What it looks like from Claude Code:
+
+```
+> anything urgent sitting in the triage queue?
+
+⏺ triage · pending_items()
+
+  2 pending item(s):
+  demo-014 P1 security_incident -> security-team (high): User entered their password on a fake helpdesk link and asks what to do next.
+  demo-017 P3 software_issue -> service-desk (medium): Spreadsheet app crashes when opening one monthly report file.
+
+⏺ One P1. demo-014 looks like a phishing hit and is routed to security.
+  Id review that one first. The Excel crash can wait.
+```
+
+The tickets above are demo data. The format is exactly what the server returns.
+
+## Design notes
+
+- **Read-only by construction.** No tool writes to the queue, the outbox or the log. Approving stays in `review.py` with a human at the keyboard.
+- **Only metadata crosses the protocol.** Ticket bodies, extracted entities and reply text never leave the server. Summaries and reject reasons are cut to 100 characters with emails and home paths masked.
+- **Small on purpose.** One file, standard library plus the `mcp` SDK.
+
+## Honest notes
+
+- It only reads what ai-triage-agent has already written. With an empty `pending/` folder most answers are zeros, which is normal between triage runs.
+- The masking is regex based. It catches emails and home paths, not names written into a summary.
+- All ticket content in the demo and the tests is made up. The logic is tested against a synthetic queue in `test_server.py`. Run `python test_server.py`.
+
+## About
+
+Al Amin Bashir Afara, Dubai · [github.com/aminafara123](https://github.com/aminafara123) · [linkedin.com/in/aminafara](https://www.linkedin.com/in/aminafara)

triage_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "triage-mcp"
+version = "1.0.0"
+description = "MCP server over a support ticket triage queue: four read-only tools for pending reviews and the decision log"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Al Amin Bashir Afara"}]
+requires-python = ">=3.10"
+dependencies = ["mcp"]
+keywords = ["mcp", "ticket-triage", "support-tickets", "helpdesk", "human-in-the-loop", "audit-log"]
+
+[project.urls]
+Homepage = "https://github.com/aminafara123/triage-mcp"
+Repository = "https://github.com/aminafara123/triage-mcp"
+
+[project.scripts]
+triage-mcp = "triage_mcp:main"
+
+[tool.setuptools]
+py-modules = ["triage_mcp"]

triage_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

triage_mcp-1.0.0/triage_mcp.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: triage-mcp
+Version: 1.0.0
+Summary: MCP server over a support ticket triage queue: four read-only tools for pending reviews and the decision log
+Author: Al Amin Bashir Afara
+License: MIT
+Project-URL: Homepage, https://github.com/aminafara123/triage-mcp
+Project-URL: Repository, https://github.com/aminafara123/triage-mcp
+Keywords: mcp,ticket-triage,support-tickets,helpdesk,human-in-the-loop,audit-log
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Dynamic: license-file
+
+# triage-mcp
+
+An MCP server over my [ai-triage-agent](https://github.com/aminafara123/ai-triage-agent) queue. A local LLM classifies support tickets and drafts replies, a human approves or rejects every one, and this server lets any MCP-capable AI client read that queue and the decision log.
+
+It answers questions like "whats waiting for review?" or "what did I reject this week and why?" straight from the files the agent writes. Four tools, all read-only. The model can look at the queue but it cant approve, reject or send anything.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `queue_status()` | Counts for inbox, pending review by priority, outbox and logged decisions |
+| `pending_items(priority)` | Tickets waiting for review, most urgent first, optional priority filter |
+| `recent_decisions(limit)` | Latest human decisions from the audit log, newest first |
+| `search_decisions(query)` | Search the decision log by id, outcome, category, priority or reject reason |
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install mcp
+```
+
+It reads `~/aiProjects/aminWork/automation-portfolio/ai-triage-agent/`. Change `DATA_DIR` at the top of `triage_mcp.py` if your copy lives somewhere else.
+
+Wire it into Claude Code:
+
+```bash
+claude mcp add triage -- /path/to/triage-mcp/.venv/bin/python /path/to/triage-mcp/triage_mcp.py
+```
+
+## Demo
+
+What it looks like from Claude Code:
+
+```
+> anything urgent sitting in the triage queue?
+
+⏺ triage · pending_items()
+
+  2 pending item(s):
+  demo-014 P1 security_incident -> security-team (high): User entered their password on a fake helpdesk link and asks what to do next.
+  demo-017 P3 software_issue -> service-desk (medium): Spreadsheet app crashes when opening one monthly report file.
+
+⏺ One P1. demo-014 looks like a phishing hit and is routed to security.
+  Id review that one first. The Excel crash can wait.
+```
+
+The tickets above are demo data. The format is exactly what the server returns.
+
+## Design notes
+
+- **Read-only by construction.** No tool writes to the queue, the outbox or the log. Approving stays in `review.py` with a human at the keyboard.
+- **Only metadata crosses the protocol.** Ticket bodies, extracted entities and reply text never leave the server. Summaries and reject reasons are cut to 100 characters with emails and home paths masked.
+- **Small on purpose.** One file, standard library plus the `mcp` SDK.
+
+## Honest notes
+
+- It only reads what ai-triage-agent has already written. With an empty `pending/` folder most answers are zeros, which is normal between triage runs.
+- The masking is regex based. It catches emails and home paths, not names written into a summary.
+- All ticket content in the demo and the tests is made up. The logic is tested against a synthetic queue in `test_server.py`. Run `python test_server.py`.
+
+## About
+
+Al Amin Bashir Afara, Dubai · [github.com/aminafara123](https://github.com/aminafara123) · [linkedin.com/in/aminafara](https://www.linkedin.com/in/aminafara)

triage_mcp-1.0.0/triage_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+triage_mcp.py
+triage_mcp.egg-info/PKG-INFO
+triage_mcp.egg-info/SOURCES.txt
+triage_mcp.egg-info/dependency_links.txt
+triage_mcp.egg-info/entry_points.txt
+triage_mcp.egg-info/requires.txt
+triage_mcp.egg-info/top_level.txt

triage_mcp-1.0.0/triage_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

triage_mcp-1.0.0/triage_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+triage-mcp = triage_mcp:main

triage_mcp-1.0.0/triage_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp

triage_mcp-1.0.0/triage_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+triage_mcp

triage_mcp-1.0.0/triage_mcp.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""triage-mcp: an MCP server over my ai-triage-agent queue.
+
+Exposes the triage queue and the human decision log as read-only tools
+any MCP-capable model can call. What is waiting for review, what got
+approved or rejected, and why.
+
+Run (stdio):  python server.py
+Wire into Claude Code:
+  claude mcp add triage -- /path/to/.venv/bin/python /path/to/server.py
+"""
+
+import json
+import re
+from collections import Counter
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+DATA_DIR = Path.home() / "aiProjects/aminWork/automation-portfolio/ai-triage-agent"
+CAP = 25
+
+server = MCPServer(
+    "triage",
+    instructions=(
+        "Read-only tools over a local support ticket triage queue. A local "
+        "LLM classifies tickets into pending/, a human approves or rejects "
+        "each draft reply, and every decision lands in decisions.jsonl."
+    ),
+)
+
+# Every tool only reads local queue files, so one shared annotation set.
+READ_ONLY = ToolAnnotations(
+    read_only_hint=True,
+    destructive_hint=False,
+    idempotent_hint=True,
+    open_world_hint=False,
+)
+
+EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
+HOME_PATH = re.compile(r"(/home/|/Users/|[A-Za-z]:\\Users\\)\S*")
+
+
+def _clip(text, n: int = 100) -> str:
+    # Summaries and reasons are free text, so emails and home paths go
+    # and everything is cut short. Message bodies and replies never leave.
+    text = HOME_PATH.sub("[path]", EMAIL.sub("[email]", str(text or "")))
+    text = " ".join(text.split())
+    return text if len(text) <= n else text[: n - 3] + "..."
+
+
+def _capped(lines: list) -> str:
+    out = "\n".join(lines[:CAP])
+    if len(lines) > CAP:
+        out += f"\n...and {len(lines) - CAP} more"
+    return out
+
+
+def _pending() -> list:
+    items = []
+    for p in sorted((DATA_DIR / "pending").glob("*.json")):
+        try:
+            items.append(json.loads(p.read_text(encoding="utf-8")))
+        except (json.JSONDecodeError, OSError):
+            continue
+    return items
+
+
+def _decisions() -> list:
+    log = DATA_DIR / "decisions.jsonl"
+    if not log.exists():
+        return []
+    out = []
+    for line in log.read_text(encoding="utf-8").splitlines():
+        try:
+            out.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _count(folder: str) -> int:
+    d = DATA_DIR / folder
+    return sum(1 for p in d.iterdir() if p.is_file()) if d.is_dir() else 0
+
+
+def _fmt_decision(d: dict) -> str:
+    line = (f"[{str(d.get('decided', '?'))[:10]}] {_clip(d.get('id'), 40)} "
+            f"{d.get('decision', '?')} (AI said {d.get('ai_category', '?')} "
+            f"{d.get('ai_priority', '?')})")
+    if d.get("reason"):
+        line += f": {_clip(d['reason'])}"
+    return line
+
+
+@server.tool(annotations=READ_ONLY)
+def queue_status() -> str:
+    """Counts across the pipeline: inbox, pending review by priority,
+    outbox, and logged decisions by outcome."""
+    pending = _pending()
+    decisions = _decisions()
+    prios = Counter(r.get("triage", {}).get("priority", "?") for r in pending)
+    outcomes = Counter(d.get("decision", "?") for d in decisions)
+    lines = [
+        f"Inbox: {_count('inbox')} message(s)",
+        f"Pending review: {len(pending)}"
+        + (" (" + ", ".join(f"{k} {v}" for k, v in sorted(prios.items())) + ")"
+           if pending else ""),
+        f"Outbox: {_count('outbox')} reply file(s)",
+        f"Decisions logged: {len(decisions)}"
+        + (" (" + ", ".join(f"{k} {v}" for k, v in sorted(outcomes.items())) + ")"
+           if decisions else ""),
+    ]
+    return "\n".join(lines)
+
+
+@server.tool(annotations=READ_ONLY)
+def pending_items(priority: str = "") -> str:
+    """Tickets waiting for human review, most urgent first, with category,
+    route, model confidence and a short summary. Optional priority filter
+    like "P1"."""
+    items = _pending()
+    if priority:
+        items = [r for r in items
+                 if r.get("triage", {}).get("priority", "").upper() == priority.upper()]
+    if not items:
+        return "No pending items" + (f" at {priority}." if priority else ".")
+    items.sort(key=lambda r: (r.get("triage", {}).get("priority", "P9"),
+                              str(r.get("id"))))
+    lines = []
+    for r in items:
+        t = r.get("triage", {})
+        lines.append(f"{_clip(r.get('id'), 40)} {t.get('priority', '?')} "
+                     f"{t.get('category', '?')} -> {t.get('route', '?')} "
+                     f"({t.get('confidence', '?')}): {_clip(t.get('summary'))}")
+    return f"{len(items)} pending item(s):\n" + _capped(lines)
+
+
+@server.tool(annotations=READ_ONLY)
+def recent_decisions(limit: int = 10) -> str:
+    """The latest human decisions from the audit log, newest first: what
+    the AI proposed and whether the reviewer approved, edited or rejected."""
+    decisions = _decisions()
+    if not decisions:
+        return "No decisions logged."
+    limit = max(1, min(limit, CAP))
+    recent = decisions[::-1][:limit]
+    return (f"{len(decisions)} decision(s) logged, latest {len(recent)}:\n"
+            + "\n".join(_fmt_decision(d) for d in recent))
+
+
+@server.tool(annotations=READ_ONLY)
+def search_decisions(query: str) -> str:
+    """Case-insensitive search over the decision log by ticket id, outcome,
+    AI category, priority or reject reason."""
+    q = query.lower().strip()
+    if not q:
+        return "Empty query."
+    fields = ("id", "decision", "ai_category", "ai_priority", "reason")
+    hits = [d for d in reversed(_decisions())
+            if any(q in str(d.get(f, "")).lower() for f in fields)]
+    if not hits:
+        return f"No decisions matching {query!r}."
+    return (f"{len(hits)} decision(s) matching {query!r}:\n"
+            + _capped([_fmt_decision(d) for d in hits]))
+
+
+def main():
+    server.run()
+
+
+if __name__ == "__main__":
+    main()