@plasmate/ai

Plasmate browser tools for the Vercel AI SDK

Plasmate is a headless browser MCP server that gives AI models structured access to the web via a Set of Marks (SOM) representation. This package is a thin wrapper that connects Plasmate to the Vercel AI SDK in one function call.

Install

npm install @plasmate/ai ai

You also need Plasmate installed locally:

npm install -g plasmate
# or
brew install plasmate-labs/tap/plasmate

Quick Start

import { createPlasmateTools } from '@plasmate/ai'
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'

const { tools, close } = await createPlasmateTools()

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools,
  maxSteps: 5,
  prompt: 'Summarize the top 3 stories on news.ycombinator.com',
})

console.log(text)

await close()

API

createPlasmateTools(options?)

Spawns plasmate mcp as a stdio MCP server and returns tools ready for use with generateText, streamText, etc.

Options:

| Option | Type | Default | Description | |-----------|----------|---------------|------------------------------------------| | binary | string | 'plasmate' | Path to the plasmate binary (if not in PATH) |

Returns: Promise<{ tools, close }>

• tools — Record<string, CoreTool> ready to pass directly to generateText / streamText
• close() — Call this when done to terminate the MCP subprocess

Available Tools

| Tool | Description | |-----------------|------------------------------------------------------------------| | fetch_page | Fetch a URL and return a structured SOM representation | | extract_text | Extract readable text content from the current page | | extract_links | Extract all links from the current page | | open_page | Open a URL in a headless browser session | | click | Click an element identified by its SOM marker | | type_text | Type text into a focused input element | | navigate_to | Navigate to a URL within an existing browser session | | evaluate | Evaluate JavaScript in the context of the current page |

Usage Examples

Basic web research

import { createPlasmateTools } from '@plasmate/ai'
import { generateText } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'

const { tools, close } = await createPlasmateTools()

const { text } = await generateText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  tools,
  maxSteps: 10,
  prompt: 'What are the latest AI news headlines on techcrunch.com?',
})

await close()
console.log(text)

Custom binary path

const { tools, close } = await createPlasmateTools({
  binary: '/usr/local/bin/plasmate',
})

Next.js App Router route

// app/api/browse/route.ts
import { createPlasmateTools } from '@plasmate/ai'
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

export async function POST(req: Request) {
  const { prompt } = await req.json()

  const { tools, close } = await createPlasmateTools()

  const result = streamText({
    model: openai('gpt-4o'),
    tools,
    maxSteps: 5,
    prompt,
    onFinish: async () => {
      await close()
    },
  })

  return result.toDataStreamResponse()
}

Error handling

import { createPlasmateTools } from '@plasmate/ai'

try {
  const { tools, close } = await createPlasmateTools()
  // ... use tools
  await close()
} catch (err) {
  // createPlasmateTools throws if plasmate binary is not found
  // or the MCP server fails to start
  console.error('Plasmate error:', err)
}

How It Works

createPlasmateTools uses the Vercel AI SDK's experimental_createMCPClient with a stdio transport to spawn plasmate mcp as a child process. Plasmate speaks the Model Context Protocol (MCP) over stdin/stdout, and the AI SDK converts the MCP tool definitions into CoreTool objects that models can call natively.

generateText ──► CoreTool ──► MCP Client ──► plasmate mcp (stdio) ──► headless browser

Requirements

• Node.js 18+
• plasmate CLI installed and in PATH (or specify via binary option)
• ai >= 4.0.0 (peer dependency)

License

MIT