instruckt-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@instruckt-mcp show my pending annotations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpRelated MCP server: Lens
Quick Start
Pick your setup below — each section is self-contained.
Setup | Use when |
App Router route handler | |
Dev-server middleware via | |
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 |
| Base path for the endpoints (trailing slashes are trimmed) |
dir | string |
| 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 |
| Returns all unresolved annotations — comment, element, page URL, severity |
| Returns the screenshot image for a specific annotation by ID |
| Marks an annotation as resolved; the instruckt widget removes the marker on its next poll |
How It Works
instruckt runs in your app and captures annotations with optional screenshots
Annotations are posted to your API endpoint and stored as JSON on disk
Your AI agent connects via MCP and calls
get_all_pendingto see what needs fixingThe agent reads the feedback, inspects screenshots with
get_screenshot, and makes code changesWhen 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 | nullLicense
MIT
Available Tools
3 toolsget_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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP Server for an Agent Task Marketplace
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for MarkItUp's AI image-annotation pipeline. Generate polished marketing-visual variations of any screenshot, regenerate, AI outpaint, and remove backgrounds — powered by Claude analysis + Gemini rendering.536 npm2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for visual feedback, video direction, and QA assertions on web pages, enabling AI agents to read, reply, and resolve annotations in real time.6MIT
- FlicenseNot gradedqualityBmaintenanceMCP server that exposes web page annotations to AI coding agents, enabling automated implementation of visual feedback and design tweaks.1 npm201-
- AlicenseNot gradedqualityDmaintenanceA MCP server that enables AI coding agents to consume structured UI feedback via click-to-annotate, supporting issue types and severity levels.MIT