docs: complete GitHub README and MCP runtime displays

Author: try1004

README.md

@@ -10,7 +10,7 @@ English | [中文](./README_zh.md)
 
 ![FlowLens AgentOps dashboard](./docs/assets/flowlens-agentops-dashboard.png)
 
-[Pages Demo](https://try1004.github.io/FlowLens-AgentOps/) | [Quick Start](#quick-start) | [Architecture](./docs/architecture.md) | [Dual MCP Validation](./docs/mcp-validation-guide.md)
+[Pages Demo](https://try1004.github.io/FlowLens-AgentOps/) | [Quick Start](#quick-start) | [Architecture](./docs/architecture.md) | [Dual MCP Validation](./docs/mcp-validation-guide.md) | [Maintainer Handoff](./now.md)
 
 > Built on [DeerFlow 2.0](https://github.com/bytedance/deer-flow) under the MIT License. DeerFlow provides the Agent runtime, tools, subagents, memory, MCP, sandbox, and application foundation. FlowLens adds the diagnostics and AgentOps product layer described below.
 
@@ -45,6 +45,14 @@ The diagnostics path is read-only: it does not mutate checkpoints, prompts, RunR
 
 ## Quick Start
 
+### Choose a mode
+
+| Mode | What it proves | Requirements | URL |
+| --- | --- | --- | --- |
+| Replay | Dashboard interactions and deterministic synthetic failure scenarios | Node.js or Docker; no model key | `http://localhost:5173` or `http://localhost:4173` |
+| Connected Runtime | Real DeerFlow runs emitted into the AgentOps event pipeline | Normal DeerFlow configuration, account, and model provider | `http://localhost:2026/agentops` |
+| Connected + dual MCP | Runtime delegation, read-only SQLite Analytics MCP, and FlowLens Inspector MCP | Docker Desktop plus the Connected Runtime requirements | `http://localhost:2027/agentops` |
+
 ### No-key Replay with pnpm
 
 ```bash
@@ -67,6 +75,14 @@ make flowlens-demo
 
 Open `http://localhost:4173`, then stop it with `make flowlens-stop`.
 
+On Windows without `make`, run the Compose command directly:
+
+```powershell
+docker compose -f docker/docker-compose-flowlens-demo.yaml up --build
+```
+
+Press `Ctrl+C` to stop the foreground Replay container.
+
 ### Connected DeerFlow runtime
 
 ```bash
@@ -78,11 +94,36 @@ Open `http://localhost:2026/agentops`. Connected mode requires the normal DeerFl
 
 ### Connected runtime with dual MCP services
 
-The development compose stack can run two internal Streamable HTTP MCP services.
-They use a discovery-only service token for schema loading and a short user/run-bound
-delegated token for each tool call. The full isolated Docker command and validation
-prompts are in the [Dual MCP Validation Guide](./docs/mcp-validation-guide.md)
-and the [Chinese end-to-end test runbook](./docs/flowlens-dual-mcp-test-runbook.zh-CN.md).
+The development stack runs two internal-only Streamable HTTP MCP services:
+
+- **SQLite Analytics MCP** exposes schema inspection and `SELECT`-only local demonstration-data queries.
+- **FlowLens Inspector MCP** queries owner-checked diagnostic data through the Gateway.
+
+Schemas are discovered with a restricted service token. A real tool invocation receives a short-lived token bound to the current `user_id` and `run_id`; the model never receives that token.
+
+From the repository root in PowerShell:
+
+```powershell
+$env:DEER_FLOW_ROOT = (Get-Location).Path
+$env:HOME = $env:USERPROFILE
+$env:DEER_FLOW_CONTAINER_PREFIX = "flowlens-agentops"
+$env:DEER_FLOW_HTTP_PORT = "2027"
+
+docker compose -p flowlens-agentops `
+  -f docker/docker-compose-dev.yaml `
+  -f docker/docker-compose-agentops-isolated.yaml `
+  up -d --build --remove-orphans frontend gateway nginx sqlite-analytics flowlens-inspector
+
+Invoke-RestMethod http://localhost:2027/health
+```
+
+Open `http://localhost:2027/`, sign in, then open `http://localhost:2027/agentops`. To exercise the real SQLite path, start a new chat and send:
+
+```text
+Use the SQLite Analytics MCP to inspect the available schema, describe the agent_runs table, then count runs by status. Execute read-only SQL only, state the SQL used, and label the result as local demonstration data.
+```
+
+The selected Run should show MCP events in Timeline and an `MCP > 0` metric. The [Dual MCP Validation Guide](./docs/mcp-validation-guide.md) and [Chinese end-to-end runbook](./docs/flowlens-dual-mcp-test-runbook.zh-CN.md) cover expected evidence, policy-rejection cases, and shutdown.
 
 ## Diagnostic APIs
 
@@ -134,8 +175,10 @@ FlowLens does not claim authorship of the DeerFlow runtime modules. See [NOTICE]
 
 | Gate                               | Result                                                             |
 | ---------------------------------- | ------------------------------------------------------------------ |
-| Focused backend FlowLens/API suite | 53 tests passed                                                    |
-| Frontend Vitest suite              | 219 tests passed                                                   |
+| Focused backend FlowLens/API suite | 58 tests passed on 2026-07-31                                     |
+| Frontend Vitest suite              | 232 tests passed on 2026-07-31                                    |
+| Frontend quality gate              | ESLint, TypeScript, Next production build, and Vite Replay build passed on 2026-07-31 |
+| Real MCP integration probe         | `ToolNode -> delegated OAuth token -> SQLite schema tool` completed locally |
 | Next and static Replay Playwright  | 5 tests passed across route, desktop, tablet, and mobile workflows |
 | Secret scan                        | No high-confidence credentials in Git-tracked files                |
 | In-process diagnostics benchmark   | 2,000 events, 20 iterations, median 24.7578 ms, P95 36.5606 ms     |
@@ -165,6 +208,8 @@ The machine-readable result is committed at [flowlens-benchmark.json](./docs/ass
 - [Failure attribution rules](./docs/failure-attribution.md)
 - [Replay and Connected demo guide](./docs/demo-guide.md)
 - [Dual MCP validation guide](./docs/mcp-validation-guide.md)
+- [Chinese dual MCP end-to-end runbook](./docs/flowlens-dual-mcp-test-runbook.zh-CN.md)
+- [Maintainer handoff and next steps](./now.md)
 - [Contributing](./CONTRIBUTING.md)
 - [Changelog](./CHANGELOG.md)
 

frontend/src/components/agentops/event-detail-sheet.tsx

@@ -9,6 +9,17 @@ function metadataValue(value: unknown): string {
   return JSON.stringify(value);
 }
 
+function metadataString(
+  metadata: TimelineItem["metadata"],
+  keys: string[],
+): string | null {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return null;
+}
+
 export function EventDetailSheet({
   item,
   onClose,
@@ -23,6 +34,12 @@ export function EventDetailSheet({
   }, [item?.seq]);
 
   if (!item) return null;
+  const isMcp = item.phase === "mcp";
+  const mcpServer = isMcp
+    ? (metadataString(item.metadata, ["server_name", "server", "mcp_server"]) ??
+      "Not reported")
+    : null;
+
   return (
     <div
       className="fixed inset-0 z-50 flex justify-end bg-black/25"
@@ -55,7 +72,9 @@ export function EventDetailSheet({
           <dl className="grid grid-cols-[7rem_1fr] gap-x-3 gap-y-3">
             <dt className="agentops-muted">Phase</dt>
             <dd className="capitalize">{item.phase}</dd>
-            <dt className="agentops-muted">Component</dt>
+            <dt className="agentops-muted">
+              {isMcp ? "MCP tool" : "Component"}
+            </dt>
             <dd className="break-words">{item.component}</dd>
             <dt className="agentops-muted">Status</dt>
             <dd className="capitalize">{item.status}</dd>
@@ -73,6 +92,20 @@ export function EventDetailSheet({
             </dd>
           </dl>
 
+          {isMcp ? (
+            <div className="agentops-divider border-y py-4">
+              <h3 className="agentops-eyebrow">MCP context</h3>
+              <dl className="mt-3 grid grid-cols-[7rem_1fr] gap-x-3 gap-y-3">
+                <dt className="agentops-muted">Server</dt>
+                <dd className="font-mono text-xs break-all">{mcpServer}</dd>
+                <dt className="agentops-muted">Tool lifecycle</dt>
+                <dd className="font-mono text-xs break-all">
+                  {item.event_type}
+                </dd>
+              </dl>
+            </div>
+          ) : null}
+
           <div>
             <h3 className="agentops-eyebrow">Summary</h3>
             <p className="mt-2 leading-6">{item.summary}</p>

frontend/src/components/agentops/metrics-strip.tsx

@@ -1,5 +1,12 @@
 import type { RunMetrics, TimelineItem } from "@/core/agentops/types";
 
+type MetricCell = {
+  label: string;
+  value: string;
+  detail?: string;
+  detailClassName?: string;
+};
+
 function durationLabel(durationMs: number | null): string {
   if (durationMs === null) return "--";
   if (durationMs < 1000) return `${durationMs} ms`;
@@ -14,28 +21,37 @@ export function MetricsStrip({
   timeline: TimelineItem[];
 }) {
   const mcpEvents = timeline.filter((item) => item.phase === "mcp").length;
+  const mcpIncidents = timeline.filter(
+    (item) => item.phase === "mcp" && item.status === "error",
+  ).length;
   const memoryEvents = timeline.filter(
     (item) => item.phase === "memory",
   ).length;
-  const cells = [
-    ["Duration", durationLabel(metrics.duration_ms)],
-    ["Tokens", metrics.total_tokens.toLocaleString()],
-    [
-      "Tools / Errors",
-      `${metrics.tool_call_count} / ${metrics.tool_error_count}`,
-    ],
-    [
-      "Subagents",
-      `${metrics.subagent_count} / ${metrics.subagent_error_count}`,
-    ],
-    ["MCP", String(mcpEvents)],
-    ["Memory", String(memoryEvents)],
-    ["Status", metrics.final_status],
+  const cells: MetricCell[] = [
+    { label: "Duration", value: durationLabel(metrics.duration_ms) },
+    { label: "Tokens", value: metrics.total_tokens.toLocaleString() },
+    {
+      label: "Tools / Errors",
+      value: `${metrics.tool_call_count} / ${metrics.tool_error_count}`,
+    },
+    {
+      label: "Subagents",
+      value: `${metrics.subagent_count} / ${metrics.subagent_error_count}`,
+    },
+    {
+      label: "MCP",
+      value: mcpEvents === 1 ? "1 event" : `${mcpEvents} events`,
+      detail: mcpIncidents > 0 ? `${mcpIncidents} incident` : undefined,
+      detailClassName:
+        mcpIncidents > 0 ? "agentops-metric-danger" : undefined,
+    },
+    { label: "Memory", value: String(memoryEvents) },
+    { label: "Status", value: metrics.final_status },
   ];
 
   return (
     <dl className="agentops-metrics grid min-h-20 grid-cols-2 border-b sm:grid-cols-4 xl:grid-cols-7">
-      {cells.map(([label, value]) => (
+      {cells.map(({ label, value, detail, detailClassName }) => (
         <div
           key={label}
           className="agentops-metric-cell flex min-w-28 flex-col justify-center border-r border-b px-5 py-3.5 last:border-r-0 sm:border-b-0"
@@ -46,6 +62,13 @@ export function MetricsStrip({
           <dd className="mt-1 truncate text-[15px] font-semibold capitalize tabular-nums">
             {value}
           </dd>
+          {detail ? (
+            <p
+              className={`mt-0.5 truncate text-[10px] font-medium ${detailClassName ?? "agentops-muted"}`}
+            >
+              {detail}
+            </p>
+          ) : null}
         </div>
       ))}
     </dl>

frontend/tests/unit/components/event-detail-sheet.test.tsx

@@ -34,4 +34,28 @@ describe("EventDetailSheet", () => {
     expect(disclosure).toHaveAttribute("aria-expanded", "true");
     expect(screen.getByText("tool_name")).toBeVisible();
   });
+
+  test("summarizes MCP service and tool context before raw metadata", () => {
+    render(
+      <EventDetailSheet
+        item={{
+          ...item,
+          phase: "mcp",
+          event_type: "mcp.tool.end",
+          component: "sqlite_analytics_query_readonly",
+          metadata: {
+            server_name: "sqlite-analytics",
+            tool_name: "sqlite_analytics_query_readonly",
+          },
+        }}
+        onClose={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("MCP context")).toBeVisible();
+    expect(screen.getByText("MCP tool")).toBeVisible();
+    expect(screen.getByText("sqlite-analytics")).toBeVisible();
+    expect(screen.getByText("Tool lifecycle")).toBeVisible();
+    expect(screen.getAllByText("mcp.tool.end")).toHaveLength(2);
+  });
 });

frontend/tests/unit/components/metrics-strip.test.tsx

@@ -0,0 +1,64 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+
+import { MetricsStrip } from "@/components/agentops/metrics-strip";
+import type { RunMetrics, TimelineItem } from "@/core/agentops/types";
+
+const metrics: RunMetrics = {
+  duration_ms: 2400,
+  total_events: 4,
+  total_tokens: 1200,
+  tool_calls: 0,
+  errors: 1,
+  tool_call_count: 0,
+  tool_error_count: 0,
+  subagent_count: 0,
+  subagent_error_count: 0,
+  rollback_performed: false,
+  final_status: "success",
+  failure_category: "MCP_TOOL_ERROR",
+  data_completeness: "complete",
+  first_event_latency_ms: 15,
+};
+
+const mcpTimeline: TimelineItem[] = [
+  {
+    seq: 1,
+    timestamp: "2026-07-31T10:00:00.000Z",
+    phase: "mcp",
+    event_type: "mcp.tool.start",
+    component: "sqlite_analytics_schema_overview",
+    status: "running",
+    summary: "SQLite Analytics tool started",
+    duration_ms: null,
+    span_id: "mcp-span",
+    parent_span_id: "agent-span",
+    malformed: false,
+    metadata: {},
+  },
+  {
+    seq: 2,
+    timestamp: "2026-07-31T10:00:01.000Z",
+    phase: "mcp",
+    event_type: "mcp.tool.error",
+    component: "sqlite_analytics_schema_overview",
+    status: "error",
+    summary: "SQLite Analytics tool rejected the query",
+    duration_ms: 12,
+    span_id: "mcp-span",
+    parent_span_id: "agent-span",
+    malformed: false,
+    metadata: {},
+  },
+];
+
+describe("MetricsStrip", () => {
+  test("surfaces MCP activity and incidents separately", () => {
+    render(<MetricsStrip metrics={metrics} timeline={mcpTimeline} />);
+
+    expect(screen.getByText("2 events")).toBeVisible();
+    expect(screen.getByText("1 incident")).toHaveClass(
+      "agentops-metric-danger",
+    );
+  });
+});