Let an AI agent see the open editor through MCP (#429)

Claude Code should be able to work inside the user's open editor tab.
This first stage connects the two and lets the agent look: what the
user sees and a picture of it. Changing the project comes in stage 2.

- An agent token per account opens only /mcp, no API route. The
  dialog "Agent tokens..." in the account menu creates it once, shows
  the ready "claude mcp add" line and revokes it. The server keeps
  only its sha256 (api/lib/AgentTokens.php).
- Wrong tokens count into the sign-in brake from #427. Changing the
  password, renaming or deleting an account ends its tokens.
- The relay (tools/mcp/) is a small Node service without packages,
  WebSocket server included. It runs in the container feuerwerk-mcp
  because PHP-FPM cannot hold connections. Whether a token or a tab
  ticket is valid is still decided by the PHP API, through two routes
  that answer only with the relay key.
- The tab joins over WebSocket on the same origin with the normal
  session, an Origin check and a one-time ticket. It connects only
  after "Agent" is switched on in the account menu. One tab per
  account is active, a new one takes over. Guests get nothing.
- Tools: get_view (project, tab, document, selection with names,
  camera, play state, open dialog) and screenshot. The resource
  feuerwerk://view can be subscribed. Claude Code does not act on
  that reliably, so a changed view is also noted on the next answer.
- A badge next to the account menu shows the connected agents. It
  counts only agents with an open stream or a request in the last
  two minutes.
- CI starts the relay in front of php -S (tools/ci/serve.sh), and
  e2e 71 runs the whole path in the browser.

Found on the live test: the badge showed four agents because old
sessions of revoked tokens were still counted.

Tests:
- Gate on atx: 316 files, 4888 tests
- relay protocol test with fake API and fake tabs: 23/23
- get_view, tools, socketUrl: 16/16
- PHP agents 29, rights 103 checks
- e2e 71 on atx 10/10, against the live site 10/10, no CSP violation
- real Claude Code against the live site: get_view answered
- ZAP against /mcp: nothing at High or Medium
- every new check fails when the guard it covers is taken out (6)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/editor/agent/agentTools.ts

@@ -0,0 +1,53 @@
+import type { AgentView } from './agentView';
+
+/** What a tool answers, as the relay hands it on to the agent (MCP's `CallToolResult`). */
+export interface ToolResult {
+  content: ({ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string })[];
+  isError?: boolean;
+  structuredContent?: object;
+}
+
+/** What the tools need of the editor. */
+export interface ToolHost {
+  view(): AgentView;
+  /** The editor as drawn, as a base64 PNG at most `maxWidth` pixels wide. */
+  screenshot(maxWidth: number): Promise<{ data: string; width: number; height: number }>;
+}
+
+const DEFAULT_SCREENSHOT_WIDTH = 1280;
+
+export function failure(text: string): ToolResult {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+/**
+ * Runs one of the tools of `tools.json` (#429). The relay has checked the name against the same
+ * list; the arguments are checked here, where their meaning is known.
+ */
+export async function runTool(
+  name: string,
+  args: Record<string, unknown>,
+  host: ToolHost,
+): Promise<ToolResult> {
+  switch (name) {
+    case 'get_view': {
+      const view = host.view();
+      return { content: [{ type: 'text', text: JSON.stringify(view) }], structuredContent: view };
+    }
+    case 'screenshot': {
+      const maxWidth = args.maxWidth ?? DEFAULT_SCREENSHOT_WIDTH;
+      if (typeof maxWidth !== 'number' || !Number.isInteger(maxWidth) || maxWidth < 320 || maxWidth > 3840) {
+        return failure('maxWidth has to be a whole number from 320 to 3840');
+      }
+      const shot = await host.screenshot(maxWidth);
+      return {
+        content: [
+          { type: 'image', data: shot.data, mimeType: 'image/png' },
+          { type: 'text', text: `The editor as the user sees it, ${shot.width}x${shot.height} pixels.` },
+        ],
+      };
+    }
+    default:
+      return failure(`This editor has no tool ${name}; reload it to get the newest.`);
+  }
+}