mcp-agent-trace 1.0.0__tar.gz

mcp_agent_trace-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2026 AMEOBIUS
+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_agent_trace-1.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mcp-agent-trace
+Version: 1.0.0
+Summary: Agent tracing: step-by-step execution traces for AI agent debugging
+Author: aaameobius-crypto
+License: MIT
+Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates
+Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
+Keywords: mcp,ai,agent,harness,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MCP Agent Trace — Observability for AI Agent Loops
+
+> Record agent events, build trace trees, compute metrics, detect loops, and export traces. Zero dependencies, pure Python stdlib.
+
+## The Problem
+
+Agent decisions are black boxes. No way to trace what happened, what tokens were spent on, where loops occurred. Debugging agent failures requires guessing.
+
+## The Solution
+
+**MCP Agent Trace** records structured events throughout the agent loop, builds hierarchical trace trees, computes token/latency metrics, detects repeated action patterns, and exports full traces as JSON.
+
+## Tools (12)
+
+| Tool | What it does |
+|------|-------------|
+| `start_trace` | Begin a new trace session |
+| `end_trace` | End session, compute summary metrics |
+| `log_event` | Record a structured event (tool_call, decision, error, milestone) |
+| `get_trace` | Get full trace tree for a session |
+| `get_metrics` | Token usage, tool calls, latency, loop detection |
+| `detect_loops` | Find repeated tool-call patterns |
+| `export_trace` | Export as JSON for external analysis |
+| `list_sessions` | List all trace sessions |
+| `get_timeline` | Chronological event timeline |
+| `annotate` | Add human annotation to an event |
+| `get_stats` | Aggregate statistics across sessions |
+| `reset` | Clear all sessions and traces |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v  # 28 tests, all passing
+```
+
+## Inspiration
+
+- [AgentDoG](https://arxiv.org/abs/2601.18491) — Diagnostic guardrails
+- [Azure SRE Agent observability](https://techcommunity.microsoft.com/blog/appsonazureblog/how-we-build-azure-sre-agent-with-agentic-workflows/4508753) — 35k incidents traced
+- [LangChain middleware](https://blog.langchain.com/how-middleware-lets-you-customize-your-agent-harness/) — Agent loop hooks
+- [The Design Space of Today's AI Agent Systems](https://arxiv.org/abs/2604.14228) — 27-event-type hook pipeline
+
+## License
+
+MIT — aaameobius-crypto

mcp_agent_trace-1.0.0/README.md

@@ -0,0 +1,45 @@
+# MCP Agent Trace — Observability for AI Agent Loops
+
+> Record agent events, build trace trees, compute metrics, detect loops, and export traces. Zero dependencies, pure Python stdlib.
+
+## The Problem
+
+Agent decisions are black boxes. No way to trace what happened, what tokens were spent on, where loops occurred. Debugging agent failures requires guessing.
+
+## The Solution
+
+**MCP Agent Trace** records structured events throughout the agent loop, builds hierarchical trace trees, computes token/latency metrics, detects repeated action patterns, and exports full traces as JSON.
+
+## Tools (12)
+
+| Tool | What it does |
+|------|-------------|
+| `start_trace` | Begin a new trace session |
+| `end_trace` | End session, compute summary metrics |
+| `log_event` | Record a structured event (tool_call, decision, error, milestone) |
+| `get_trace` | Get full trace tree for a session |
+| `get_metrics` | Token usage, tool calls, latency, loop detection |
+| `detect_loops` | Find repeated tool-call patterns |
+| `export_trace` | Export as JSON for external analysis |
+| `list_sessions` | List all trace sessions |
+| `get_timeline` | Chronological event timeline |
+| `annotate` | Add human annotation to an event |
+| `get_stats` | Aggregate statistics across sessions |
+| `reset` | Clear all sessions and traces |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v  # 28 tests, all passing
+```
+
+## Inspiration
+
+- [AgentDoG](https://arxiv.org/abs/2601.18491) — Diagnostic guardrails
+- [Azure SRE Agent observability](https://techcommunity.microsoft.com/blog/appsonazureblog/how-we-build-azure-sre-agent-with-agentic-workflows/4508753) — 35k incidents traced
+- [LangChain middleware](https://blog.langchain.com/how-middleware-lets-you-customize-your-agent-harness/) — Agent loop hooks
+- [The Design Space of Today's AI Agent Systems](https://arxiv.org/abs/2604.14228) — 27-event-type hook pipeline
+
+## License
+
+MIT — aaameobius-crypto

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

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mcp-agent-trace
+Version: 1.0.0
+Summary: Agent tracing: step-by-step execution traces for AI agent debugging
+Author: aaameobius-crypto
+License: MIT
+Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates
+Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
+Keywords: mcp,ai,agent,harness,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MCP Agent Trace — Observability for AI Agent Loops
+
+> Record agent events, build trace trees, compute metrics, detect loops, and export traces. Zero dependencies, pure Python stdlib.
+
+## The Problem
+
+Agent decisions are black boxes. No way to trace what happened, what tokens were spent on, where loops occurred. Debugging agent failures requires guessing.
+
+## The Solution
+
+**MCP Agent Trace** records structured events throughout the agent loop, builds hierarchical trace trees, computes token/latency metrics, detects repeated action patterns, and exports full traces as JSON.
+
+## Tools (12)
+
+| Tool | What it does |
+|------|-------------|
+| `start_trace` | Begin a new trace session |
+| `end_trace` | End session, compute summary metrics |
+| `log_event` | Record a structured event (tool_call, decision, error, milestone) |
+| `get_trace` | Get full trace tree for a session |
+| `get_metrics` | Token usage, tool calls, latency, loop detection |
+| `detect_loops` | Find repeated tool-call patterns |
+| `export_trace` | Export as JSON for external analysis |
+| `list_sessions` | List all trace sessions |
+| `get_timeline` | Chronological event timeline |
+| `annotate` | Add human annotation to an event |
+| `get_stats` | Aggregate statistics across sessions |
+| `reset` | Clear all sessions and traces |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v  # 28 tests, all passing
+```
+
+## Inspiration
+
+- [AgentDoG](https://arxiv.org/abs/2601.18491) — Diagnostic guardrails
+- [Azure SRE Agent observability](https://techcommunity.microsoft.com/blog/appsonazureblog/how-we-build-azure-sre-agent-with-agentic-workflows/4508753) — 35k incidents traced
+- [LangChain middleware](https://blog.langchain.com/how-middleware-lets-you-customize-your-agent-harness/) — Agent loop hooks
+- [The Design Space of Today's AI Agent Systems](https://arxiv.org/abs/2604.14228) — 27-event-type hook pipeline
+
+## License
+
+MIT — aaameobius-crypto

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

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+./src/__init__.py
+./src/agent_trace_engine.py
+./src/server.py
+mcp_agent_trace.egg-info/PKG-INFO
+mcp_agent_trace.egg-info/SOURCES.txt
+mcp_agent_trace.egg-info/dependency_links.txt
+mcp_agent_trace.egg-info/top_level.txt
+src/__init__.py
+src/agent_trace_engine.py
+src/server.py
+tests/test_agent_trace.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+src

mcp_agent_trace-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-agent-trace"
+version = "1.0.0"
+description = "Agent tracing: step-by-step execution traces for AI agent debugging"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "aaameobius-crypto"}]
+keywords = ["mcp", "ai", "agent", "harness", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/aaameobius-crypto/darkbot-ai-templates"
+Repository = "https://github.com/aaameobius-crypto/darkbot-ai-templates"
+
+[tool.setuptools]
+packages = ["src"]
+package-dir = {"" = "."}

mcp_agent_trace-1.0.0/setup.cfg

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

mcp_agent_trace-1.0.0/src/__init__.py

@@ -0,0 +1,5 @@
+"""mcp-agent-trace package — MCP server for agent loop observability."""
+from .agent_trace_engine import AgentTrace
+from .server import MCPAgentTraceServer, TOOL_DEFS
+__all__ = ["AgentTrace", "MCPAgentTraceServer", "TOOL_DEFS"]
+__version__ = "1.0.0"

mcp_agent_trace-1.0.0/src/agent_trace_engine.py

@@ -0,0 +1,269 @@
+"""Agent Trace engine — zero dependencies.
+Records agent loop events, builds trace trees, computes metrics,
+detects loops, and exports traces for external analysis.
+"""
+import json, time, collections, hashlib
+from typing import Any, Dict, List, Optional, Tuple
+
+class AgentTrace:
+    @staticmethod
+    def create_store() -> Dict:
+        return {
+            "stats": {"events_logged": 0, "sessions_started": 0, "sessions_ended": 0, "loops_detected": 0, "errors": 0},
+            "sessions": {},  # session_id -> {start, end, events, metadata}
+            "active_session": None,
+        }
+
+    @staticmethod
+    def _track(store: Dict, op: str):
+        store["stats"][op] = store["stats"].get(op, 0) + 1
+
+    @staticmethod
+    def _gen_id() -> str:
+        return hashlib.sha256(str(time.time()).encode()).hexdigest()[:12]
+
+    @staticmethod
+    def start_trace(store: Dict, name: str = "", metadata: Dict = None) -> Dict:
+        AgentTrace._track(store, "sessions_started")
+        session_id = AgentTrace._gen_id()
+        store["sessions"][session_id] = {
+            "id": session_id,
+            "name": name or f"trace_{session_id[:8]}",
+            "start_time": time.time(),
+            "end_time": None,
+            "events": [],
+            "metadata": metadata or {},
+            "status": "active",
+        }
+        store["active_session"] = session_id
+        return {"success": True, "session_id": session_id, "name": store["sessions"][session_id]["name"]}
+
+    @staticmethod
+    def end_trace(store: Dict, session_id: str = None) -> Dict:
+        AgentTrace._track(store, "sessions_ended")
+        sid = session_id or store["active_session"]
+        if not sid or sid not in store["sessions"]:
+            return {"success": False, "error": "Session not found"}
+        session = store["sessions"][sid]
+        session["end_time"] = time.time()
+        session["status"] = "ended"
+        if store["active_session"] == sid:
+            store["active_session"] = None
+
+        # Compute summary metrics
+        events = session["events"]
+        duration = session["end_time"] - session["start_time"]
+        tool_calls = [e for e in events if e.get("type") == "tool_call"]
+        errors = [e for e in events if e.get("type") == "error"]
+        decisions = [e for e in events if e.get("type") == "decision"]
+
+        # Estimate token usage from event data
+        total_tokens = sum(e.get("metadata", {}).get("tokens", 0) for e in events)
+
+        # Detect loops
+        loops = AgentTrace._detect_loops_in_events(events)
+
+        return {
+            "success": True,
+            "session_id": sid,
+            "duration_seconds": round(duration, 3),
+            "total_events": len(events),
+            "tool_calls": len(tool_calls),
+            "errors": len(errors),
+            "decisions": len(decisions),
+            "estimated_tokens": total_tokens,
+            "loops_detected": len(loops),
+            "status": "ended",
+        }
+
+    @staticmethod
+    def log_event(store: Dict, event_type: str, data: Dict = None, session_id: str = None) -> Dict:
+        AgentTrace._track(store, "events_logged")
+        sid = session_id or store["active_session"]
+        if not sid or sid not in store["sessions"]:
+            # Auto-create a session
+            r = AgentTrace.start_trace(store)
+            sid = r["session_id"]
+
+        event = {
+            "id": AgentTrace._gen_id(),
+            "timestamp": time.time(),
+            "type": event_type,
+            "data": data or {},
+            "sequence": len(store["sessions"][sid]["events"]),
+        }
+        store["sessions"][sid]["events"].append(event)
+        if event_type == "error":
+            AgentTrace._track(store, "errors")
+        return {"success": True, "event_id": event["id"], "session_id": sid, "sequence": event["sequence"]}
+
+    @staticmethod
+    def get_trace(store: Dict, session_id: str) -> Dict:
+        if session_id not in store["sessions"]:
+            return {"success": False, "error": "Session not found"}
+        session = store["sessions"][session_id]
+        # Build tree from flat events
+        events = session["events"]
+        tree = AgentTrace._build_tree(events)
+        return {
+            "success": True,
+            "session": {
+                "id": session["id"],
+                "name": session["name"],
+                "start_time": session["start_time"],
+                "end_time": session["end_time"],
+                "status": session["status"],
+                "metadata": session["metadata"],
+            },
+            "events": events,
+            "tree": tree,
+            "total_events": len(events),
+        }
+
+    @staticmethod
+    def _build_tree(events: List[Dict]) -> Dict:
+        """Build a simple tree from flat events based on parent_id in data."""
+        root = {"id": "root", "children": []}
+        nodes = {"root": root}
+        for e in events:
+            parent_id = e.get("data", {}).get("parent_id", "root")
+            node = {"id": e["id"], "type": e["type"], "timestamp": e["timestamp"], "children": []}
+            nodes[e["id"]] = node
+            if parent_id in nodes:
+                nodes[parent_id]["children"].append(node)
+            else:
+                root["children"].append(node)
+        return root
+
+    @staticmethod
+    def get_metrics(store: Dict, session_id: str) -> Dict:
+        if session_id not in store["sessions"]:
+            return {"success": False, "error": "Session not found"}
+        session = store["sessions"][session_id]
+        events = session["events"]
+        end = session["end_time"] or time.time()
+        duration = end - session["start_time"]
+
+        type_counts = dict(collections.Counter(e["type"] for e in events))
+
+        # Tool call latency
+        tool_calls = [e for e in events if e.get("type") == "tool_call"]
+        latencies = [e.get("data", {}).get("latency_ms", 0) for e in tool_calls if "latency_ms" in e.get("data", {})]
+
+        # Token usage by type
+        tokens_by_type = collections.defaultdict(int)
+        for e in events:
+            tokens_by_type[e["type"]] += e.get("data", {}).get("tokens", 0)
+
+        loops = AgentTrace._detect_loops_in_events(events)
+
+        return {
+            "success": True,
+            "session_id": session_id,
+            "duration_seconds": round(duration, 3),
+            "total_events": len(events),
+            "events_by_type": type_counts,
+            "tokens_by_type": dict(tokens_by_type),
+            "total_tokens": sum(tokens_by_type.values()),
+            "tool_calls": len(tool_calls),
+            "avg_latency_ms": round(sum(latencies) / len(latencies), 2) if latencies else 0,
+            "max_latency_ms": max(latencies) if latencies else 0,
+            "loops_detected": len(loops),
+            "events_per_second": round(len(events) / max(duration, 0.001), 2),
+        }
+
+    @staticmethod
+    def _detect_loops_in_events(events: List[Dict]) -> List[Dict]:
+        """Detect repeated action patterns in events."""
+        loops = []
+        # Simple: look for repeated tool_call sequences of length 2-5
+        tool_calls = [(e["sequence"], e.get("data", {}).get("tool", "")) for e in events if e.get("type") == "tool_call"]
+        if len(tool_calls) < 4:
+            return loops
+
+        for seq_len in (2, 3):
+            seen = {}
+            for i in range(len(tool_calls) - seq_len + 1):
+                key = tuple(tc[1] for tc in tool_calls[i:i + seq_len])
+                if key in seen:
+                    loops.append({
+                        "pattern": list(key),
+                        "first_at": seen[key],
+                        "repeated_at": tool_calls[i][0],
+                        "sequence_length": seq_len,
+                    })
+                else:
+                    seen[key] = tool_calls[i][0]
+
+        return loops
+
+    @staticmethod
+    def detect_loops(store: Dict, session_id: str = None) -> Dict:
+        sid = session_id or store["active_session"]
+        if not sid or sid not in store["sessions"]:
+            return {"success": False, "error": "No session"}
+        loops = AgentTrace._detect_loops_in_events(store["sessions"][sid]["events"])
+        store["stats"]["loops_detected"] += len(loops)
+        return {"success": True, "loops": loops, "count": len(loops)}
+
+    @staticmethod
+    def export_trace(store: Dict, session_id: str, format: str = "json") -> Dict:
+        trace = AgentTrace.get_trace(store, session_id)
+        if not trace["success"]:
+            return trace
+        if format == "json":
+            return {"success": True, "format": "json", "data": json.dumps(trace, indent=2)}
+        return trace
+
+    @staticmethod
+    def list_sessions(store: Dict) -> Dict:
+        sessions = []
+        for sid, s in store["sessions"].items():
+            sessions.append({
+                "id": sid,
+                "name": s["name"],
+                "status": s["status"],
+                "start_time": s["start_time"],
+                "end_time": s["end_time"],
+                "events": len(s["events"]),
+            })
+        sessions.sort(key=lambda x: -x["start_time"])
+        return {"success": True, "sessions": sessions, "total": len(sessions)}
+
+    @staticmethod
+    def get_timeline(store: Dict, session_id: str, limit: int = 50) -> Dict:
+        if session_id not in store["sessions"]:
+            return {"success": False, "error": "Session not found"}
+        events = store["sessions"][session_id]["events"][-limit:]
+        start = store["sessions"][session_id]["start_time"]
+        timeline = []
+        for e in events:
+            timeline.append({
+                "t": round(e["timestamp"] - start, 3),
+                "type": e["type"],
+                "data": e["data"],
+                "sequence": e["sequence"],
+            })
+        return {"success": True, "timeline": timeline, "count": len(timeline)}
+
+    @staticmethod
+    def annotate(store: Dict, session_id: str, event_id: str, annotation: str) -> Dict:
+        if session_id not in store["sessions"]:
+            return {"success": False, "error": "Session not found"}
+        for e in store["sessions"][session_id]["events"]:
+            if e["id"] == event_id:
+                e.setdefault("annotations", []).append({"text": annotation, "timestamp": time.time()})
+                return {"success": True, "event_id": event_id, "annotation": annotation}
+        return {"success": False, "error": "Event not found"}
+
+    @staticmethod
+    def get_stats(store: Dict) -> Dict:
+        return {"success": True, **store["stats"], "total_sessions": len(store["sessions"])}
+
+    @staticmethod
+    def reset(store: Dict) -> Dict:
+        old = AgentTrace.get_stats(store)
+        store["stats"] = {"events_logged": 0, "sessions_started": 0, "sessions_ended": 0, "loops_detected": 0, "errors": 0}
+        store["sessions"] = {}
+        store["active_session"] = None
+        return {"success": True, "reset": old}

mcp_agent_trace-1.0.0/src/server.py

@@ -0,0 +1,71 @@
+"""MCP Server for Agent Trace — observability and tracing for agent loops."""
+import json, sys, argparse
+from .agent_trace_engine import AgentTrace
+
+_store = AgentTrace.create_store()
+
+TOOL_DEFS = [
+    {"name":"start_trace","description":"Start a new trace session.","inputSchema":{"type":"object","properties":{"name":{"type":"string","default":""},"metadata":{"type":"object"}},"required":[]}},
+    {"name":"end_trace","description":"End trace session and compute summary.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"}},"required":[]}},
+    {"name":"log_event","description":"Record a structured trace event.","inputSchema":{"type":"object","properties":{"event_type":{"type":"string"},"data":{"type":"object"},"session_id":{"type":"string"}},"required":["event_type"]}},
+    {"name":"get_trace","description":"Get full trace tree for a session.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"}},"required":["session_id"]}},
+    {"name":"get_metrics","description":"Get token usage, tool calls, latency, loops.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"}},"required":["session_id"]}},
+    {"name":"detect_loops","description":"Find repeated action patterns.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"}},"required":[]}},
+    {"name":"export_trace","description":"Export trace as JSON.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"},"format":{"type":"string","default":"json"}},"required":["session_id"]}},
+    {"name":"list_sessions","description":"List all trace sessions.","inputSchema":{"type":"object","properties":{},"required":[]}},
+    {"name":"get_timeline","description":"Chronological event timeline.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"},"limit":{"type":"integer","default":50}},"required":["session_id"]}},
+    {"name":"annotate","description":"Add human annotation to an event.","inputSchema":{"type":"object","properties":{"session_id":{"type":"string"},"event_id":{"type":"string"},"annotation":{"type":"string"}},"required":["session_id","event_id","annotation"]}},
+    {"name":"get_stats","description":"Get aggregate trace statistics.","inputSchema":{"type":"object","properties":{},"required":[]}},
+    {"name":"reset","description":"Clear all sessions and traces.","inputSchema":{"type":"object","properties":{},"required":[]}},
+]
+
+class MCPAgentTraceServer:
+    def __init__(self,name="mcp-agent-trace",version="1.0.0"):
+        self.name=name;self.version=version
+    def list_tools(self):return TOOL_DEFS
+    def manifest(self):return{"server":{"name":self.name,"version":self.version},"capabilities":{"tools":{"listChanged":False}},"tools":self.list_tools()}
+    def handle_tool_call(self,name,args):
+        try:
+            if name=="start_trace":return json.dumps(AgentTrace.start_trace(_store,args.get("name",""),args.get("metadata")))
+            elif name=="end_trace":return json.dumps(AgentTrace.end_trace(_store,args.get("session_id")))
+            elif name=="log_event":return json.dumps(AgentTrace.log_event(_store,args["event_type"],args.get("data"),args.get("session_id")))
+            elif name=="get_trace":return json.dumps(AgentTrace.get_trace(_store,args["session_id"]))
+            elif name=="get_metrics":return json.dumps(AgentTrace.get_metrics(_store,args["session_id"]))
+            elif name=="detect_loops":return json.dumps(AgentTrace.detect_loops(_store,args.get("session_id")))
+            elif name=="export_trace":return json.dumps(AgentTrace.export_trace(_store,args["session_id"],args.get("format","json")))
+            elif name=="list_sessions":return json.dumps(AgentTrace.list_sessions(_store))
+            elif name=="get_timeline":return json.dumps(AgentTrace.get_timeline(_store,args["session_id"],args.get("limit",50)))
+            elif name=="annotate":return json.dumps(AgentTrace.annotate(_store,args["session_id"],args["event_id"],args["annotation"]))
+            elif name=="get_stats":return json.dumps(AgentTrace.get_stats(_store))
+            elif name=="reset":return json.dumps(AgentTrace.reset(_store))
+            else:return json.dumps({"error":f"Unknown tool: {name}"})
+        except KeyError as e:return json.dumps({"error":f"Missing required parameter: {e}","tool":name})
+        except Exception as e:return json.dumps({"error":str(e),"tool":name})
+
+def _run_stdio():
+    server=MCPAgentTraceServer()
+    for line in sys.stdin:
+        line=line.strip()
+        if not line:continue
+        try:request=json.loads(line)
+        except json.JSONDecodeError:print(json.dumps({"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error"}}),flush=True);continue
+        method=request.get("method","");req_id=request.get("id");params=request.get("params",{})
+        if method=="initialize":response={"jsonrpc":"2.0","id":req_id,"result":{"server":server.name,"version":server.version}}
+        elif method=="tools/list":response={"jsonrpc":"2.0","id":req_id,"result":{"tools":server.list_tools()}}
+        elif method=="tools/call":
+            result=server.handle_tool_call(params.get("name",""),params.get("arguments",{}))
+            response={"jsonrpc":"2.0","id":req_id,"result":{"content":[{"type":"text","text":result}]}}
+        elif method=="shutdown":response={"jsonrpc":"2.0","id":req_id,"result":{}};print(json.dumps(response),flush=True);break
+        else:response={"jsonrpc":"2.0","id":req_id,"error":{"code":-32601,"message":f"Method not found: {method}"}}
+        print(json.dumps(response),flush=True)
+
+def main():
+    parser=argparse.ArgumentParser(description="MCP Agent Trace Server")
+    parser.add_argument("--stdio",action="store_true")
+    parser.add_argument("--manifest",action="store_true")
+    args=parser.parse_args()
+    if args.manifest:print(json.dumps(MCPAgentTraceServer().manifest(),indent=2))
+    elif args.stdio:_run_stdio()
+    else:parser.print_help()
+
+if __name__=="__main__":main()

mcp_agent_trace-1.0.0/tests/test_agent_trace.py

@@ -0,0 +1,190 @@
+"""Tests for MCP Agent Trace — sessions, events, metrics, loops, timeline."""
+import json, pytest, os, sys, time
+from unittest.mock import patch
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from src.server import MCPAgentTraceServer, TOOL_DEFS
+from src.agent_trace_engine import AgentTrace
+
+class TestToolDefs:
+    def test_names(self):
+        for t in TOOL_DEFS: assert "name" in t and len(t["name"])>0
+    def test_descs(self):
+        for t in TOOL_DEFS: assert "description" in t and len(t["description"])>15
+    def test_schema(self):
+        for t in TOOL_DEFS: assert "inputSchema" in t and t["inputSchema"]["type"]=="object"
+    def test_count(self):
+        assert len(TOOL_DEFS)==12
+    def test_required(self):
+        names={t["name"] for t in TOOL_DEFS}
+        expected={"start_trace","end_trace","log_event","get_trace","get_metrics","detect_loops","export_trace","list_sessions","get_timeline","annotate","get_stats","reset"}
+        assert names==expected
+
+class TestManifest:
+    def test_manifest(self):
+        s=MCPAgentTraceServer();m=s.manifest()
+        assert m["server"]["name"]=="mcp-agent-trace"
+        assert len(m["tools"])==12
+
+class TestStartEndTrace:
+    def test_start(self):
+        s=AgentTrace.create_store()
+        r=AgentTrace.start_trace(s,name="test_session")
+        assert r["success"] is True
+        assert len(r["session_id"])>0
+        assert r["name"]=="test_session"
+    def test_end(self):
+        s=AgentTrace.create_store()
+        r=AgentTrace.start_trace(s,name="test")
+        time.sleep(0.01)
+        end=AgentTrace.end_trace(s,r["session_id"])
+        assert end["success"] is True
+        assert end["duration_seconds"]>0
+        assert end["status"]=="ended"
+    def test_end_nonexistent(self):
+        s=AgentTrace.create_store()
+        r=AgentTrace.end_trace(s,"nonexistent")
+        assert r["success"] is False
+
+class TestLogEvent:
+    def test_basic(self):
+        s=AgentTrace.create_store()
+        AgentTrace.start_trace(s)
+        r=AgentTrace.log_event(s,"tool_call",{"tool":"read_file","args":{"path":"/tmp"}})
+        assert r["success"] is True
+        assert r["sequence"]==0
+    def test_multiple(self):
+        s=AgentTrace.create_store()
+        AgentTrace.start_trace(s)
+        AgentTrace.log_event(s,"tool_call",{"tool":"a"})
+        AgentTrace.log_event(s,"decision",{"action":"proceed"})
+        r=AgentTrace.log_event(s,"tool_call",{"tool":"b"})
+        assert r["sequence"]==2
+    def test_auto_session(self):
+        s=AgentTrace.create_store()
+        r=AgentTrace.log_event(s,"milestone",{"msg":"started"})
+        assert r["success"] is True  # auto-creates session
+
+class TestGetTrace:
+    def test_basic(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s,name="test")["session_id"]
+        AgentTrace.log_event(s,"tool_call",{"tool":"read"},session_id=sid)
+        r=AgentTrace.get_trace(s,sid)
+        assert r["success"] is True
+        assert r["total_events"]==1
+        assert "tree" in r
+    def test_not_found(self):
+        s=AgentTrace.create_store()
+        r=AgentTrace.get_trace(s,"nonexistent")
+        assert r["success"] is False
+
+class TestGetMetrics:
+    def test_basic(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        AgentTrace.log_event(s,"tool_call",{"tool":"a","latency_ms":100,"tokens":50},session_id=sid)
+        AgentTrace.log_event(s,"tool_call",{"tool":"b","latency_ms":200,"tokens":30},session_id=sid)
+        AgentTrace.log_event(s,"error",{"msg":"failed"},session_id=sid)
+        r=AgentTrace.get_metrics(s,sid)
+        assert r["success"] is True
+        assert r["tool_calls"]==2
+        assert r["avg_latency_ms"]==150
+        assert r["total_tokens"]==80
+        assert r["events_by_type"]["error"]==1
+
+class TestDetectLoops:
+    def test_loop(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        # Create a repeated pattern: a,b,a,b
+        for tool in ["read","write","read","write","read","write"]:
+            AgentTrace.log_event(s,"tool_call",{"tool":tool},session_id=sid)
+        r=AgentTrace.detect_loops(s,sid)
+        assert r["success"] is True
+        assert r["count"]>0
+    def test_no_loop(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        for tool in ["read","write","delete","search"]:
+            AgentTrace.log_event(s,"tool_call",{"tool":tool},session_id=sid)
+        r=AgentTrace.detect_loops(s,sid)
+        assert r["count"]==0
+
+class TestExportTrace:
+    def test_json(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        AgentTrace.log_event(s,"milestone",{"msg":"test"},session_id=sid)
+        r=AgentTrace.export_trace(s,sid,format="json")
+        assert r["success"] is True
+        assert r["format"]=="json"
+        assert isinstance(r["data"],str)
+        parsed=json.loads(r["data"])
+        assert parsed["total_events"]==1
+
+class TestListSessions:
+    def test_list(self):
+        s=AgentTrace.create_store()
+        AgentTrace.start_trace(s,name="s1")
+        AgentTrace.start_trace(s,name="s2")
+        r=AgentTrace.list_sessions(s)
+        assert r["total"]==2
+        assert all("name" in sess for sess in r["sessions"])
+
+class TestGetTimeline:
+    def test_basic(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        AgentTrace.log_event(s,"tool_call",{"tool":"a"},session_id=sid)
+        AgentTrace.log_event(s,"decision",{"action":"b"},session_id=sid)
+        r=AgentTrace.get_timeline(s,sid)
+        assert r["count"]==2
+        assert r["timeline"][0]["t"]<=r["timeline"][1]["t"]
+        assert "type" in r["timeline"][0]
+
+class TestAnnotate:
+    def test_basic(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        eid=AgentTrace.log_event(s,"milestone",{"msg":"done"},session_id=sid)["event_id"]
+        r=AgentTrace.annotate(s,sid,eid,"This was important")
+        assert r["success"] is True
+    def test_event_not_found(self):
+        s=AgentTrace.create_store()
+        sid=AgentTrace.start_trace(s)["session_id"]
+        r=AgentTrace.annotate(s,sid,"nonexistent","note")
+        assert r["success"] is False
+
+class TestStatsReset:
+    def test_stats(self):
+        s=AgentTrace.create_store()
+        AgentTrace.start_trace(s)
+        AgentTrace.log_event(s,"tool_call")
+        r=AgentTrace.get_stats(s)
+        assert r["sessions_started"]==1
+        assert r["events_logged"]==1
+    def test_reset(self):
+        s=AgentTrace.create_store()
+        AgentTrace.start_trace(s)
+        AgentTrace.log_event(s,"tool_call")
+        r=AgentTrace.reset(s)
+        assert r["reset"]["events_logged"]==1
+        assert AgentTrace.get_stats(s)["events_logged"]==0
+        assert AgentTrace.list_sessions(s)["total"]==0
+
+class TestDispatch:
+    def test_unknown(self):
+        srv=MCPAgentTraceServer();assert "error" in json.loads(srv.handle_tool_call("nope",{}))
+    def test_missing(self):
+        srv=MCPAgentTraceServer();assert "error" in json.loads(srv.handle_tool_call("get_trace",{}))
+    def test_start_dispatch(self):
+        srv=MCPAgentTraceServer()
+        r=json.loads(srv.handle_tool_call("start_trace",{"name":"test"}))
+        assert r["success"] is True
+
+class TestSTDIO:
+    def test_manifest_flag(self,capsys):
+        from src.server import main
+        with patch("sys.argv",["server","--manifest"]):main()
+        parsed=json.loads(capsys.readouterr().out.strip())
+        assert parsed["server"]["name"]=="mcp-agent-trace"