@quey/mcp

MCP server for Quey — a visual feedback bridge that connects a Chrome extension to AI coding agents. Select elements on any webpage, and your AI agent (Claude Code, Cursor, Codex) receives structured context about the element's styles, layout, and component identity.

Current architecture

Today, captures are stored in process-local memory inside src/store.ts. That means the HTTP bridge and the MCP stdio server only share state when they run in the same process. Because of that:

• the recommended project MCP entry still points at server
• http and mcp are advanced commands
• a future split to stdio-only project MCP requires shared persistence or IPC first

Quick start

1. Install

npm install -g @quey/mcp

2. Register with Claude Code

quey-mcp init

Or add manually to your project's .mcp.json:

{
  "mcpServers": {
    "quey": {
      "command": "npx",
      "args": ["@quey/mcp", "server"]
    }
  }
}

3. Start using

Install the Quey Chrome extension, select an element on any page, and your AI agent will receive the capture automatically.

CLI commands

quey-mcp [command]

| Command | Description | |---------|-------------| | server | Start HTTP + MCP in one process. Current recommended mode. | | http | Start the HTTP bridge only. Advanced / debugging. | | mcp | Start MCP stdio only. Advanced / programmatic. | | init | Register MCP server with Claude Code | | doctor | Check environment and connectivity | | help | Show usage information |

Environment variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | HTTP server port | 4747 | | TOOLBAR_AUTO_RUN | Enable automatic codex execution | 0 | | TOOLBAR_CODEX_CWD | Codebase path for codex exec | — | | TOOLBAR_CODEX_CMD | Override codex command | codex | | TOOLBAR_CODEX_FULL_AUTO | Disable --full-auto when set to 0 | 1 | | TOOLBAR_CODEX_MODEL | Optional model override | — |

MCP tools reference

These tools are available to AI agents via the Model Context Protocol:

| Tool | Description | |------|-------------| | quey_list_sessions | List all capture sessions with counts | | quey_get_session | Get a session with all its captures | | quey_get_pending | Get unacknowledged captures (optionally by session) | | quey_get_capture | Get full capture details including element context and thread | | quey_acknowledge | Mark a capture as seen/in-progress | | quey_resolve | Mark a capture as resolved with a summary | | quey_dismiss | Dismiss a capture with a reason | | quey_reply | Add a message to a capture's thread | | quey_watch | Block until new captures appear (for hands-free mode) |

HTTP API

The HTTP server receives captures from the Chrome extension and serves SSE events.

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | POST | /sessions | Create a new session | | GET | /sessions | List all sessions | | GET | /sessions/:id | Get session with captures | | POST | /sessions/:id/close | Close a session | | POST | /captures | Submit a capture from the extension | | GET | /captures | List captures (filter by ?session= or ?status=) | | GET | /captures/pending | Get pending captures | | GET | /captures/:id | Get a specific capture | | PATCH | /captures/:id | Update capture status | | POST | /captures/:id/thread | Add a thread message | | POST | /open-file | Open a file in Cursor IDE | | GET | /events | SSE event stream |

Auto-runner

Enable automatic execution when captures arrive:

TOOLBAR_AUTO_RUN=1 TOOLBAR_CODEX_CWD=/path/to/repo quey-mcp server

When a toolbar-agent-prompt capture is received, the server will automatically run codex exec - with the structured prompt.

Codex fast path

The Codex/OpenAI path now prefers deterministic direct-file edits over repo-wide discovery:

• the extension performs a final React source lookup immediately before handoff
• the MCP runner uses a smaller Codex-specific prompt when a concrete source file is available
• if no source file can be resolved, the run fails fast instead of sending Codex into a slow broad search

This keeps simple edit requests like text or color changes on the fastest available path.

Timing and progress signals

The auto-runner now emits activity events for the main Codex phases:

• target resolution
• snapshot preparation
• Codex process startup
• first Codex output
• diff finalization

These events are intended to make slow handoffs diagnosable in the extension UI and local logs instead of appearing as a single long "thinking" state.

Hands-free mode

Use quey_watch in a loop for a fully hands-free workflow. Add this to your project's CLAUDE.md:

## Quey workflow

Use the quey MCP tools to receive visual feedback:
1. Call `quey_watch` to wait for captures
2. When a capture arrives, call `quey_acknowledge`
3. Make the requested changes
4. Call `quey_resolve` with a summary
5. Loop back to step 1

Programmatic usage

import { startHttpServer, createMcpServer, startAutoRunner } from "@quey/mcp";

// Start the HTTP server on a custom port
await startHttpServer(8080);

// Start the auto-runner
startAutoRunner();

// Or create an MCP server instance for custom integration
const server = createMcpServer();

Local CLI

The companion quey CLI package now exposes:

• quey bridge start
• quey bridge doctor
• quey mcp add

These commands are thin wrappers around the provider's current combined-mode contract.

License

PolyForm Shield 1.0.0