@viral_vector/ig-mcp 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# ViralVector Instagram MCP Server
+
+`@viral_vector/ig-mcp` exposes ViralVector Instagram library and live exploration tools through MCP over stdio. The same process also starts a localhost bridge server that the Chrome extension connects to.
+
+A pairing token is required. The server refuses to start without `--token` or `VV_IG_MCP_TOKEN`.
+
+## MCP Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "viralvector-instagram": {
+      "command": "npx",
+      "args": ["-y", "@viral_vector/ig-mcp"],
+      "env": {
+        "VV_IG_MCP_PORT": "8765",
+        "VV_IG_MCP_TOKEN": "replace-with-extension-pairing-token"
+      }
+    }
+  }
+}
+```
+
+The MCP transport uses stdout. Diagnostics and bridge status messages are written to stderr.
+
+## Extension Pairing
+
+1. Open the ViralVector extension dashboard.
+2. Go to Settings.
+3. Enable the local MCP bridge.
+4. Set the bridge port to the same `VV_IG_MCP_PORT` value.
+5. Copy the pairing token into `VV_IG_MCP_TOKEN`.
+6. Start or restart the MCP client.
+
+The bridge server binds only to `127.0.0.1` and accepts WebSocket connections on `/viral-vector-bridge`.
+
+Common recovery paths:
+
+- `extension_disconnected`: open Chrome, load the ViralVector extension, enable Local MCP bridge in Settings, and verify the port matches `VV_IG_MCP_PORT`.
+- `auth_failed`: copy the same pairing token into extension Settings and `VV_IG_MCP_TOKEN`; restart the MCP client after changing environment variables.
+- `instagram_session_unavailable`: open Instagram in the same Chrome profile and sign in before calling session-dependent tools.
+
+## Recommended Tools
+
+Recommended tools use `snake_case` names and keep local-library reads, live Instagram exploration, and explicit local mutations separate.
+
+### Viral Vector Local Library: `vv_*`
+
+`vv_*` tools query only data already saved in the ViralVector extension library, historical snapshots, saved media/comments, exports, and existing operations. They do not perform Instagram live search and they do not implicitly create tracked targets.
+
+- `vv_status`
+- `vv_library_query`
+- `vv_account_query`
+- `vv_account_audience_query`
+- `vv_hashtag_query`
+- `vv_media_query`
+- `vv_comments_query`
+- `vv_operation_run`
+- `vv_operation_query`
+
+`vv_operation_run` is the only explicit side-effect entrypoint. It supports these `kind` values:
+
+- `account_track`
+- `account_update_role`
+- `account_untrack`
+- `account_refresh`
+- `hashtag_track`
+- `hashtag_untrack`
+- `hashtag_refresh`
+- `media_comments_refresh`
+- `media_download`
+- `export_create`
+
+`account_untrack` and `hashtag_untrack` delete local tracked targets only. They do not delete Instagram content. Use `dryRun: true` to validate inputs and preview effects without calling mutating bridge capabilities.
+
+### Instagram Live Exploration: `ig_*`
+
+`ig_*` tools are temporary Instagram exploration entrypoints. They are read-only from the plugin perspective: they must not save targets, start tracking, refresh snapshots, or write to the local library. Returned candidates must identify whether the object is already known locally with flags such as `inLibrary` or `isTracked`.
+
+- `ig_search`
+  - Parameters: `query`, optional `targets` (`accounts`, `hashtags`), optional `limit`.
+  - Purpose: live candidate search across Instagram accounts and hashtags.
+- `ig_lookup`
+  - Parameters: `type` (`account`, `hashtag`), one identifier (`username` or `hashtag`), optional `include` (`recent_media`, `related`) and `mediaLimit`.
+  - Purpose: live lightweight lookup for one Instagram account or hashtag.
+
+Live exploration is read-only and never persists results. Saving or refreshing a chosen result remains explicit:
+
+```text
+ig_search -> ig_lookup -> vv_operation_run(kind: "account_track") -> vv_account_query
+ig_lookup(type: "hashtag", hashtag) -> vv_operation_run(kind: "hashtag_track") -> vv_hashtag_query
+```
+
+The MCP facade hides extension internals such as collection tasks, export repositories, and IndexedDB storage shapes while preserving the underlying bridge protocol.
+
+Instagram requests share a single extension-side queue. Defaults are configured in `../src/config/instagramRequestSettings.ts`: one request at a time, a 1-second minimum interval, 30-second in-memory duplicate reuse, and persisted cooldowns after rate-limit, feedback, or challenge responses.
+
+## CLI
+
+```bash
+vv-ig-mcp --port 8765 --token replace-with-extension-pairing-token
+```
+
+Environment variables:
+
+- `VV_IG_MCP_PORT`
+- `VV_IG_MCP_TOKEN`
+- `VV_IG_MCP_REQUEST_TIMEOUT_MS`
+
+## Local Verification
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm smoke:mcp-v1
+npm pack
+npx -y ./viral_vector-ig-mcp-*.tgz --help
+```
+
+Formal npm publishing is intentionally outside this repository workflow.
+
+See `../../docs/ig-extension-mcp-v1-smoke.md` for the full automated smoke, manual Chrome checklist, and expected error samples.

package/dist/bridge/protocol.d.ts

@@ -0,0 +1,84 @@
+export declare const BRIDGE_PROTOCOL_VERSION = 1;
+export declare const BRIDGE_PATH = "/viral-vector-bridge";
+export declare const CAPABILITIES: {
+    readonly SOCIAL_SESSION_STATUS: "social.session.status";
+    readonly SOCIAL_INSTAGRAM_LOOKUP_ACCOUNT: "social.instagram.lookupAccount";
+    readonly SOCIAL_INSTAGRAM_LOOKUP_HASHTAG: "social.instagram.lookupHashtag";
+    readonly SOCIAL_CONTEXT_QUERY_AUDIENCE_MEMBERS: "social.context.queryAudienceMembers";
+    readonly SOCIAL_CONTEXT_LIST_ACCOUNTS: "social.context.listAccounts";
+    readonly SOCIAL_CONTEXT_SEARCH_ACCOUNTS: "social.context.searchAccounts";
+    readonly SOCIAL_CONTEXT_SEARCH_HASHTAGS: "social.context.searchHashtags";
+    readonly SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL: "social.context.getAccountDetail";
+    readonly SOCIAL_CONTEXT_GET_HASHTAG_DETAIL: "social.context.getHashtagDetail";
+    readonly SOCIAL_CONTEXT_GET_POST_DETAIL: "social.context.getPostDetail";
+    readonly SOCIAL_CONTEXT_UPSERT_ACCOUNT_TARGET: "social.context.upsertAccountTarget";
+    readonly SOCIAL_CONTEXT_UPSERT_HASHTAG_TARGET: "social.context.upsertHashtagTarget";
+    readonly SOCIAL_CONTEXT_UPDATE_ACCOUNT_ROLE: "social.context.updateAccountRole";
+    readonly SOCIAL_CONTEXT_DELETE_ACCOUNT: "social.context.deleteAccount";
+    readonly SOCIAL_CONTEXT_DELETE_HASHTAG: "social.context.deleteHashtag";
+    readonly SOCIAL_CONTEXT_LIST_EXPORTS: "social.context.listExports";
+    readonly SOCIAL_CONTEXT_EXPORT_CSV: "social.context.exportCsv";
+    readonly SOCIAL_COLLECTION_START: "social.collection.start";
+    readonly SOCIAL_COLLECTION_LIST_TASKS: "social.collection.listTasks";
+    readonly SOCIAL_COLLECTION_GET_ACTIVE_TASK: "social.collection.getActiveTask";
+    readonly SOCIAL_MEDIA_DOWNLOAD: "social.media.download";
+};
+export type CapabilityName = (typeof CAPABILITIES)[keyof typeof CAPABILITIES];
+export declare const BRIDGE_ERROR_CODES: {
+    readonly MALFORMED_FRAME: "malformed_frame";
+    readonly EXTENSION_DISCONNECTED: "extension_disconnected";
+    readonly BRIDGE_DISABLED: "bridge_disabled";
+    readonly AUTH_FAILED: "auth_failed";
+    readonly VALIDATION_FAILED: "validation_failed";
+    readonly UNSUPPORTED_CAPABILITY: "unsupported_capability";
+    readonly WRITE_CAPABILITY_DISABLED: "write_capability_disabled";
+    readonly TOOL_TIMEOUT: "tool_timeout";
+    readonly INSTAGRAM_SESSION_UNAVAILABLE: "instagram_session_unavailable";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly INSTAGRAM_CHALLENGE: "instagram_challenge";
+    readonly HANDLER_FAILED: "handler_failed";
+    readonly DUPLICATE_CONNECTION: "duplicate_connection";
+};
+export type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[keyof typeof BRIDGE_ERROR_CODES];
+export type BridgeHelloFrame = {
+    type: 'hello';
+    id: string;
+    protocolVersion: typeof BRIDGE_PROTOCOL_VERSION;
+    clientId: string;
+    extensionVersion?: string;
+    token?: string;
+};
+export type BridgeRequestFrame = {
+    type: 'request';
+    id: string;
+    capability: string;
+    input?: unknown;
+    token?: string;
+};
+export type BridgeResponseFrame = {
+    type: 'response';
+    id: string;
+    capability: string;
+    ok: true;
+    data: unknown;
+};
+export type BridgeErrorFrame = {
+    type: 'error';
+    id: string | null;
+    capability: string | null;
+    ok: false;
+    error: {
+        code: BridgeErrorCode;
+        message: string;
+    };
+};
+export type BridgeConnectionStatusFrame = {
+    type: 'connection_status';
+    status: string;
+    lastConnectedAt: string | null;
+    lastError: string | null;
+};
+export type BridgeFrame = BridgeHelloFrame | BridgeRequestFrame | BridgeResponseFrame | BridgeErrorFrame | BridgeConnectionStatusFrame;
+export declare function parseBridgeFrame(value: unknown): BridgeFrame | BridgeErrorFrame;
+export declare function createBridgeErrorFrame(id: string | null, capability: string | null, code: BridgeErrorCode, message: string): BridgeErrorFrame;
+export declare function createBridgeRequestFrame(id: string, capability: CapabilityName, input: unknown, token: string | null): BridgeRequestFrame;

package/dist/bridge/protocol.js

@@ -0,0 +1,139 @@
+export const BRIDGE_PROTOCOL_VERSION = 1;
+export const BRIDGE_PATH = '/viral-vector-bridge';
+export const CAPABILITIES = {
+    SOCIAL_SESSION_STATUS: 'social.session.status',
+    SOCIAL_INSTAGRAM_LOOKUP_ACCOUNT: 'social.instagram.lookupAccount',
+    SOCIAL_INSTAGRAM_LOOKUP_HASHTAG: 'social.instagram.lookupHashtag',
+    SOCIAL_CONTEXT_QUERY_AUDIENCE_MEMBERS: 'social.context.queryAudienceMembers',
+    SOCIAL_CONTEXT_LIST_ACCOUNTS: 'social.context.listAccounts',
+    SOCIAL_CONTEXT_SEARCH_ACCOUNTS: 'social.context.searchAccounts',
+    SOCIAL_CONTEXT_SEARCH_HASHTAGS: 'social.context.searchHashtags',
+    SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL: 'social.context.getAccountDetail',
+    SOCIAL_CONTEXT_GET_HASHTAG_DETAIL: 'social.context.getHashtagDetail',
+    SOCIAL_CONTEXT_GET_POST_DETAIL: 'social.context.getPostDetail',
+    SOCIAL_CONTEXT_UPSERT_ACCOUNT_TARGET: 'social.context.upsertAccountTarget',
+    SOCIAL_CONTEXT_UPSERT_HASHTAG_TARGET: 'social.context.upsertHashtagTarget',
+    SOCIAL_CONTEXT_UPDATE_ACCOUNT_ROLE: 'social.context.updateAccountRole',
+    SOCIAL_CONTEXT_DELETE_ACCOUNT: 'social.context.deleteAccount',
+    SOCIAL_CONTEXT_DELETE_HASHTAG: 'social.context.deleteHashtag',
+    SOCIAL_CONTEXT_LIST_EXPORTS: 'social.context.listExports',
+    SOCIAL_CONTEXT_EXPORT_CSV: 'social.context.exportCsv',
+    SOCIAL_COLLECTION_START: 'social.collection.start',
+    SOCIAL_COLLECTION_LIST_TASKS: 'social.collection.listTasks',
+    SOCIAL_COLLECTION_GET_ACTIVE_TASK: 'social.collection.getActiveTask',
+    SOCIAL_MEDIA_DOWNLOAD: 'social.media.download'
+};
+export const BRIDGE_ERROR_CODES = {
+    MALFORMED_FRAME: 'malformed_frame',
+    EXTENSION_DISCONNECTED: 'extension_disconnected',
+    BRIDGE_DISABLED: 'bridge_disabled',
+    AUTH_FAILED: 'auth_failed',
+    VALIDATION_FAILED: 'validation_failed',
+    UNSUPPORTED_CAPABILITY: 'unsupported_capability',
+    WRITE_CAPABILITY_DISABLED: 'write_capability_disabled',
+    TOOL_TIMEOUT: 'tool_timeout',
+    INSTAGRAM_SESSION_UNAVAILABLE: 'instagram_session_unavailable',
+    RATE_LIMITED: 'rate_limited',
+    INSTAGRAM_CHALLENGE: 'instagram_challenge',
+    HANDLER_FAILED: 'handler_failed',
+    DUPLICATE_CONNECTION: 'duplicate_connection'
+};
+export function parseBridgeFrame(value) {
+    if (typeof value === 'string') {
+        try {
+            return parseBridgeFrame(JSON.parse(value));
+        }
+        catch {
+            return createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge frame must be valid JSON.');
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge frame must be an object.');
+    }
+    const candidate = value;
+    switch (candidate.type) {
+        case 'hello':
+            return isHelloFrame(candidate)
+                ? candidate
+                : createBridgeErrorFrame(frameId(candidate), null, BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge hello frame is malformed.');
+        case 'response':
+            return isResponseFrame(candidate)
+                ? candidate
+                : createBridgeErrorFrame(frameId(candidate), frameCapability(candidate), BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge response frame is malformed.');
+        case 'error':
+            return isErrorFrame(candidate)
+                ? candidate
+                : createBridgeErrorFrame(frameId(candidate), frameCapability(candidate), BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge error frame is malformed.');
+        case 'connection_status':
+            return isConnectionStatusFrame(candidate)
+                ? candidate
+                : createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge connection status frame is malformed.');
+        case 'request':
+            return isRequestFrame(candidate)
+                ? candidate
+                : createBridgeErrorFrame(frameId(candidate), frameCapability(candidate), BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Bridge request frame is malformed.');
+        default:
+            return createBridgeErrorFrame(frameId(candidate), frameCapability(candidate), BRIDGE_ERROR_CODES.MALFORMED_FRAME, 'Unsupported bridge frame type.');
+    }
+}
+export function createBridgeErrorFrame(id, capability, code, message) {
+    return {
+        type: 'error',
+        id,
+        capability,
+        ok: false,
+        error: { code, message }
+    };
+}
+export function createBridgeRequestFrame(id, capability, input, token) {
+    return {
+        type: 'request',
+        id,
+        capability,
+        input,
+        token: token ?? undefined
+    };
+}
+function isHelloFrame(value) {
+    return value.type === 'hello'
+        && typeof value.id === 'string'
+        && value.id.trim() !== ''
+        && value.protocolVersion === BRIDGE_PROTOCOL_VERSION
+        && typeof value.clientId === 'string'
+        && value.clientId.trim() !== ''
+        && (value.extensionVersion === undefined || typeof value.extensionVersion === 'string');
+}
+function isRequestFrame(value) {
+    return value.type === 'request'
+        && typeof value.id === 'string'
+        && value.id.trim() !== ''
+        && typeof value.capability === 'string'
+        && value.capability.trim() !== '';
+}
+function isResponseFrame(value) {
+    return value.type === 'response'
+        && value.ok === true
+        && typeof value.id === 'string'
+        && value.id.trim() !== ''
+        && typeof value.capability === 'string'
+        && value.capability.trim() !== '';
+}
+function isErrorFrame(value) {
+    return value.type === 'error'
+        && value.ok === false
+        && value.error !== undefined
+        && typeof value.error.code === 'string'
+        && typeof value.error.message === 'string';
+}
+function isConnectionStatusFrame(value) {
+    return value.type === 'connection_status'
+        && typeof value.status === 'string'
+        && (value.lastConnectedAt === null || typeof value.lastConnectedAt === 'string')
+        && (value.lastError === null || typeof value.lastError === 'string');
+}
+function frameId(value) {
+    return typeof value.id === 'string' && value.id.trim() !== '' ? value.id : null;
+}
+function frameCapability(value) {
+    return typeof value.capability === 'string' && value.capability.trim() !== '' ? value.capability : null;
+}

package/dist/bridge/server.d.ts

@@ -0,0 +1,12 @@
+import { ExtensionSessionRegistry } from './sessionRegistry.js';
+export type LocalBridgeServerOptions = {
+    port: number;
+    registry: ExtensionSessionRegistry;
+    host?: '127.0.0.1';
+    log?: (message: string, context?: unknown) => void;
+};
+export type LocalBridgeServer = {
+    close: () => Promise<void>;
+    port: () => number;
+};
+export declare function startLocalBridgeServer({ port, registry, host, log }: LocalBridgeServerOptions): Promise<LocalBridgeServer>;

package/dist/bridge/server.js

@@ -0,0 +1,82 @@
+import { WebSocketServer } from 'ws';
+import { BRIDGE_ERROR_CODES, BRIDGE_PATH, createBridgeErrorFrame, parseBridgeFrame } from './protocol.js';
+export async function startLocalBridgeServer({ port, registry, host = '127.0.0.1', log = () => { } }) {
+    const server = new WebSocketServer({ host, port, path: BRIDGE_PATH });
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        let authorized = false;
+        const helloTimer = setTimeout(() => {
+            if (!authorized) {
+                sendError(socket, createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.AUTH_FAILED, 'Bridge hello was not received before timeout.'));
+                socket.close(1008, 'hello_timeout');
+            }
+        }, 5_000);
+        socket.on('message', (data) => {
+            const raw = data.toString('utf8');
+            if (!authorized) {
+                const frame = parseBridgeFrame(raw);
+                if (frame.type !== 'hello') {
+                    sendError(socket, frame.type === 'error'
+                        ? frame
+                        : createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.AUTH_FAILED, 'First bridge frame must be hello.'));
+                    socket.close(1008, 'hello_required');
+                    return;
+                }
+                const error = registry.attach(socket, frame);
+                if (error) {
+                    sendError(socket, error);
+                    socket.close(1008, 'auth_failed');
+                    return;
+                }
+                authorized = true;
+                clearTimeout(helloTimer);
+                log('Extension bridge connected', {
+                    clientId: frame.clientId,
+                    extensionVersion: frame.extensionVersion ?? null
+                });
+                return;
+            }
+            const error = registry.handleMessage(socket, raw);
+            if (error) {
+                sendError(socket, error);
+            }
+        });
+        socket.on('close', () => {
+            clearTimeout(helloTimer);
+            sockets.delete(socket);
+            registry.detach(socket);
+            log('Extension bridge disconnected');
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('listening', resolve);
+        server.once('error', reject);
+    });
+    return {
+        close: () => new Promise((resolve, reject) => {
+            for (const socket of sockets) {
+                registry.detach(socket);
+                socket.close(1001, 'server_shutdown');
+                socket.terminate();
+            }
+            sockets.clear();
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+        port: () => {
+            const address = server.address();
+            return typeof address === 'object' && address ? address.port : port;
+        }
+    };
+}
+function sendError(socket, frame) {
+    if (socket.readyState === socket.OPEN) {
+        socket.send(JSON.stringify(frame));
+    }
+}

package/dist/bridge/sessionRegistry.d.ts

@@ -0,0 +1,50 @@
+import type { WebSocket } from 'ws';
+import { type BridgeConnectionStatusFrame, type BridgeErrorFrame, type BridgeHelloFrame, type CapabilityName } from './protocol.js';
+export type BridgeRequestResult = {
+    ok: true;
+    requestId: string;
+    capability: CapabilityName;
+    data: unknown;
+} | {
+    ok: false;
+    requestId: string | null;
+    capability: string | null;
+    error: BridgeErrorFrame['error'];
+};
+export type ExtensionConnectionStatus = {
+    connected: boolean;
+    clientId: string | null;
+    extensionVersion: string | null;
+    connectedAt: string | null;
+    lastSeenAt: string | null;
+    lastStatus: BridgeConnectionStatusFrame | null;
+    pendingRequests: number;
+};
+export type ExtensionSessionRegistryOptions = {
+    token: string;
+    requestTimeoutMs?: number;
+    now?: () => Date;
+    setTimer?: (callback: () => void, delayMs: number) => unknown;
+    clearTimer?: (timer: unknown) => void;
+};
+export declare class ExtensionSessionRegistry {
+    private readonly token;
+    private readonly requestTimeoutMs;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private session;
+    private lastStatus;
+    private sequence;
+    private readonly pending;
+    constructor(options: ExtensionSessionRegistryOptions);
+    attach(socket: WebSocket, hello: BridgeHelloFrame): BridgeErrorFrame | null;
+    detach(socket: WebSocket): void;
+    failPending(error: BridgeErrorFrame['error']): void;
+    handleMessage(socket: WebSocket, value: unknown): BridgeErrorFrame | null;
+    getStatus(): ExtensionConnectionStatus;
+    request(capability: CapabilityName, input?: unknown): Promise<BridgeRequestResult>;
+    private isConnected;
+    private resolvePendingResponse;
+    private resolvePendingError;
+}

package/dist/bridge/sessionRegistry.js

@@ -0,0 +1,175 @@
+import { BRIDGE_ERROR_CODES, CAPABILITIES, createBridgeErrorFrame, createBridgeRequestFrame, parseBridgeFrame } from './protocol.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+export class ExtensionSessionRegistry {
+    token;
+    requestTimeoutMs;
+    now;
+    setTimer;
+    clearTimer;
+    session = null;
+    lastStatus = null;
+    sequence = 0;
+    pending = new Map();
+    constructor(options) {
+        this.token = options.token;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.now = options.now ?? (() => new Date());
+        this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer));
+    }
+    attach(socket, hello) {
+        if (hello.token !== this.token) {
+            return createBridgeErrorFrame(hello.id, null, BRIDGE_ERROR_CODES.AUTH_FAILED, 'Bridge pairing token is missing or invalid.');
+        }
+        if (this.session && this.session.socket !== socket) {
+            this.session.socket.send(JSON.stringify(createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.DUPLICATE_CONNECTION, 'Another extension bridge connection replaced this session.')));
+            this.failPending({
+                code: BRIDGE_ERROR_CODES.DUPLICATE_CONNECTION,
+                message: 'Another extension bridge connection replaced this session.'
+            });
+            this.session.socket.close(4000, 'duplicate_connection');
+        }
+        const now = this.now().toISOString();
+        this.session = {
+            socket,
+            clientId: hello.clientId,
+            extensionVersion: hello.extensionVersion ?? null,
+            connectedAt: now,
+            lastSeenAt: now
+        };
+        this.lastStatus = null;
+        return null;
+    }
+    detach(socket) {
+        if (!this.session || this.session.socket !== socket) {
+            return;
+        }
+        this.session = null;
+        this.failPending({
+            code: BRIDGE_ERROR_CODES.EXTENSION_DISCONNECTED,
+            message: 'Extension disconnected before the bridge request completed.'
+        });
+    }
+    failPending(error) {
+        for (const [id, pending] of this.pending) {
+            this.clearTimer(pending.timer);
+            pending.resolve({
+                ok: false,
+                requestId: id,
+                capability: pending.capability,
+                error
+            });
+        }
+        this.pending.clear();
+    }
+    handleMessage(socket, value) {
+        const frame = parseBridgeFrame(value);
+        if (frame.type === 'error') {
+            this.resolvePendingError(frame);
+            return null;
+        }
+        if (!this.session || this.session.socket !== socket) {
+            return createBridgeErrorFrame(null, null, BRIDGE_ERROR_CODES.EXTENSION_DISCONNECTED, 'Bridge extension session is not active.');
+        }
+        this.session.lastSeenAt = this.now().toISOString();
+        if (frame.type === 'response') {
+            this.resolvePendingResponse(frame);
+            return null;
+        }
+        if (frame.type === 'connection_status') {
+            this.lastStatus = frame;
+            return null;
+        }
+        if (frame.type === 'request') {
+            return createBridgeErrorFrame(frame.id, frame.capability, BRIDGE_ERROR_CODES.UNSUPPORTED_CAPABILITY, 'MCP bridge server does not accept extension-initiated capability requests.');
+        }
+        return null;
+    }
+    getStatus() {
+        return {
+            connected: this.isConnected(),
+            clientId: this.session?.clientId ?? null,
+            extensionVersion: this.session?.extensionVersion ?? null,
+            connectedAt: this.session?.connectedAt ?? null,
+            lastSeenAt: this.session?.lastSeenAt ?? null,
+            lastStatus: this.lastStatus,
+            pendingRequests: this.pending.size
+        };
+    }
+    async request(capability, input = {}) {
+        if (!Object.values(CAPABILITIES).includes(capability)) {
+            return {
+                ok: false,
+                requestId: null,
+                capability,
+                error: {
+                    code: BRIDGE_ERROR_CODES.UNSUPPORTED_CAPABILITY,
+                    message: `Unsupported MCP bridge capability: ${capability}`
+                }
+            };
+        }
+        if (!this.isConnected() || !this.session) {
+            return {
+                ok: false,
+                requestId: null,
+                capability,
+                error: {
+                    code: BRIDGE_ERROR_CODES.EXTENSION_DISCONNECTED,
+                    message: 'ViralVector extension is not connected to the local MCP bridge.'
+                }
+            };
+        }
+        const requestId = `mcp-${Date.now().toString(36)}-${(++this.sequence).toString(36)}`;
+        const frame = createBridgeRequestFrame(requestId, capability, input, this.token);
+        return new Promise((resolve) => {
+            const timer = this.setTimer(() => {
+                this.pending.delete(requestId);
+                resolve({
+                    ok: false,
+                    requestId,
+                    capability,
+                    error: {
+                        code: BRIDGE_ERROR_CODES.TOOL_TIMEOUT,
+                        message: `Bridge request timed out after ${this.requestTimeoutMs}ms.`
+                    }
+                });
+            }, this.requestTimeoutMs);
+            this.pending.set(requestId, { capability, timer, resolve });
+            this.session?.socket.send(JSON.stringify(frame));
+        });
+    }
+    isConnected() {
+        return Boolean(this.session && this.session.socket.readyState === this.session.socket.OPEN);
+    }
+    resolvePendingResponse(frame) {
+        const pending = this.pending.get(frame.id);
+        if (!pending) {
+            return;
+        }
+        this.pending.delete(frame.id);
+        this.clearTimer(pending.timer);
+        pending.resolve({
+            ok: true,
+            requestId: frame.id,
+            capability: pending.capability,
+            data: frame.data
+        });
+    }
+    resolvePendingError(frame) {
+        if (!frame.id) {
+            return;
+        }
+        const pending = this.pending.get(frame.id);
+        if (!pending) {
+            return;
+        }
+        this.pending.delete(frame.id);
+        this.clearTimer(pending.timer);
+        pending.resolve({
+            ok: false,
+            requestId: frame.id,
+            capability: frame.capability,
+            error: frame.error
+        });
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};