agentsentinel-cli 0.7.0__tar.gz → 0.7.1__tar.gz

{agentsentinel_cli-0.7.0 → agentsentinel_cli-0.7.1}/.gitignore

@@ -39,3 +39,6 @@ Thumbs.db
 .vscode/
 *.swp
 ~$*
+
+# Local documentation (not for commit)
+doc/

{agentsentinel_cli-0.7.0 → agentsentinel_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsentinel-cli
-Version: 0.7.0
+Version: 0.7.1
 Summary: Agentic security CLI — AI analyst with memory, supply chain audit, MCP audit, red-team probing, and agent discovery
 Project-URL: Homepage, https://github.com/jaydenaung/agentsentinel-cli
 Project-URL: Repository, https://github.com/jaydenaung/agentsentinel-cli
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/pypi/pyversions/agentsentinel-cli)](https://pypi.org/project/agentsentinel-cli/)
 
-**AI agent security — analyst mode, static rules, red-team probing, and MCP auditing. No server. No Docker. One install.**
+**AI agent security — analyst mode, multi-agent trust analysis, static rules, red-team probing, and MCP auditing. No server. No Docker. One install.**
 
 ```bash
 pipx install "agentsentinel-cli[all]"
@@ -61,7 +61,7 @@ pipx install "agentsentinel-cli[all]"
 
 ## What it does
 
-`sentinel` covers 8 of the 10 risks in the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/).
+`sentinel` covers 9 of the 10 risks in the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/).
 
 It operates at two levels:
 
@@ -83,6 +83,10 @@ sentinel agentic ./my-agent/
 sentinel supply-chain http://localhost:3001
 sentinel supply-chain http://localhost:3001 --ai   # + Claude semantic analysis
 
+# Multi-agent trust analysis — detect A2A trust violations in your codebase
+sentinel a2a ./agents/
+sentinel a2a multi_agent.py --fail-on HIGH
+
 # Static posture scan
 sentinel scan my_agent.py
 sentinel secrets .
@@ -300,6 +304,54 @@ sentinel discover --format json
 
 ---
 
+### `sentinel a2a` — multi-agent trust analysis
+
+Scans Python agent source files and builds a call graph showing which agents call which, then audits the trust boundaries between them. Detects the attack paths that single-agent tools miss entirely: injection that propagates across agent boundaries, unbounded agent spawning, and code-execution agents that accept delegated instructions without verification.
+
+Supports **LangChain / LangGraph**, **AutoGen**, and **CrewAI**. No API key required.
+
+```bash
+sentinel a2a ./agents/
+sentinel a2a multi_agent.py
+sentinel a2a . --fail-on HIGH
+sentinel a2a . --format json
+sentinel a2a . --ignore-rule A2A01_UNVERIFIED_ORCHESTRATOR  # suppress if handled at infra layer
+```
+
+**Rules:**
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `A2A03_IMPLICIT_TRUST` | CRITICAL | Code-execution agent accepts calls from other agents with no caller verification |
+| `A2A04_PROMPT_PASSTHROUGH` | HIGH | User input flows directly across an agent boundary without sanitization |
+| `A2A02_UNBOUNDED_SPAWNING` | HIGH | Agent is instantiated inside a loop — unbounded agent creation risk |
+| `A2A06_CIRCULAR_DELEGATION` | HIGH | Cycle in the call graph — agents can loop indefinitely under injection |
+| `A2A05_UNSCOPED_DELEGATION` | MEDIUM | Orchestrator delegates its full tool set to a sub-agent instead of a restricted subset |
+| `A2A01_UNVERIFIED_ORCHESTRATOR` | LOW | Agents receive instructions from other agents with no visible trust verification |
+
+**Example output:**
+
+```
+  2 agents  1 edges  1 max depth  acyclic
+
+  Agent         Framework   Role          Tools
+  planner       autogen     worker        —
+  executor      autogen     orchestrator  —    ⚠ code exec
+
+  Call graph:
+    executor ──► planner  initiate_chat  passes input
+
+  ● HIGH      A2A04_PROMPT_PASSTHROUGH  ASI01
+              User input flows directly from 'executor' to 'planner'
+              without sanitization at the agent boundary.
+
+  Trust Score   75/100  ███████████████░░░░░  WATCH
+```
+
+Covers **ASI07** (Insecure Inter-Agent Communication) from OWASP Top 10 for Agentic Applications 2026.
+
+---
+
 ## Finding suppression
 
 Use `--ignore-rule` to suppress specific findings by rule ID. Suppressed findings are excluded from `--fail-on` evaluation and output — they don't break CI gates.
@@ -325,7 +377,7 @@ SC03_HIDDEN_NETWORK_FIELDS  # webhook field verified safe — used for audit log
 NO_AUTH                     # server is behind an authenticated reverse proxy
 ```
 
-Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
+Supported on: `sentinel scan`, `sentinel a2a`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
 
 ---
 
@@ -339,7 +391,7 @@ Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `se
 | **Agentic Supply Chain Compromise** | **ASI04** | **`sentinel supply-chain`** (static + AI), **`sentinel agentic`** |
 | Unexpected Code Execution | ASI05 | `sentinel scan` (CODE_EXECUTION_GRANT), `sentinel mcp scan` |
 | **Memory & Context Poisoning** | **ASI06** | **`sentinel secrets`** (memory contamination), **`sentinel agentic`** |
-| Insecure Inter-Agent Communication | ASI07 | `sentinel agentic` (reasoning layer) |
+| **Insecure Inter-Agent Communication** | **ASI07** | **`sentinel a2a`** (call graph + trust rules), `sentinel agentic` (semantic reasoning) |
 | Cascading Agent Failures | ASI08 | `sentinel agentic` (cross-finding chain analysis) |
 | Human-Agent Trust Exploitation | ASI09 | `sentinel agentic` (narrative + evidence standard) |
 | Rogue Agents | ASI10 | `sentinel agentic` (drift detection across sessions) |
@@ -373,6 +425,9 @@ jobs:
 
       - name: MCP security audit
         run: sentinel mcp scan http://localhost:3001 --fail-on CRITICAL
+
+      - name: Multi-agent trust analysis
+        run: sentinel a2a ./agents/ --fail-on HIGH
 ```
 
 Use a `.sentinelignore` file at the repo root to suppress known-accepted findings without weakening the gate threshold:
@@ -393,6 +448,7 @@ MISSING_RATE_LIMIT    # rate limiting handled at infra layer
 | Investigating a specific server or codebase | `sentinel agentic` |
 | First assessment of a new MCP server | `sentinel agentic` |
 | Scheduled nightly security check | `sentinel agentic` (memory tracks drift) |
+| Auditing a multi-agent codebase | `sentinel a2a` (call graph + trust rules) |
 | Quick local sanity check | `sentinel mcp scan`, `sentinel scan` |
 | Red-teaming a live agent endpoint | `sentinel ai-probe` |
 
@@ -402,7 +458,7 @@ MISSING_RATE_LIMIT    # rate limiting handled at infra layer
 
 - Python 3.10+
 - `ANTHROPIC_API_KEY` required for: `sentinel agentic`, `sentinel ai-probe`, `sentinel supply-chain --ai`, `sentinel inspect` (AI summary)
-- No API key required for: `sentinel scan`, `sentinel secrets`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel probe`, `sentinel discover`, `sentinel inspect --no-ai`
+- No API key required for: `sentinel scan`, `sentinel a2a`, `sentinel secrets`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel probe`, `sentinel discover`, `sentinel inspect --no-ai`
 
 ---
 

{agentsentinel_cli-0.7.0 → agentsentinel_cli-0.7.1}/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/pypi/pyversions/agentsentinel-cli)](https://pypi.org/project/agentsentinel-cli/)
 
-**AI agent security — analyst mode, static rules, red-team probing, and MCP auditing. No server. No Docker. One install.**
+**AI agent security — analyst mode, multi-agent trust analysis, static rules, red-team probing, and MCP auditing. No server. No Docker. One install.**
 
 ```bash
 pipx install "agentsentinel-cli[all]"
@@ -14,7 +14,7 @@ pipx install "agentsentinel-cli[all]"
 
 ## What it does
 
-`sentinel` covers 8 of the 10 risks in the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/).
+`sentinel` covers 9 of the 10 risks in the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/).
 
 It operates at two levels:
 
@@ -36,6 +36,10 @@ sentinel agentic ./my-agent/
 sentinel supply-chain http://localhost:3001
 sentinel supply-chain http://localhost:3001 --ai   # + Claude semantic analysis
 
+# Multi-agent trust analysis — detect A2A trust violations in your codebase
+sentinel a2a ./agents/
+sentinel a2a multi_agent.py --fail-on HIGH
+
 # Static posture scan
 sentinel scan my_agent.py
 sentinel secrets .
@@ -253,6 +257,54 @@ sentinel discover --format json
 
 ---
 
+### `sentinel a2a` — multi-agent trust analysis
+
+Scans Python agent source files and builds a call graph showing which agents call which, then audits the trust boundaries between them. Detects the attack paths that single-agent tools miss entirely: injection that propagates across agent boundaries, unbounded agent spawning, and code-execution agents that accept delegated instructions without verification.
+
+Supports **LangChain / LangGraph**, **AutoGen**, and **CrewAI**. No API key required.
+
+```bash
+sentinel a2a ./agents/
+sentinel a2a multi_agent.py
+sentinel a2a . --fail-on HIGH
+sentinel a2a . --format json
+sentinel a2a . --ignore-rule A2A01_UNVERIFIED_ORCHESTRATOR  # suppress if handled at infra layer
+```
+
+**Rules:**
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `A2A03_IMPLICIT_TRUST` | CRITICAL | Code-execution agent accepts calls from other agents with no caller verification |
+| `A2A04_PROMPT_PASSTHROUGH` | HIGH | User input flows directly across an agent boundary without sanitization |
+| `A2A02_UNBOUNDED_SPAWNING` | HIGH | Agent is instantiated inside a loop — unbounded agent creation risk |
+| `A2A06_CIRCULAR_DELEGATION` | HIGH | Cycle in the call graph — agents can loop indefinitely under injection |
+| `A2A05_UNSCOPED_DELEGATION` | MEDIUM | Orchestrator delegates its full tool set to a sub-agent instead of a restricted subset |
+| `A2A01_UNVERIFIED_ORCHESTRATOR` | LOW | Agents receive instructions from other agents with no visible trust verification |
+
+**Example output:**
+
+```
+  2 agents  1 edges  1 max depth  acyclic
+
+  Agent         Framework   Role          Tools
+  planner       autogen     worker        —
+  executor      autogen     orchestrator  —    ⚠ code exec
+
+  Call graph:
+    executor ──► planner  initiate_chat  passes input
+
+  ● HIGH      A2A04_PROMPT_PASSTHROUGH  ASI01
+              User input flows directly from 'executor' to 'planner'
+              without sanitization at the agent boundary.
+
+  Trust Score   75/100  ███████████████░░░░░  WATCH
+```
+
+Covers **ASI07** (Insecure Inter-Agent Communication) from OWASP Top 10 for Agentic Applications 2026.
+
+---
+
 ## Finding suppression
 
 Use `--ignore-rule` to suppress specific findings by rule ID. Suppressed findings are excluded from `--fail-on` evaluation and output — they don't break CI gates.
@@ -278,7 +330,7 @@ SC03_HIDDEN_NETWORK_FIELDS  # webhook field verified safe — used for audit log
 NO_AUTH                     # server is behind an authenticated reverse proxy
 ```
 
-Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
+Supported on: `sentinel scan`, `sentinel a2a`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel secrets`, `sentinel inspect`.
 
 ---
 
@@ -292,7 +344,7 @@ Supported on: `sentinel scan`, `sentinel mcp scan`, `sentinel supply-chain`, `se
 | **Agentic Supply Chain Compromise** | **ASI04** | **`sentinel supply-chain`** (static + AI), **`sentinel agentic`** |
 | Unexpected Code Execution | ASI05 | `sentinel scan` (CODE_EXECUTION_GRANT), `sentinel mcp scan` |
 | **Memory & Context Poisoning** | **ASI06** | **`sentinel secrets`** (memory contamination), **`sentinel agentic`** |
-| Insecure Inter-Agent Communication | ASI07 | `sentinel agentic` (reasoning layer) |
+| **Insecure Inter-Agent Communication** | **ASI07** | **`sentinel a2a`** (call graph + trust rules), `sentinel agentic` (semantic reasoning) |
 | Cascading Agent Failures | ASI08 | `sentinel agentic` (cross-finding chain analysis) |
 | Human-Agent Trust Exploitation | ASI09 | `sentinel agentic` (narrative + evidence standard) |
 | Rogue Agents | ASI10 | `sentinel agentic` (drift detection across sessions) |
@@ -326,6 +378,9 @@ jobs:
 
       - name: MCP security audit
         run: sentinel mcp scan http://localhost:3001 --fail-on CRITICAL
+
+      - name: Multi-agent trust analysis
+        run: sentinel a2a ./agents/ --fail-on HIGH
 ```
 
 Use a `.sentinelignore` file at the repo root to suppress known-accepted findings without weakening the gate threshold:
@@ -346,6 +401,7 @@ MISSING_RATE_LIMIT    # rate limiting handled at infra layer
 | Investigating a specific server or codebase | `sentinel agentic` |
 | First assessment of a new MCP server | `sentinel agentic` |
 | Scheduled nightly security check | `sentinel agentic` (memory tracks drift) |
+| Auditing a multi-agent codebase | `sentinel a2a` (call graph + trust rules) |
 | Quick local sanity check | `sentinel mcp scan`, `sentinel scan` |
 | Red-teaming a live agent endpoint | `sentinel ai-probe` |
 
@@ -355,7 +411,7 @@ MISSING_RATE_LIMIT    # rate limiting handled at infra layer
 
 - Python 3.10+
 - `ANTHROPIC_API_KEY` required for: `sentinel agentic`, `sentinel ai-probe`, `sentinel supply-chain --ai`, `sentinel inspect` (AI summary)
-- No API key required for: `sentinel scan`, `sentinel secrets`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel probe`, `sentinel discover`, `sentinel inspect --no-ai`
+- No API key required for: `sentinel scan`, `sentinel a2a`, `sentinel secrets`, `sentinel mcp scan`, `sentinel supply-chain`, `sentinel probe`, `sentinel discover`, `sentinel inspect --no-ai`
 
 ---
 

{agentsentinel_cli-0.7.0 → agentsentinel_cli-0.7.1}/agentsentinel_cli/mcp_client.py

@@ -1,7 +1,7 @@
 """Minimal MCP (Model Context Protocol) client for security scanning.
 
-Implements the initialize + tools/list exchange over stdio and streamable-HTTP
-transports. Only what an auditor needs — no full MCP client dependency.
+Implements the initialize + tools/list exchange over stdio, streamable-HTTP,
+and legacy SSE transports. Only what an auditor needs — no full MCP client dependency.
 """
 
 import dataclasses
@@ -10,6 +10,7 @@ import queue
 import shlex
 import subprocess
 import threading
+import urllib.parse
 from typing import Any
 
 from agentsentinel_cli.scanner import classify_tool
@@ -79,6 +80,9 @@ def scan_http(
 ) -> McpServerInfo:
     """Scan an MCP server via streamable HTTP (POST-based) transport.
 
+    If the server responds with 405 or text/event-stream, automatically falls
+    back to the legacy SSE transport (GET /sse + POST /messages).
+
     Raises McpAuthRequired if the server requires credentials.
     Raises McpError for all other connection or protocol failures.
     """
@@ -105,18 +109,12 @@ def scan_http(
         if resp.status_code in (401, 403):
             raise McpAuthRequired(resp.status_code)
         if resp.status_code == 405:
-            raise McpError(
-                "Server returned 405 Method Not Allowed. "
-                "This server may use the older SSE transport (GET /sse). "
-                "Try scanning it locally with: sentinel mcp scan --stdio 'python server.py'"
-            )
+            # Old SSE transport — fall back automatically
+            return scan_sse(url, extra_headers=extra_headers, timeout=timeout)
 
         content_type = resp.headers.get("content-type", "")
         if "text/event-stream" in content_type:
-            raise McpError(
-                "Server responded with SSE stream (older transport). "
-                "Try scanning it locally with: sentinel mcp scan --stdio 'python server.py'"
-            )
+            return scan_sse(url, extra_headers=extra_headers, timeout=timeout)
 
         resp.raise_for_status()
         init_data = _parse_rpc_response(resp.text)
@@ -143,6 +141,132 @@ def scan_http(
     )
 
 
+def scan_sse(
+    url: str,
+    extra_headers: dict[str, str] | None = None,
+    timeout: float = 15.0,
+) -> McpServerInfo:
+    """Scan an MCP server via the legacy SSE transport (GET /sse + POST /messages).
+
+    FastMCP 0.x / mcp 1.x servers use this transport. The protocol is:
+      1. Client opens GET /sse — server streams SSE events back.
+      2. First event is  event: endpoint / data: /messages/?session_id=xxx
+      3. Client POSTs JSON-RPC requests to /messages/?session_id=xxx.
+      4. Server sends responses as SSE  data:  events on the open GET stream.
+
+    We handle the bidirectional exchange with a background reader thread that
+    drains the SSE stream into a queue while the main thread sends requests.
+    """
+    try:
+        import httpx
+    except ImportError:
+        raise McpError("httpx is required: pip install 'agentsentinel-cli[mcp]'")
+
+    # Normalise: /sse suffix accepted but not required
+    base = url.rstrip("/")
+    if not base.endswith("/sse"):
+        base = f"{base}/sse"
+
+    parsed = urllib.parse.urlparse(base)
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+
+    sse_headers: dict[str, str] = {"Accept": "text/event-stream"}
+    if extra_headers:
+        sse_headers.update(extra_headers)
+
+    event_q: queue.Queue[str | None] = queue.Queue()
+    endpoint_q: queue.Queue[str | None] = queue.Queue(maxsize=1)
+
+    def _sse_reader(client: "httpx.Client") -> None:
+        """Stream GET /sse, push data-line payloads into event_q."""
+        try:
+            with client.stream("GET", base, headers=sse_headers) as resp:
+                if resp.status_code in (401, 403):
+                    endpoint_q.put(None)
+                    return
+                resp.raise_for_status()
+                endpoint_sent = False
+                for line in resp.iter_lines():
+                    if line.startswith("data:"):
+                        data = line[5:].strip()
+                        if not endpoint_sent:
+                            # First data line is the session endpoint path
+                            endpoint_q.put(data)
+                            endpoint_sent = True
+                        else:
+                            event_q.put(data)
+        except Exception:
+            endpoint_q.put(None)
+            event_q.put(None)
+
+    def _recv(wait: float) -> dict[str, Any]:
+        try:
+            payload = event_q.get(timeout=wait)
+        except queue.Empty:
+            raise McpError(f"No SSE response within {wait}s")
+        if payload is None:
+            raise McpError("SSE stream closed unexpectedly")
+        try:
+            return json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise McpError(f"Invalid JSON from SSE stream: {exc}") from exc
+
+    with httpx.Client(timeout=timeout) as client:
+        reader = threading.Thread(target=_sse_reader, args=(client,), daemon=True)
+        reader.start()
+
+        # Wait for the session endpoint URL
+        try:
+            session_path = endpoint_q.get(timeout=timeout)
+        except queue.Empty:
+            raise McpError("SSE server did not send an endpoint URL in time")
+        if session_path is None:
+            raise McpAuthRequired(401)
+
+        # Build the absolute messages URL
+        if session_path.startswith("http"):
+            messages_url = session_path
+        else:
+            messages_url = f"{origin}{session_path}"
+
+        post_headers: dict[str, str] = {"Content-Type": "application/json"}
+        if extra_headers:
+            post_headers.update(extra_headers)
+
+        # initialize
+        resp = client.post(messages_url, json=_rpc("initialize", {
+            "protocolVersion": _PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": _CLIENT_INFO,
+        }, 1), headers=post_headers)
+        if resp.status_code in (401, 403):
+            raise McpAuthRequired(resp.status_code)
+        resp.raise_for_status()
+        init_data = _recv(timeout)
+
+        # initialized notification — fire and forget
+        client.post(messages_url, json={
+            "jsonrpc": "2.0",
+            "method": "notifications/initialized",
+            "params": {},
+        }, headers=post_headers)
+
+        # tools/list
+        resp = client.post(messages_url, json=_rpc("tools/list", {}, 2), headers=post_headers)
+        resp.raise_for_status()
+        tools_data = _recv(timeout)
+
+    server_meta = init_data.get("result", {}).get("serverInfo", {})
+    raw_tools = tools_data.get("result", {}).get("tools", [])
+
+    return McpServerInfo(
+        name=server_meta.get("name", "unknown"),
+        version=server_meta.get("version", "unknown"),
+        tools=[_make_tool(t) for t in raw_tools],
+        transport="sse",
+    )
+
+
 def _parse_rpc_response(text: str) -> dict[str, Any]:
     """Parse a JSON-RPC response body, unwrapping SSE data-lines if present."""
     text = text.strip()

{agentsentinel_cli-0.7.0 → agentsentinel_cli-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentsentinel-cli"
-version = "0.7.0"
+version = "0.7.1"
 description = "Agentic security CLI — AI analyst with memory, supply chain audit, MCP audit, red-team probing, and agent discovery"
 readme = "README.md"
 requires-python = ">=3.10"

agentsentinel_cli-0.7.1/tmp/test-mcp-agent/README.md

@@ -0,0 +1,134 @@
+# LangChain Agent + MCP Server — Learning Example
+
+Two separate scripts. Run them in two separate terminals to see
+agent → MCP server communication in real time.
+
+```
+Terminal 1                          Terminal 2
+──────────────────────────────      ──────────────────────────────
+python mcp_server.py                python langchain_agent.py
+  ↑ shows [TOOL CALL] logs            ↑ LLM + agent loop
+  ↑ runs as HTTP server               ↑ connects over HTTP/SSE
+```
+
+---
+
+## Setup (do this once)
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+> To deactivate when done: `deactivate`
+
+---
+
+## How to run
+
+**Terminal 1 — start the MCP server:**
+
+```bash
+source venv/bin/activate
+python mcp_server.py
+```
+
+You'll see:
+```
+10:30:00  INFO    file-browser MCP server starting (SSE/HTTP transport)
+10:30:00  INFO    tools: list_directory, get_directory_tree
+10:30:00  INFO    listening on  http://127.0.0.1:8000/sse
+10:30:00  INFO    waiting for agent connection...
+```
+
+**Terminal 2 — run the agent:**
+
+```bash
+source venv/bin/activate
+python langchain_agent.py
+```
+
+Now ask the agent something:
+```
+You: list /Users/jaydenaung/code
+```
+
+**Watch Terminal 1** — you'll see every tool call the agent makes:
+```
+10:30:05  INFO    [TOOL CALL]  list_directory  path='/Users/jaydenaung/code'  show_hidden=False
+10:30:05  INFO    [TOOL DONE]  list_directory  → 42 lines
+```
+
+---
+
+## File 1: `mcp_server.py`
+
+Standalone HTTP/SSE server exposing two tools: `list_directory` and `get_directory_tree`.
+
+Logs every incoming tool call to stderr so you can watch agent→server traffic live.
+
+**Custom port:**
+```bash
+python mcp_server.py --port 9000
+# update MCP_SERVER_URL in langchain_agent.py to match
+```
+
+**Test in the MCP Inspector (browser UI):**
+```bash
+mcp dev mcp_server.py
+```
+
+**Connect to Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "file-browser": {
+      "command": "/absolute/path/to/venv/bin/python",
+      "args": ["/absolute/path/to/mcp_server.py"]
+    }
+  }
+}
+```
+Use the venv Python path so it picks up the `mcp` package. Restart Claude Desktop after saving.
+
+---
+
+## File 2: `langchain_agent.py`
+
+LangChain agent that connects to the running MCP server over HTTP/SSE.
+Does NOT spawn the server — the server must be running first.
+
+Uses `langchain.agents.create_agent` (the LangChain v1 replacement for the
+removed `AgentExecutor` + `create_tool_calling_agent` API).
+
+**Example prompts:**
+```
+> What's in my home directory?
+> List /Users/jaydenaung/code
+> Show me the tree of ~/Downloads
+```
+
+---
+
+## Key concepts
+
+### stdio vs HTTP/SSE transport
+
+| | stdio | HTTP/SSE (this example) |
+|---|---|---|
+| How server starts | Client spawns it as a subprocess | Runs independently, clients connect |
+| Terminals needed | 1 (server hidden inside agent) | 2 (server + agent separate) |
+| Multiple clients | No — one subprocess per client | Yes — any number of clients |
+| Claude Desktop | Yes (subprocess mode) | Yes (point to URL) |
+| Good for | Embedding tools into one script | Observing, sharing, scaling |
+
+### LangChain tool vs MCP server
+
+| | LangChain tool | MCP server |
+|---|---|---|
+| Scope | Only works inside your Python agent | Works with ANY MCP client |
+| Clients | Your script only | Claude Desktop, Cursor, Claude Code, etc. |
+| Transport | Direct Python function call | JSON-RPC over HTTP or stdio |
+| When to use | Building your own agent in code | Exposing tools to AI assistants generally |

agentsentinel_cli-0.7.1/tmp/test-mcp-agent/langchain_agent.py

@@ -0,0 +1,178 @@
+"""
+LangChain Agent — connects to a running MCP server over HTTP/SSE
+=================================================================
+The agent connects to mcp_server.py over HTTP — it does NOT spawn it.
+Start the server in one terminal first, then run this in another.
+
+HOW TO RUN (two separate terminals):
+    Terminal 1:  python mcp_server.py
+    Terminal 2:  python langchain_agent.py
+
+    The server terminal will show [TOOL CALL] / [TOOL DONE] logs for
+    every request the agent sends.
+
+WHAT THIS TEACHES:
+    - How an agent calls tools over MCP (HTTP/SSE transport)
+    - The full flow: LLM decides → MCP client sends request → server executes
+    - How the agent and server are truly decoupled processes
+
+NOTE (LangChain v1.x):
+    AgentExecutor and create_tool_calling_agent were removed in LangChain v1.
+    The modern API is langchain.agents.create_agent (backed by LangGraph).
+"""
+
+import asyncio
+import os
+import sys
+
+from dotenv import load_dotenv
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+load_dotenv()
+
+from langchain_anthropic import ChatAnthropic
+from langchain_core.tools import StructuredTool
+from langchain_core.messages import HumanMessage
+from langchain.agents import create_agent
+from pydantic import BaseModel, Field
+
+
+# ─────────────────────────────────────────────
+# Server URL — change port if you started mcp_server.py with --port
+# ─────────────────────────────────────────────
+
+MCP_SERVER_URL = "http://127.0.0.1:8000/sse"
+
+
+# ─────────────────────────────────────────────
+# STEP 1: Pydantic schemas — tell the LLM what arguments each tool takes
+# These mirror the inputSchema defined in mcp_server.py
+# ─────────────────────────────────────────────
+
+class ListDirectoryInput(BaseModel):
+    path: str = Field(description="Absolute path to the directory. Examples: /Users/jaydenaung/code, ~/Documents")
+    show_hidden: bool = Field(default=False, description="Include hidden files (starting with '.')")
+
+
+class GetDirectoryTreeInput(BaseModel):
+    path: str = Field(description="Absolute path to the root directory")
+    max_depth: int = Field(default=2, description="How many levels deep to recurse")
+
+
+# ─────────────────────────────────────────────
+# STEP 2: Wrap MCP tools as LangChain tools
+# Each async function forwards the call to the MCP server over the live session.
+# ─────────────────────────────────────────────
+
+def make_mcp_tools(session: ClientSession) -> list:
+    async def list_directory(path: str, show_hidden: bool = False) -> str:
+        result = await session.call_tool(
+            "list_directory", {"path": path, "show_hidden": show_hidden}
+        )
+        return "\n".join(b.text for b in result.content if hasattr(b, "text"))
+
+    async def get_directory_tree(path: str, max_depth: int = 2) -> str:
+        result = await session.call_tool(
+            "get_directory_tree", {"path": path, "max_depth": max_depth}
+        )
+        return "\n".join(b.text for b in result.content if hasattr(b, "text"))
+
+    return [
+        StructuredTool.from_function(
+            coroutine=list_directory,
+            name="list_directory",
+            description="List all files and folders in a directory. Returns names, types, and sizes.",
+            args_schema=ListDirectoryInput,
+        ),
+        StructuredTool.from_function(
+            coroutine=get_directory_tree,
+            name="get_directory_tree",
+            description="Get a recursive tree view of a directory up to a specified depth.",
+            args_schema=GetDirectoryTreeInput,
+        ),
+    ]
+
+
+# ─────────────────────────────────────────────
+# STEP 3: LLM setup
+# ─────────────────────────────────────────────
+
+llm = ChatAnthropic(model="claude-sonnet-4-6", temperature=0, max_tokens=4096)
+
+SYSTEM_PROMPT = (
+    "You are a helpful file system assistant running on macOS. "
+    "You have tools to list directories and get directory trees. "
+    "When a user asks about files or folders, use the appropriate tool. "
+    "Be concise and helpful."
+)
+
+
+# ─────────────────────────────────────────────
+# STEP 4: Connect to the MCP server and run the agent loop
+#
+# sse_client connects to the running HTTP server — it does NOT spawn a process.
+# The session stays open for the entire conversation so all tool calls
+# go through the same persistent connection.
+# ─────────────────────────────────────────────
+
+async def main():
+    print("\n" + "=" * 55)
+    print("  LangChain Agent — File System Assistant (MCP)")
+    print("  Type 'exit' to quit")
+    print("=" * 55)
+    print(f"\nConnecting to MCP server at {MCP_SERVER_URL} ...")
+    print("(Start mcp_server.py first if you haven't already)\n")
+
+    api_key = os.environ.get("MCP_API_KEY", "")
+    if not api_key:
+        print("Error: MCP_API_KEY is not set. Add it to .env or export it.")
+        sys.exit(1)
+
+    auth_headers = {"Authorization": f"Bearer {api_key}"}
+
+    try:
+        async with sse_client(MCP_SERVER_URL, headers=auth_headers) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+
+                tools = make_mcp_tools(session)
+                agent = create_agent(llm, tools, system_prompt=SYSTEM_PROMPT)
+
+                print(f"Connected! Tools: {[t.name for t in tools]}")
+                print("\nExample prompts:")
+                print("  > What's in my home directory?")
+                print("  > List /Users/jaydenaung/code")
+                print("  > Show me the tree of ~/Downloads")
+                print()
+
+                messages = []
+
+                while True:
+                    user_input = await asyncio.to_thread(input, "You: ")
+                    user_input = user_input.strip()
+
+                    if not user_input:
+                        continue
+                    if user_input.lower() in ("exit", "quit", "q"):
+                        print("Bye!")
+                        break
+
+                    messages.append(HumanMessage(content=user_input))
+                    result = await agent.ainvoke({"messages": messages})
+
+                    ai_message = result["messages"][-1]
+                    print(f"\nAgent: {ai_message.content}\n")
+                    messages = result["messages"]
+
+    except* Exception as eg:
+        for exc in eg.exceptions:
+            if "connection refused" in str(exc).lower() or "connect" in str(exc).lower():
+                print(f"\nError: could not connect to {MCP_SERVER_URL}")
+                print("Make sure mcp_server.py is running in another terminal.")
+                sys.exit(1)
+            raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentsentinel_cli-0.7.1/tmp/test-mcp-agent/mcp_server.py

@@ -0,0 +1,245 @@
+"""
+Simple MCP Server — Directory Lister
+=====================================
+Exposes two tools over HTTP/SSE: list_directory and get_directory_tree.
+
+Runs as a standalone HTTP server so ANY MCP client can connect to it —
+langchain_agent.py, Claude Desktop, Cursor, or the MCP inspector.
+
+HOW TO RUN:
+    source venv/bin/activate
+    python mcp_server.py              # starts on http://127.0.0.1:8000
+    python mcp_server.py --port 9000  # custom port
+
+HOW TO CONNECT:
+    - langchain_agent.py connects automatically (run it in a separate terminal)
+    - MCP inspector: mcp dev mcp_server.py
+    - Claude Desktop: see README for config
+
+WHAT THIS TEACHES:
+    - How an MCP server is structured with FastMCP
+    - How tools are defined (decorated functions — docstring = description)
+    - HTTP/SSE transport: the server is a proper long-running HTTP service,
+      not a subprocess spawned per-client like stdio mode
+    - The difference between MCP server vs LangChain tool:
+        LangChain tool = only works inside your Python agent
+        MCP server     = works with ANY MCP-compatible client
+"""
+
+import argparse
+import os
+import sys
+import logging
+
+import uvicorn
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from pathlib import Path
+
+load_dotenv()
+
+
+# ─────────────────────────────────────────────
+# Logging — stderr keeps it out of the HTTP response stream
+# ─────────────────────────────────────────────
+
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-7s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("file-browser")
+
+
+# ─────────────────────────────────────────────
+# Bearer token auth middleware (raw ASGI)
+#
+# BaseHTTPMiddleware buffers the full response before sending, which breaks
+# SSE streaming. Raw ASGI middleware passes the scope/receive/send directly
+# so SSE streams flow through without buffering.
+# ─────────────────────────────────────────────
+
+class BearerAuthMiddleware:
+    def __init__(self, app, token: str):
+        self.app = app
+        self._token = f"Bearer {token}".encode()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] in ("http", "websocket"):
+            headers = dict(scope.get("headers", []))
+            auth = headers.get(b"authorization", b"")
+            if auth != self._token:
+                log.warning(f"[AUTH] rejected connection from {scope.get('client', ('?', 0))[0]}")
+                if scope["type"] == "http":
+                    body = b'{"error":"Unauthorized: invalid or missing Bearer token"}'
+                    await send({"type": "http.response.start", "status": 401,
+                                "headers": [(b"content-type", b"application/json")]})
+                    await send({"type": "http.response.body", "body": body})
+                return
+            log.info(f"[AUTH] accepted connection from {scope.get('client', ('?', 0))[0]}")
+        await self.app(scope, receive, send)
+
+
+# ─────────────────────────────────────────────
+# STEP 1: Create the FastMCP server instance
+# ─────────────────────────────────────────────
+
+mcp = FastMCP("file-browser")
+
+
+# ─────────────────────────────────────────────
+# STEP 2: Define tools with @mcp.tool()
+# FastMCP reads the function signature for the input schema and
+# the docstring for the description — no manual schema required.
+# ─────────────────────────────────────────────
+
+@mcp.tool()
+def list_directory(path: str, show_hidden: bool = False) -> str:
+    """
+    List all files and folders in a given directory.
+    Returns names, types (file/folder), and sizes.
+    Use this to browse the local file system.
+
+    Args:
+        path: Absolute path to the directory. Examples: /Users/jaydenaung/code, ~/Documents
+        show_hidden: Whether to include hidden files (starting with '.'). Defaults to false.
+    """
+    log.info(f"[TOOL CALL]  list_directory  path={path!r}  show_hidden={show_hidden}")
+    result = handle_list_directory(path, show_hidden)
+    log.info(f"[TOOL DONE]  list_directory  → {result.count(chr(10)) + 1} lines")
+    return result
+
+
+@mcp.tool()
+def get_directory_tree(path: str, max_depth: int = 2) -> str:
+    """
+    Get a recursive tree view of a directory up to a specified depth.
+    Useful for understanding a project's folder structure at a glance.
+
+    Args:
+        path: Absolute path to the root directory.
+        max_depth: How many levels deep to recurse. Default is 2.
+    """
+    log.info(f"[TOOL CALL]  get_directory_tree  path={path!r}  max_depth={max_depth}")
+    result = handle_directory_tree(path, max_depth)
+    log.info(f"[TOOL DONE]  get_directory_tree  → {result.count(chr(10)) + 1} lines")
+    return result
+
+
+# ─────────────────────────────────────────────
+# STEP 3: Business logic (pure Python, no MCP dependency)
+# ─────────────────────────────────────────────
+
+def handle_list_directory(path: str, show_hidden: bool = False) -> str:
+    try:
+        expanded = os.path.expanduser(path)
+        dir_path = Path(expanded)
+
+        if not dir_path.exists():
+            return f"❌ Path does not exist: {expanded}"
+        if not dir_path.is_dir():
+            return f"❌ Not a directory: {expanded}"
+
+        entries = sorted(dir_path.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        if not show_hidden:
+            entries = [e for e in entries if not e.name.startswith(".")]
+        if not entries:
+            return f"Directory is empty: {expanded}"
+
+        lines = [f"📂 {expanded}\n", f"{'Name':<40} {'Type':<8} {'Size':>10}", "-" * 62]
+        for entry in entries:
+            try:
+                if entry.is_dir():
+                    lines.append(f"📁 {entry.name:<38} {'folder':<8} {'':>10}")
+                else:
+                    size_str = format_size(entry.stat().st_size)
+                    lines.append(f"📄 {entry.name:<38} {'file':<8} {size_str:>10}")
+            except PermissionError:
+                lines.append(f"🔒 {entry.name:<38} (permission denied)")
+
+        lines.append(f"\nTotal: {len(entries)} item(s)")
+        return "\n".join(lines)
+
+    except PermissionError:
+        return f"❌ Permission denied: {path}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def handle_directory_tree(path: str, max_depth: int = 2) -> str:
+    try:
+        expanded = os.path.expanduser(path)
+        root = Path(expanded)
+
+        if not root.exists():
+            return f"❌ Path does not exist: {expanded}"
+        if not root.is_dir():
+            return f"❌ Not a directory: {expanded}"
+
+        lines = [f"📂 {root.name}/"]
+        _build_tree(root, lines, prefix="", depth=0, max_depth=max_depth)
+        lines.append(f"\n(max depth: {max_depth})")
+        return "\n".join(lines)
+
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def _build_tree(directory: Path, lines: list, prefix: str, depth: int, max_depth: int):
+    if depth >= max_depth:
+        return
+    try:
+        entries = sorted(directory.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        entries = [e for e in entries if not e.name.startswith(".")]
+    except PermissionError:
+        lines.append(f"{prefix}└── 🔒 (permission denied)")
+        return
+
+    for i, entry in enumerate(entries):
+        is_last = (i == len(entries) - 1)
+        connector = "└── " if is_last else "├── "
+        icon = "📁" if entry.is_dir() else "📄"
+        lines.append(f"{prefix}{connector}{icon} {entry.name}")
+        if entry.is_dir():
+            extension = "    " if is_last else "│   "
+            _build_tree(entry, lines, prefix + extension, depth + 1, max_depth)
+
+
+def format_size(size_bytes: int) -> str:
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.0f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"
+
+
+# ─────────────────────────────────────────────
+# STEP 4: Run as a standalone HTTP/SSE server
+#
+# SSE transport = the server is a real HTTP service.
+# Any MCP client connects to http://host:port/sse — no subprocess spawning.
+# This is what lets you run the server and agent in two separate terminals.
+# ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="file-browser MCP server")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+
+    api_key = os.environ.get("MCP_API_KEY", "")
+    if not api_key:
+        log.error("MCP_API_KEY is not set — refusing to start without auth.")
+        log.error("Set it in .env or export MCP_API_KEY=<secret>")
+        sys.exit(1)
+
+    log.info("file-browser MCP server starting (SSE/HTTP transport)")
+    log.info("tools: list_directory, get_directory_tree")
+    log.info(f"listening on  http://{args.host}:{args.port}/sse  [auth: Bearer token]")
+    log.info("waiting for agent connection...")
+
+    # Wrap the Starlette SSE app with bearer token auth before handing to uvicorn.
+    # Using raw ASGI (not mcp.run) so we control the middleware stack.
+    app = BearerAuthMiddleware(mcp.sse_app(), token=api_key)
+    uvicorn.run(app, host=args.host, port=args.port, log_level="warning")

agentsentinel_cli-0.7.1/tmp/test-mcp-agent/requirements.txt

@@ -0,0 +1,16 @@
+# LangChain Agent + MCP Server
+# Python 3.11+ recommended
+
+# LangChain core
+langchain>=0.3.0
+langchain-core>=0.3.0
+langchain-anthropic>=0.3.0
+
+# MCP server + inspector (cli extras required for mcp dev)
+mcp[cli]>=1.0.0
+
+# Anthropic SDK (pulled in by langchain-anthropic, pinned for safety)
+anthropic>=0.40.0
+
+# Env file loading
+python-dotenv>=1.0.0