repoburg 1.3.254 → 1.3.256

package/daemon/dist/tabtape/mcp/server.js

@@ -0,0 +1,411 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TabtapeMcp = exports.INSTRUCTIONS = void 0;
+/**
+ * Exposes recorded sessions to Claude Code (and other MCP clients) over MCP
+ * Streamable HTTP at /tabtape/mcp. Every tool is read-only.
+ *
+ * The server is stateless: each HTTP request gets a fresh SDK Server and
+ * transport, answers with plain JSON, and lists sessions as they are at that
+ * moment. Before a message reaches the SDK, requests go through the checks
+ * of the Go server and of the Go SDK's stateless handler (go-sdk v1.8.0), so
+ * HTTP-level answers match the Go server's.
+ */
+const crypto_1 = __importDefault(require("crypto"));
+const net_1 = __importDefault(require("net"));
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const errors_1 = require("../errors");
+const log_1 = require("../log");
+const definitions_1 = require("./definitions");
+const gofmt_1 = require("./gofmt");
+const tools_1 = require("./tools");
+exports.INSTRUCTIONS = `tabtape records browser sessions locally: DOM replay, clicks, page views, form changes, network requests, console output, the app's own events (tabtape.track) and user id (tabtape.identify), Web Vitals and long freezes, and Redux / Zustand store actions.
+Use these tools to answer questions about what happened in a recording. Times are offsets from the start of the replay (mm:ss.mmm).
+Every session and line carries a replay link; include the relevant links in answers so the user can watch the moment.
+Start with list_sessions or get_session_summary (session_id "latest" is the most recent recording), then drill down with get_network, get_request, get_console and get_context_at.
+Request and response bodies are only returned by get_request or with include_bodies=true. Sensitive headers are shown as [redacted].
+Recordings made in deep mode also have the real request headers and cookies, the timing split, why a request failed (CORS, blocked cookies, mixed content) and WebSocket connections: get_network with kind=websocket lists them, get_request on a connection pages its messages.
+get_context_at ends with the last store actions before the moment and the state paths they changed.
+To record a browser you drive yourself (Playwright MCP, a Playwright script), get_record_link returns links that start and stop a recording in it; open the start link before the check and the stop link after it.`;
+const RESOURCE_PREFIX = 'tabtape://session/';
+const SESSION_TEMPLATE = {
+    name: 'session',
+    title: 'tabtape recording',
+    description: 'Summary of a recorded session: pages, clicks, changes, errors and failed requests with replay links.',
+    mimeType: 'text/markdown',
+    uriTemplate: 'tabtape://session/{id}',
+};
+const DEBUG_PROMPT = {
+    name: 'debug_latest',
+    title: 'Debug the latest tabtape recording',
+    description: 'Find the first error in the most recent recording, what the user did before it, and the likely root cause.',
+};
+const DEBUG_TEXT = `Debug my latest tabtape recording.
+
+1. Call get_session_summary with session_id "latest" to see what happened.
+2. Look at failed requests (get_network with status "failed" and include_bodies true) and console errors (get_console with level "error").
+3. For the first error, call get_context_at with its id to see what the user did right before it.
+4. Explain the most likely root cause in a few sentences, quote the evidence (request, response body, error message) and include the replay links of the key moments.
+If the recording has no errors, say so and describe what the user did.`;
+/** Page size of list results, as in the Go SDK. */
+const PAGE_SIZE = 1000;
+/** The Go SDK's limit on a request body. */
+const MAX_BODY_BYTES = 4 << 20;
+/** JSON-RPC invalid params; the Go SDK also uses it for unknown resources (SEP-2164). */
+const INVALID_PARAMS = -32602;
+/** An error the SDK sends as is: code, message and data. */
+class RpcError extends Error {
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'RpcError';
+    }
+}
+const resourceNotFound = (uri) => new RpcError(INVALID_PARAMS, 'Resource not found', { uri });
+class TabtapeMcp {
+    constructor(st, rd, opts) {
+        this.st = st;
+        this.opts = opts;
+        this.log = opts.logger ?? (0, log_1.consoleLogger)();
+        this.tools = new tools_1.Tools(st, rd, {
+            baseURL: opts.baseURL,
+            redact: opts.redact,
+            showSecrets: opts.showSecrets,
+            recordToken: opts.recordToken,
+            timeZone: opts.timeZone,
+            now: opts.now ?? Date.now,
+        });
+    }
+    /**
+     * Serves one MCP Streamable HTTP request (POST/GET/DELETE). The request
+     * body has NOT been read or parsed. Browser requests (they carry Origin)
+     * are rejected, and the optional token is checked, before anything else.
+     * Resolves once the response is sent.
+     */
+    async handle(req, res) {
+        try {
+            if (header(req, 'origin') !== '') {
+                textError(res, 403, 'browser requests are not allowed');
+                return;
+            }
+            if (this.opts.token !== '' && !this.authorized(req)) {
+                res.setHeader('WWW-Authenticate', 'Bearer realm="tabtape"');
+                textError(res, 401, 'missing or wrong bearer token');
+                return;
+            }
+            const body = await this.admit(req, res);
+            if (body === undefined)
+                return;
+            await this.serve(req, res, body);
+        }
+        catch (err) {
+            this.log.error('mcp request failed', { err });
+            if (!res.headersSent)
+                textError(res, 500, 'internal server error');
+            else
+                res.end();
+        }
+    }
+    authorized(req) {
+        const auth = header(req, 'authorization');
+        if (!auth.startsWith('Bearer '))
+            return false;
+        const got = Buffer.from(auth.slice('Bearer '.length));
+        const want = Buffer.from(this.opts.token);
+        return got.length === want.length && crypto_1.default.timingSafeEqual(got, want);
+    }
+    /**
+     * The Go SDK's stateless handler up to the first message: it answers
+     * everything but a well-formed POST, and returns that POST's parsed body.
+     */
+    async admit(req, res) {
+        // DNS rebinding protection for a server on a loopback address.
+        const host = header(req, 'host');
+        if (isLoopback(req.socket.localAddress ?? '') && !isLoopback(host)) {
+            textError(res, 403, `Forbidden: invalid Host header ${(0, gofmt_1.goQuote)(host)}`);
+            return undefined;
+        }
+        const version = header(req, 'mcp-protocol-version');
+        if (version !== '' && !types_js_1.SUPPORTED_PROTOCOL_VERSIONS.includes(version) && version < '2026-07-28') {
+            textError(res, 400, `Bad Request: Unsupported protocol version (supported versions: ${types_js_1.SUPPORTED_PROTOCOL_VERSIONS.join(',')})`);
+            return undefined;
+        }
+        // Stateless: there is no session to stream to (GET) or to end (DELETE).
+        if (req.method !== 'POST') {
+            res.setHeader('Allow', 'POST');
+            textError(res, 405, 'Method Not Allowed');
+            return undefined;
+        }
+        if (baseMediaType(header(req, 'content-type')) !== 'application/json') {
+            textError(res, 415, "Content-Type must be 'application/json'");
+            return undefined;
+        }
+        if (!acceptsJSONAndStream(header(req, 'accept'))) {
+            textError(res, 400, "Accept must contain both 'application/json' and 'text/event-stream'");
+            return undefined;
+        }
+        let raw;
+        try {
+            raw = await readBody(req, MAX_BODY_BYTES);
+        }
+        catch (err) {
+            textError(res, 400, `failed to read body: ${(0, errors_1.errorMessage)(err)}`);
+            return undefined;
+        }
+        if (raw === null) {
+            res.setHeader('Connection', 'close');
+            textError(res, 413, `request body exceeds ${MAX_BODY_BYTES} bytes`);
+            return undefined;
+        }
+        if (req.headers['last-event-id'] !== undefined) {
+            textError(res, 400, "can't send Last-Event-ID for POST request");
+            return undefined;
+        }
+        if (raw.length === 0) {
+            textError(res, 400, 'POST requires a non-empty body');
+            return undefined;
+        }
+        let body;
+        try {
+            body = JSON.parse(raw.toString('utf8'));
+        }
+        catch (err) {
+            textError(res, 400, `malformed payload: ${(0, errors_1.errorMessage)(err)}`);
+            return undefined;
+        }
+        if (Array.isArray(body)) {
+            if (body.length === 0) {
+                textError(res, 400, 'malformed payload: empty batch');
+                return undefined;
+            }
+            const v = version || '2025-03-26';
+            if (v >= '2025-06-18') {
+                textError(res, 400, `JSON-RPC batching is not supported in 2025-06-18 and later (request version: ${v})`);
+                return undefined;
+            }
+        }
+        // The SDK transport checks these headers again, without wildcards or parameters.
+        req.headers.accept = 'application/json, text/event-stream';
+        req.headers['content-type'] = 'application/json';
+        return body;
+    }
+    /** Answers one POST with a fresh server and transport. */
+    async serve(req, res, body) {
+        const server = this.newServer();
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+            await responseDone(res); // handleRequest returns before the handlers answer
+        }
+        finally {
+            await server.close().catch(() => undefined);
+        }
+    }
+    newServer() {
+        const server = new index_js_1.Server({ name: 'tabtape', title: 'tabtape session recorder', version: this.opts.version }, {
+            capabilities: { tools: { listChanged: true }, resources: { listChanged: true }, prompts: { listChanged: true } },
+            instructions: exports.INSTRUCTIONS,
+        });
+        // Invalid messages and clients that went away; the client gets its answer.
+        server.onerror = (err) => this.log.debug('mcp', { err });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: definitions_1.TOOL_LIST }));
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            if (!(0, definitions_1.hasTool)(name))
+                throw new RpcError(INVALID_PARAMS, `unknown tool ${(0, gofmt_1.goQuote)(name)}`);
+            return (0, definitions_1.callTool)(this.tools, name, args);
+        });
+        server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async (request) => this.listResources(request.params?.cursor));
+        server.setRequestHandler(types_js_1.ListResourceTemplatesRequestSchema, async () => ({ resourceTemplates: [SESSION_TEMPLATE] }));
+        server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => this.readResource(request.params.uri));
+        server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => ({ prompts: [DEBUG_PROMPT] }));
+        server.setRequestHandler(types_js_1.GetPromptRequestSchema, async (request) => this.getPrompt(request.params.name));
+        return server;
+    }
+    /** Every session as a resource, so Claude Code can offer them for @-mentions; by URI, in pages. */
+    listResources(cursor) {
+        const all = this.st.list().map((sess) => ({
+            uri: RESOURCE_PREFIX + sess.id,
+            name: sess.id,
+            title: this.tools.resourceTitle(sess),
+            description: 'tabtape recording of ' + (sess.url || sess.id),
+            mimeType: 'text/markdown',
+        }));
+        all.sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+        let start = 0;
+        if (cursor) {
+            const after = Buffer.from(cursor, 'base64url').toString('utf8');
+            if (!after.startsWith(RESOURCE_PREFIX))
+                throw new RpcError(INVALID_PARAMS, 'invalid params');
+            start = all.findIndex((r) => r.uri > after);
+            if (start < 0)
+                start = all.length;
+        }
+        const page = all.slice(start, start + PAGE_SIZE);
+        const result = { resources: page };
+        if (start + PAGE_SIZE < all.length)
+            result.nextCursor = Buffer.from(page[page.length - 1].uri, 'utf8').toString('base64url');
+        return result;
+    }
+    async readResource(uri) {
+        const id = uri.startsWith(RESOURCE_PREFIX) ? uri.slice(RESOURCE_PREFIX.length) : '';
+        if (id === '')
+            throw resourceNotFound(uri);
+        let sessionID;
+        try {
+            sessionID = this.tools.resolve(id).id;
+        }
+        catch {
+            throw resourceNotFound(uri);
+        }
+        const { text } = await this.tools.summary(sessionID, '');
+        return { contents: [{ uri, mimeType: 'text/markdown', text }] };
+    }
+    getPrompt(name) {
+        if (name !== DEBUG_PROMPT.name)
+            throw new RpcError(INVALID_PARAMS, `unknown prompt ${(0, gofmt_1.goQuote)(name)}`);
+        return {
+            description: 'Debug the latest tabtape recording',
+            messages: [{ role: 'user', content: { type: 'text', text: DEBUG_TEXT } }],
+        };
+    }
+}
+exports.TabtapeMcp = TabtapeMcp;
+function header(req, name) {
+    const v = req.headers[name];
+    return (Array.isArray(v) ? v[0] : v) ?? '';
+}
+/** The Go SDK's reading of Accept: media types without parameters, any case, wildcards. */
+function acceptsJSONAndStream(accept) {
+    let json = false;
+    let stream = false;
+    for (const part of accept.split(',')) {
+        switch ((0, gofmt_1.goTrimSpace)(part.split(';')[0]).toLowerCase()) {
+            case 'application/json':
+            case 'application/*':
+                json = true;
+                break;
+            case 'text/event-stream':
+            case 'text/*':
+                stream = true;
+                break;
+            case '*/*':
+                json = true;
+                stream = true;
+                break;
+        }
+    }
+    return json && stream;
+}
+const TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+";
+const MEDIA_TYPE_RE = new RegExp(`^${TOKEN}(?:/${TOKEN})?$`);
+const PARAM_RE = new RegExp(`^;\\s*${TOKEN}\\s*=\\s*(?:${TOKEN}|"(?:[^"\\\\]|\\\\.)*")\\s*`);
+/** Go's mime.ParseMediaType as the Go SDK uses it: the lowercase media type, or "" when the value is malformed. */
+function baseMediaType(value) {
+    const semi = value.indexOf(';');
+    const base = (0, gofmt_1.goTrimSpace)((semi < 0 ? value : value.slice(0, semi)).toLowerCase());
+    if (!MEDIA_TYPE_RE.test(base))
+        return '';
+    let rest = semi < 0 ? '' : value.slice(semi);
+    while (rest !== '') {
+        if (rest.trim() === ';')
+            break; // a trailing semicolon is fine
+        const m = PARAM_RE.exec(rest);
+        if (!m)
+            return '';
+        rest = rest.slice(m[0].length);
+    }
+    return base;
+}
+/** Go's net.SplitHostPort host part, or null when addr has no port. */
+function splitHost(addr) {
+    if (addr.startsWith('[')) {
+        const end = addr.indexOf(']');
+        if (end < 0 || addr[end + 1] !== ':')
+            return null;
+        return addr.slice(1, end);
+    }
+    const colon = addr.lastIndexOf(':');
+    if (colon < 0 || addr.slice(0, colon).includes(':'))
+        return null;
+    return addr.slice(0, colon);
+}
+const IPV4_RE = /^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/** The Go SDK's util.IsLoopback: "localhost" or a loopback IP, with or without a port. */
+function isLoopback(addr) {
+    const host = splitHost(addr) ?? addr.replace(/^[[\]]+|[[\]]+$/g, '');
+    if (host === 'localhost')
+        return true;
+    if (IPV4_RE.test(host))
+        return host.startsWith('127.');
+    const ip = host.replace(/%.*$/, ''); // zone
+    if (!net_1.default.isIPv6(ip))
+        return false;
+    let normal;
+    try {
+        normal = new URL(`http://[${ip}]/`).hostname;
+    }
+    catch {
+        return false;
+    }
+    return normal === '[::1]' || /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(normal);
+}
+/** The body, or null when it is longer than limit. */
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        req.on('data', (chunk) => {
+            if (settled)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                settled = true;
+                resolve(null); // the rest is drained and dropped
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(Buffer.concat(chunks, size));
+        });
+        req.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        });
+    });
+}
+/** Go's http.Error. */
+function textError(res, status, msg) {
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.writeHead(status);
+    res.end(msg + '\n');
+}
+/** Resolves when the response is sent or the client went away. */
+function responseDone(res) {
+    if (res.writableFinished || res.destroyed)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            res.off('finish', done);
+            res.off('close', done);
+            resolve();
+        };
+        res.on('finish', done);
+        res.on('close', done);
+    });
+}