Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

7.6 KB
Raw Blame
// Package mcp provides a native MCP (Model Context Protocol) server for PinchTab.
package mcp

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strings"
	"sync"
	"time"

	"github.com/pinchtab/pinchtab/internal/activity"
	"github.com/pinchtab/pinchtab/internal/api/types"
)

const vocabHeader = types.HeaderVocab

// vocabStore holds the last snapshot vocabulary token per tab so an interaction
// echoes it back and a ref minted under a superseded snapshot is refused rather
// than resolved against whatever the tab was last renumbered to. Shared by
// pointer so a withTimeout clone reads and writes the same tokens.
type vocabStore struct {
	mu sync.Mutex
	m  map[string]string
}

func newVocabStore() *vocabStore { return &vocabStore{m: map[string]string{}} }

func (v *vocabStore) set(tabKey, token string) {
	if token == "" {
		return
	}
	v.mu.Lock()
	defer v.mu.Unlock()
	v.m[tabKey] = token
}

func (v *vocabStore) get(tabKey string) string {
	v.mu.Lock()
	defer v.mu.Unlock()
	return v.m[tabKey]
}

// Client is an HTTP client for PinchTab's REST API.
type Client struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
	vocab      *vocabStore
}

// NewClient creates a Client for the given PinchTab base URL.
func NewClient(baseURL, token string) *Client {
	return &Client{
		BaseURL: baseURL,
		Token:   token,
		HTTPClient: &http.Client{
			Timeout: 120 * time.Second,
		},
		vocab: newVocabStore(),
	}
}

// withTimeout returns a shallow copy of the Client whose HTTPClient uses the
// given timeout. The original Transport is preserved.
func (c *Client) withTimeout(d time.Duration) *Client {
	clone := *c
	clone.HTTPClient = &http.Client{
		Timeout:   d,
		Transport: c.HTTPClient.Transport,
	}
	return &clone
}

func (c *Client) url(path string) string {
	return c.BaseURL + path
}

func (c *Client) profileInstancePath(profile string) string {
	return "/profiles/" + url.PathEscape(profile) + "/instance"
}

func (c *Client) dashboardProfilesURL() string {
	return strings.TrimRight(c.BaseURL, "/") + "/dashboard/profiles"
}

func (c *Client) do(req *http.Request) ([]byte, int, error) {
	body, code, _, err := c.doWithHeaders(req)
	return body, code, err
}

func (c *Client) doWithHeaders(req *http.Request) ([]byte, int, http.Header, error) {
	if c.Token != "" {
		req.Header.Set("Authorization", "Bearer "+c.Token)
	}
	req.Header.Set(activity.HeaderAgentID, "mcp")
	// No X-PinchTab-Source: MCP calls the public front door with a bearer token, so
	// the ingress strip layer drops inbound X-PinchTab-* headers. Setting a source
	// here would be a silent no-op; MCP correctly falls back to "client" until a
	// per-client MCP credential exists.
	resp, err := c.HTTPClient.Do(req)
	if err != nil {
		return nil, 0, nil, fmt.Errorf("request %s %s: %w", req.Method, req.URL.Path, err)
	}
	defer func() { _ = resp.Body.Close() }()

	body, err := io.ReadAll(io.LimitReader(resp.Body, MaxResponseBytes+1))
	if err != nil {
		return nil, resp.StatusCode, resp.Header, fmt.Errorf("read response: %w", err)
	}
	if len(body) > MaxResponseBytes {
		return nil, resp.StatusCode, resp.Header, oversizeResponseError(req.URL.Path, resp.ContentLength)
	}
	return body, resp.StatusCode, resp.Header, nil
}

// MaxResponseBytes caps what the MCP server will read from one PinchTab response.
// The read takes MaxResponseBytes+1 and refuses above the cap — the module's idiom
// wherever a limit exists — because a body cut at exactly the cap is indistinguishable
// from a whole one, and the consumer here is a language model that cannot tell a
// truncated base64 image from a complete one.
const MaxResponseBytes = 10 << 20

// oversizeResponseError refuses the read and tells the agent how to ask for less.
// A refusal an agent cannot act on is retried verbatim, so the remedy is keyed to the
// endpoint that produced the body rather than being a generic "too large".
func oversizeResponseError(path string, contentLength int64) error {
	seen := "more than"
	if contentLength >= 0 {
		seen = fmt.Sprintf("%d bytes, over", contentLength)
	}
	return fmt.Errorf("%s returned %s the %d-byte response limit and was refused rather than truncated; %s",
		path, seen, MaxResponseBytes, oversizeRemedy(path))
}

// oversizeRemedy names the narrowing argument of the tool that reaches each path.
func oversizeRemedy(path string) string {
	switch {
	case strings.HasSuffix(path, "/screenshot"):
		return "retry with beyondViewport=false, a lower quality, or a selector so only one element is captured"
	case strings.HasSuffix(path, "/capture"):
		return "retry with beyondViewport=false, a lower quality, or interactiveOnly so the snapshot half is smaller"
	case strings.HasSuffix(path, "/snapshot"), strings.HasSuffix(path, "/text"),
		strings.HasSuffix(path, "/html"), strings.HasSuffix(path, "/scrape"):
		return "retry with a selector, a smaller depth, or interactiveOnly to read one region instead of the page"
	default:
		return "retry asking for less of the page"
	}
}

// GetCapturingVocab performs a GET and records the response's vocabulary token
// under tabKey, so a later interaction on the same tab echoes it. tabKey is the
// tab as the caller addresses it (the tabId argument, possibly empty), which is
// stable across a session's snapshot and action calls.
func (c *Client) GetCapturingVocab(ctx context.Context, path string, query url.Values, tabKey string) ([]byte, int, error) {
	u := c.url(path)
	if len(query) > 0 {
		u += "?" + query.Encode()
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
	if err != nil {
		return nil, 0, err
	}
	body, code, hdr, err := c.doWithHeaders(req)
	if err == nil && code < 400 {
		c.vocab.set(tabKey, hdr.Get(vocabHeader))
	}
	return body, code, err
}

// VocabToken returns the last vocabulary token captured for tabKey, or "".
func (c *Client) VocabToken(tabKey string) string { return c.vocab.get(tabKey) }

// Get performs a GET request and returns the response body.
func (c *Client) Get(ctx context.Context, path string, query url.Values) ([]byte, int, error) {
	u := c.url(path)
	if len(query) > 0 {
		u += "?" + query.Encode()
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
	if err != nil {
		return nil, 0, err
	}
	return c.do(req)
}

// Delete performs a DELETE request, optionally with a query string.
func (c *Client) Delete(ctx context.Context, path string, query url.Values) ([]byte, int, error) {
	u := c.url(path)
	if len(query) > 0 {
		u += "?" + query.Encode()
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, u, nil)
	if err != nil {
		return nil, 0, err
	}
	return c.do(req)
}

// Post performs a POST request with a JSON body.
func (c *Client) Post(ctx context.Context, path string, payload any) ([]byte, int, error) {
	req, err := c.newPostRequest(ctx, path, payload)
	if err != nil {
		return nil, 0, err
	}
	return c.do(req)
}

func (c *Client) PostCapturingVocab(ctx context.Context, path string, payload any, tabKey string) ([]byte, int, error) {
	req, err := c.newPostRequest(ctx, path, payload)
	if err != nil {
		return nil, 0, err
	}
	body, code, hdr, err := c.doWithHeaders(req)
	if err == nil && code < 400 {
		c.vocab.set(tabKey, hdr.Get(vocabHeader))
	}
	return body, code, err
}

func (c *Client) newPostRequest(ctx context.Context, path string, payload any) (*http.Request, error) {
	var body io.Reader
	if payload != nil {
		b, err := json.Marshal(payload)
		if err != nil {
			return nil, fmt.Errorf("marshal payload: %w", err)
		}
		body = bytes.NewReader(b)
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url(path), body)
	if err != nil {
		return nil, err
	}
	if payload != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	return req, nil
}