Instruckt

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

Quick Start

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

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:

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:

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