Skip to main content
Glama
instruckt-mcp
by tdwesten

instruckt-mcp

MCP server and API handlers for instruckt visual annotations. Stores annotations and screenshots to disk, and exposes them to your AI agent via MCP tools.

Install

npm install instruckt-mcp

Related MCP server: Lens

Quick Start

Pick your setup below — each section is self-contained.

Setup

Use when

Next.js

App Router route handler

Ember.js 6+

Dev-server middleware via server/index.js

Custom backend

Any Node.js framework


Next.js

Create a route handler at app/api/annotations/[[...slug]]/route.ts:

import { createHandlers } from 'instruckt-mcp/nextjs'

export const { GET, POST, PATCH } = createHandlers()

Then wire up the MCP server in your Claude/agent config:

{
  "mcpServers": {
    "instruckt": {
      "command": "npx",
      "args": ["instruckt-mcp"]
    }
  }
}

Ember.js 6+

Add the adapter to your Ember CLI dev-server in server/index.js:

const { createEmberMiddleware } = require('@tdwesten/instruckt-mcp/ember');

module.exports = createEmberMiddleware();

This registers GET, POST, and PATCH /api/annotations on the Ember CLI Express dev-server. Request bodies up to 10 MB are accepted (large enough for base64-encoded screenshots). Options:

Option

Type

Default

Description

route

string

/api/annotations

Base path for the endpoints (trailing slashes are trimmed)

dir

string

.instruckt

Storage directory

Development only. Ember CLI's middleware runs during ember serve. For production, use the Custom backend setup with your own Node server.

Then wire up the MCP server in your Claude/agent config:

{
  "mcpServers": {
    "instruckt": {
      "command": "npx",
      "args": ["instruckt-mcp"]
    }
  }
}

Custom backend

Use createRequestHandlers with any Node.js framework:

import { InstrucktStorage, createRequestHandlers } from 'instruckt-mcp'

const storage = new InstrucktStorage('.instruckt')
const handlers = createRequestHandlers(storage)

// GET /annotations
app.get('/annotations', async (req, res) => {
  res.json(await handlers.getAnnotations())
})

// POST /annotations
app.post('/annotations', async (req, res) => {
  res.status(201).json(await handlers.createAnnotation(req.body))
})

// PATCH /annotations/:id
app.patch('/annotations/:id', async (req, res) => {
  res.json(await handlers.updateAnnotation(req.params.id, req.body))
})

MCP Tools

Once connected, your AI agent has three tools:

Tool

Description

get_all_pending

Returns all unresolved annotations — comment, element, page URL, severity

get_screenshot

Returns the screenshot image for a specific annotation by ID

resolve

Marks an annotation as resolved; the instruckt widget removes the marker on its next poll

How It Works

  1. instruckt runs in your app and captures annotations with optional screenshots

  2. Annotations are posted to your API endpoint and stored as JSON on disk

  3. Your AI agent connects via MCP and calls get_all_pending to see what needs fixing

  4. The agent reads the feedback, inspects screenshots with get_screenshot, and makes code changes

  5. When done, the agent calls resolve — the widget picks up the status change on its next poll and removes the marker

Storage

Annotations are stored in .instruckt/annotations.json. Screenshots go in .instruckt/screenshots/<id>.png. The directory is created automatically on first use.

import { InstrucktStorage } from 'instruckt-mcp'

const storage = new InstrucktStorage('.instruckt')

await storage.getAll()          // all annotations
await storage.getPending()      // unresolved only
await storage.add(input)        // create annotation
await storage.update(id, input) // update annotation
await storage.resolve(id)       // mark as resolved
await storage.getScreenshot(id) // Buffer | null

License

MIT

Available Tools

3 tools
get_all_pendingA

Get all pending (unresolved) annotations from the UI. Returns annotation metadata including comment, element, page URL, and severity. Does not include screenshot data — use get_screenshot for that.

Inputs: no named parameters.

get_screenshotA

Get the screenshot image for a specific annotation by ID.

Inputs: id (required).

resolveA

Mark an annotation as resolved. This removes the marker from the browser on next page load.

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing pending annotations, fetching a screenshot by ID, and resolving an annotation. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    Names are mostly consistent with verb_noun pattern: get_all_pending, get_screenshot, but resolve is a bare verb lacking an object. Minor deviation does not hurt readability.

    Tool Count4/5

    Three tools is a compact set for a narrow domain (annotation review and resolution). It feels slightly thin, but each tool is necessary and the scope is well-defined.

    Completeness4/5

    The set covers the core workflow of listing pending annotations, viewing details (screenshot), and resolving them. A minor gap is lack of access to resolved annotations, but it's not essential for the intended use.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers