@eyemark/mcp 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,4 @@
1
+ Copyright (c) 2026 Pablo Monteoliva. All rights reserved.
2
+
3
+ This software is not open source. No license to use, copy, modify, or distribute it is
4
+ granted except by written agreement with the copyright holder.
package/README.md CHANGED
@@ -1,3 +1,19 @@
1
- # Temporary Holding Version
1
+ # @eyemark/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Eyemark for your coding agent, in one MCP server: the design principles, `plan_feature`, the shape
4
+ and critique prompts and reviews of your previews, from Eyemark's hosted server, and `measure`, the
5
+ rendered checks on your dev server, run on your machine. Your dev server never leaves it.
6
+
7
+ ```bash
8
+ claude mcp add --scope user eyemark -e EYEMARK_TOKEN=<your Eyemark MCP token> -- npx -y @eyemark/mcp@latest
9
+ ```
10
+
11
+ Other clients: run `npx -y @eyemark/mcp@latest` with `EYEMARK_TOKEN` in its environment.
12
+
13
+ Then ask your agent to measure `http://localhost:3000` (or whichever port your dev server uses).
14
+ The first time, it downloads the browser it measures with (about a minute). It answers PASS or
15
+ FAIL with the fixes to make first. Node 22 or later.
16
+
17
+ The checks come from Eyemark on each call (nothing is stored on disk), so you always run the newest
18
+ ones with nothing to update. Offline, `measure` keeps working once it has run; the rest comes back
19
+ when Eyemark can be reached.
package/bin/eyemark.js ADDED
@@ -0,0 +1,183 @@
1
+ #!/usr/bin/env node
2
+ // eyemark: Eyemark for your coding agent, as one MCP server on stdio. measure runs here: on each
3
+ // call it asks the hosted service for the current engine with your Eyemark MCP token, keeps it in
4
+ // memory (never on disk), and runs it on this machine, so your dev server never leaves it. Every
5
+ // other request (the principles, plan_feature, the prompts, reviews) goes to the hosted server
6
+ // as it is, so a new hosted tool reaches you with no update. Offline, measure keeps working.
7
+
8
+ import { spawn } from "node:child_process";
9
+ import fs from "node:fs";
10
+ import { createRequire } from "node:module";
11
+ import path from "node:path";
12
+ import readline from "node:readline";
13
+
14
+ const BASE = (process.env.EYEMARK_URL || "https://mcp.eyemark.dev").replace(/\/+$/, "");
15
+ const ENDPOINT = process.env.EYEMARK_ENGINE_URL || `${BASE}/api/engine`;
16
+ const VERSION = "0.2.0";
17
+ const RETRY_MS = Number(process.env.EYEMARK_RETRY_MS) || 30000;
18
+
19
+ // Shown until the engine loads, and when it can't: the same inputs the engine's tool takes.
20
+ const FALLBACK = {
21
+ name: "measure",
22
+ description: "Run Eyemark's rendered checks on the dev server on this machine (or any site, read-only), at desktop and phone width. Ends with PASS or FAIL and the fixes to make first.",
23
+ inputSchema: {
24
+ type: "object",
25
+ properties: {
26
+ url: { type: "string", description: "The dev server, e.g. http://localhost:3000." },
27
+ routes: { type: "array", items: { type: "string" }, description: "Routes to load. Defaults to [\"/\"]." },
28
+ only: { type: "array", items: { type: "string" }, description: "Keep only these checks or categories. Optional." },
29
+ },
30
+ required: ["url"],
31
+ },
32
+ };
33
+
34
+ // Until the hosted server answers: enough to work with measure alone.
35
+ const OFFLINE_INSTRUCTIONS =
36
+ "Eyemark is the designer for anything a person will see. Its hosted tools (principles, plan_feature, the shape and critique prompts, reviews) appear once Eyemark can be reached. Meanwhile: after building each part of a UI, call measure on the dev server (localhost) with the routes it touches, fix every error, and measure again until it passes before saying the work is done. A request to review or check a page on this machine is measure's.";
37
+
38
+ const token = () => {
39
+ const t = process.env.EYEMARK_TOKEN;
40
+ if (!t) throw new Error("Set EYEMARK_TOKEN to your Eyemark MCP token, then restart your agent.");
41
+ return t;
42
+ };
43
+
44
+ let engine;
45
+ let etag;
46
+
47
+ // The current engine: fetched when there's none yet or the service has a newer one. When the
48
+ // service can't be reached, the one already loaded keeps working.
49
+ async function load() {
50
+ let res;
51
+ try {
52
+ res = await fetch(ENDPOINT, { headers: { authorization: `Bearer ${token()}`, "x-eyemark-client": VERSION, ...(etag && engine ? { "if-none-match": etag } : {}) }, signal: AbortSignal.timeout(15000) });
53
+ } catch (e) {
54
+ if (engine) return engine;
55
+ throw new Error(`Couldn't reach Eyemark (${ENDPOINT}): ${e.cause?.code ?? e.message}. measure needs the internet to get its checks the first time.`);
56
+ }
57
+ if (res.status === 304 && engine) return engine;
58
+ if (res.status === 401) throw new Error("Eyemark refused the token in EYEMARK_TOKEN. Check it, or ask for a new one.");
59
+ if (!res.ok) {
60
+ if (engine) return engine;
61
+ throw new Error(`Eyemark answered ${res.status}. Try again in a minute.`);
62
+ }
63
+ const code = await res.text();
64
+ engine = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
65
+ etag = res.headers.get("etag") ?? undefined;
66
+ return engine;
67
+ }
68
+
69
+ // One JSON-RPC message to the hosted server; its reply's result or error, under our id.
70
+ async function forward(msg, timeout = 15000) {
71
+ let res;
72
+ try {
73
+ res = await fetch(BASE, {
74
+ method: "POST",
75
+ headers: { authorization: `Bearer ${token()}`, "content-type": "application/json", accept: "application/json", "x-eyemark-client": VERSION },
76
+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: msg.method, params: msg.params ?? {} }),
77
+ signal: AbortSignal.timeout(timeout),
78
+ });
79
+ } catch (e) {
80
+ throw new Error(`Couldn't reach Eyemark (${BASE}): ${e.cause?.code ?? e.message}. measure still works; the rest needs the internet.`);
81
+ }
82
+ if (res.status === 401) throw new Error("Eyemark refused the token in EYEMARK_TOKEN. Check it, or ask for a new one.");
83
+ if (!res.ok) throw new Error(`Eyemark answered ${res.status}. Try again in a minute.`);
84
+ const out = await res.json();
85
+ if (out.error) throw Object.assign(new Error(out.error.message), { rpc: out.error });
86
+ return out.result;
87
+ }
88
+
89
+ const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);
90
+ const text = (s) => ({ content: [{ type: "text", text: s }], isError: true });
91
+
92
+ // The hosted tools couldn't be listed: try again now and then, and tell the agent once they can.
93
+ let retrying;
94
+ function retryHosted() {
95
+ if (retrying) return;
96
+ retrying = setInterval(async () => {
97
+ try {
98
+ await forward({ method: "tools/list" }, 10000);
99
+ clearInterval(retrying);
100
+ retrying = undefined;
101
+ send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
102
+ send({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" });
103
+ } catch {
104
+ // Still offline: try again next time.
105
+ }
106
+ }, RETRY_MS);
107
+ retrying.unref();
108
+ }
109
+
110
+ // Chromium, downloaded by Playwright's own installer the first time measure needs it. Its output
111
+ // goes to stderr: stdout carries the protocol.
112
+ const require = createRequire(import.meta.url);
113
+ async function ensureBrowser(playwright, progressToken) {
114
+ if (fs.existsSync(playwright.chromium.executablePath())) return;
115
+ const cli = process.env.EYEMARK_PLAYWRIGHT_CLI || path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
116
+ if (progressToken !== undefined) send({ jsonrpc: "2.0", method: "notifications/progress", params: { progressToken, progress: 0, message: "Downloading the browser measure uses (once, about a minute)." } });
117
+ const code = await new Promise((resolve) => {
118
+ const child = spawn(process.execPath, [cli, "install", "chromium"], { stdio: ["ignore", "pipe", "inherit"] });
119
+ child.stdout.pipe(process.stderr);
120
+ child.on("error", () => resolve(-1));
121
+ child.on("exit", resolve);
122
+ });
123
+ if (code !== 0) throw new Error("Couldn't download the browser measure uses. Run `npx playwright install chromium`, then try again.");
124
+ }
125
+
126
+ async function handle(msg) {
127
+ const { id, method, params = {} } = msg;
128
+ const reply = (result) => ({ jsonrpc: "2.0", id, result });
129
+ const failed = (e) => (e.rpc ? { jsonrpc: "2.0", id, error: e.rpc } : { jsonrpc: "2.0", id, error: { code: -32603, message: e.message } });
130
+ switch (method) {
131
+ case "initialize": {
132
+ let instructions = OFFLINE_INSTRUCTIONS;
133
+ try {
134
+ instructions = (await forward(msg, 5000)).instructions ?? instructions;
135
+ } catch {
136
+ // Offline or refused: the short version, and the full one next time.
137
+ }
138
+ return reply({
139
+ protocolVersion: params.protocolVersion ?? "2025-06-18",
140
+ capabilities: { tools: { listChanged: true }, prompts: { listChanged: true } },
141
+ serverInfo: { name: "eyemark", version: VERSION },
142
+ instructions,
143
+ });
144
+ }
145
+ case "ping":
146
+ return reply({});
147
+ case "tools/list": {
148
+ const [local, hosted] = await Promise.allSettled([load(), forward(msg)]);
149
+ const measure = local.status === "fulfilled" ? local.value.TOOLS : [{ ...FALLBACK, description: `${FALLBACK.description} Not ready: ${local.reason.message}` }];
150
+ if (hosted.status === "rejected") retryHosted();
151
+ return reply({ tools: [...measure, ...(hosted.status === "fulfilled" ? hosted.value.tools : [])] });
152
+ }
153
+ case "prompts/list":
154
+ return forward(msg).then(reply, () => reply({ prompts: [] }));
155
+ case "tools/call":
156
+ if (params.name !== "measure") return forward(msg).then(reply, (e) => (e.rpc ? failed(e) : reply(text(`Error: ${e.message}`))));
157
+ try {
158
+ const playwright = await import("playwright");
159
+ const loaded = await load();
160
+ await ensureBrowser(playwright, params._meta?.progressToken);
161
+ return reply(await loaded.call("measure", params.arguments ?? {}, playwright, VERSION));
162
+ } catch (e) {
163
+ return reply(text(`Error: ${e.message}`));
164
+ }
165
+ default:
166
+ // Notifications get no reply; any other request is the hosted server's to answer.
167
+ if (id === undefined) return undefined;
168
+ return forward(msg).then(reply, failed);
169
+ }
170
+ }
171
+
172
+ const rl = readline.createInterface({ input: process.stdin });
173
+ rl.on("line", (line) => {
174
+ if (!line.trim()) return;
175
+ let msg;
176
+ try {
177
+ msg = JSON.parse(line);
178
+ } catch {
179
+ send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
180
+ return;
181
+ }
182
+ handle(msg).then((out) => out && send(out));
183
+ });
package/package.json CHANGED
@@ -1,6 +1,21 @@
1
1
  {
2
2
  "name": "@eyemark/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Eyemark for your coding agent: the design principles, plan_feature and reviews, and measure on your dev server, in one MCP server.",
5
+ "license": "SEE LICENSE IN LICENSE",
6
+ "type": "module",
7
+ "bin": {
8
+ "eyemark": "bin/eyemark.js"
9
+ },
10
+ "files": [
11
+ "bin",
12
+ "README.md",
13
+ "LICENSE"
14
+ ],
15
+ "engines": {
16
+ "node": ">=22"
17
+ },
18
+ "dependencies": {
19
+ "playwright": "1.63.0"
20
+ }
21
+ }