ui-annotator-mcp

Instructions

Implementation Reference

• src/index.js:33-57 (handler)

  The 'annotate' tool registration and handler implementation. It takes a target URL, constructs a proxied version of it, and returns the instructions for the user.

  mcp.tool(
    'annotate',
    'Open a web page with hover annotations. Returns a proxy URL that adds interactive element labels to any page. User opens this URL in any browser to see annotations on hover.',
    {
      url: z.string().describe('The target URL to annotate, e.g. "http://localhost:3847" or "localhost:3847"'),
    },
    async ({ url }) => {
      let target = url;
      if (!target.startsWith('http')) target = 'http://' + target;
      let parsed;
      try {
        parsed = new URL(target);
      } catch(e) {
        return { content: [{ type: 'text', text: 'Invalid URL: ' + url }], isError: true };
      }
  
      const proxyUrl = `http://localhost:${PROXY_PORT}/${parsed.host}${parsed.pathname}`;
      return {
        content: [{
          type: 'text',
          text: `Annotated URL ready:\n\n${proxyUrl}\n\nOpen this URL in any browser. Hover over any element to see its name, CSS selector, and dimensions. The annotation works in Chrome, Firefox, Safari — any browser.\n\nOnce the user has the page open, use get_elements to see what UI elements are on the page.`,
        }],
      };
    }
  );