@agent-eyes/agent-eyes-mcp 0.0.2

package/README.md

@@ -0,0 +1,35 @@
+# agent-eyes-mcp
+
+MCP server for Agent Eyes. It exposes two tools:
+
+- `get_selected_context`
+  Reads `GET /context/selected` from the local Agent Eyes service.
+- `ensure_agents_rule`
+  Creates or updates `AGENTS.md` in the target project root with the Agent Eyes workflow rule.
+
+## Install
+
+```bash
+pnpm add -D agent-eyes-mcp
+```
+
+## Configure MCP client
+
+Example stdio config:
+
+```json
+{
+  "mcpServers": {
+    "agent-eyes": {
+      "command": "npx",
+      "args": ["agent-eyes-mcp"]
+    }
+  }
+}
+```
+
+## Tool notes
+
+`get_selected_context` expects the local Agent Eyes service to be running, usually at `http://127.0.0.1:5678`.
+
+`ensure_agents_rule` writes `AGENTS.md` in the provided `projectRoot`, or in the current working directory when omitted.

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const require_src = require("./src-D-OQOBYj.js");
+require_src.startAgentEyesMcpServer().catch((error) => {
+	console.error("[agent-eyes-mcp] failed to start:", error);
+	process.exit(1);
+});
+process.stdin.resume();

package/dist/cli.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { n as startAgentEyesMcpServer } from "./src-DMIK-7Qu.mjs";
+startAgentEyesMcpServer().catch((error) => {
+	console.error("[agent-eyes-mcp] failed to start:", error);
+	process.exit(1);
+});
+process.stdin.resume();

package/dist/index.js

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-D-OQOBYj.js");
+exports.createAgentEyesMcpServer = require_src.createAgentEyesMcpServer;
+exports.startAgentEyesMcpServer = require_src.startAgentEyesMcpServer;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as startAgentEyesMcpServer, t as createAgentEyesMcpServer } from "./src-DMIK-7Qu.mjs";
+export { createAgentEyesMcpServer, startAgentEyesMcpServer };

package/dist/src-D-OQOBYj.js

@@ -0,0 +1,214 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+let fs = require("fs");
+fs = __toESM(fs);
+let path = require("path");
+path = __toESM(path);
+let __modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let __modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let zod = require("zod");
+var DEFAULT_BASE_URL = "http://127.0.0.1:5678";
+var agentEyesRuleSection = `## Agent Eyes Workflow
+
+For any task that may modify UI, DOM structure, styles, component behavior, page content, or selected elements:
+
+1. First verify that \`code-inspector-plugin\` is installed in this project.
+2. Before making any code change, request \`GET http://127.0.0.1:5678/context/selected\`.
+3. If the response contains \`data: null\`, do not guess the target code.
+4. Ask the user to open Agent Eyes, select the target element, and keep the selection panel open.
+5. Only after a non-null context is returned may you use that context to locate and modify code precisely.
+
+Prefer multi-selection fields when available:
+
+- \`activeSelectionId\`
+- \`selections\` / \`contexts\`
+- \`data.active\` and \`data.selections\`
+
+If only single-selection fields exist, use \`filePath\`, \`line\`, \`column\`, \`elementName\`, \`dom\`, and \`domPath\`.
+
+If \`code-inspector-plugin\` is missing:
+
+- \`pnpm add -D code-inspector-plugin\`
+- \`yarn add -D code-inspector-plugin\`
+- \`npm i -D code-inspector-plugin\`
+
+Then add the minimal bundler configuration required by the current project before continuing.
+`;
+function detectPackageManager(rootDir) {
+	if (fs.default.existsSync(path.default.join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.default.existsSync(path.default.join(rootDir, "yarn.lock"))) return "yarn";
+	if (fs.default.existsSync(path.default.join(rootDir, "package-lock.json"))) return "npm";
+	return "npm";
+}
+function readProjectPackageMeta(rootDir) {
+	const packageJsonPath = path.default.join(rootDir, "package.json");
+	if (!fs.default.existsSync(packageJsonPath)) return {
+		packageJsonPath,
+		packageExists: false,
+		pluginInstalled: false
+	};
+	try {
+		const pkg = JSON.parse(fs.default.readFileSync(packageJsonPath, "utf-8"));
+		return {
+			packageJsonPath,
+			packageExists: true,
+			pluginInstalled: !!{
+				...pkg?.dependencies || {},
+				...pkg?.devDependencies || {}
+			}["code-inspector-plugin"]
+		};
+	} catch {
+		return {
+			packageJsonPath,
+			packageExists: true,
+			pluginInstalled: false
+		};
+	}
+}
+function getAgentsFileStatus(rootDir) {
+	const agentsPath = path.default.join(rootDir, "AGENTS.md");
+	const exists = fs.default.existsSync(agentsPath);
+	const content = exists ? fs.default.readFileSync(agentsPath, "utf-8") : "";
+	return {
+		agentsPath,
+		exists,
+		hasRule: content.includes("## Agent Eyes Workflow"),
+		content
+	};
+}
+async function getSelectedContext(baseUrl) {
+	const response = await fetch(`${baseUrl.replace(/\/$/, "")}/context/selected`, { headers: { Accept: "application/json" } });
+	if (!response.ok) throw new Error(`request failed: ${response.status}`);
+	return response.json();
+}
+function normalizeSelectedContextPayload(payload) {
+	const topSelections = Array.isArray(payload?.selections) ? payload.selections : [];
+	const topContexts = Array.isArray(payload?.contexts) ? payload.contexts : [];
+	const dataSelections = Array.isArray(payload?.data?.selections) ? payload.data.selections : [];
+	const dataContexts = Array.isArray(payload?.data?.contexts) ? payload.data.contexts : [];
+	const contexts = topContexts.length > 0 ? topContexts : topSelections.length > 0 ? topSelections : dataContexts.length > 0 ? dataContexts : dataSelections.length > 0 ? dataSelections : payload?.data?.filePath ? [payload.data] : [];
+	const activeSelectionId = String(payload?.activeSelectionId || payload?.data?.activeSelectionId || payload?.active?.id || payload?.data?.active?.id || "");
+	const active = payload?.active || payload?.data?.active || contexts.find((item) => item?.id && item.id === activeSelectionId) || payload?.data || contexts[0] || null;
+	return {
+		...payload,
+		data: payload?.data ?? active,
+		active,
+		activeSelectionId: activeSelectionId || active?.id || "",
+		contexts,
+		selections: contexts
+	};
+}
+function ensureAgentsRule(rootDir) {
+	const agentsMeta = getAgentsFileStatus(rootDir);
+	let nextContent = "";
+	if (!agentsMeta.exists) nextContent = `# Project Agent Rules\n\n${agentEyesRuleSection}\n`;
+	else nextContent = agentsMeta.hasRule ? agentsMeta.content.replace(/## Agent Eyes Workflow[\s\S]*$/m, agentEyesRuleSection.trimEnd()) : `${agentsMeta.content.trimEnd()}\n\n${agentEyesRuleSection}\n`;
+	fs.default.writeFileSync(agentsMeta.agentsPath, nextContent, "utf-8");
+	return {
+		agentsPath: agentsMeta.agentsPath,
+		created: !agentsMeta.exists,
+		updated: agentsMeta.exists
+	};
+}
+function createAgentEyesMcpServer() {
+	const server = new __modelcontextprotocol_sdk_server_mcp_js.McpServer({
+		name: "agent-eyes-mcp",
+		version: "0.0.1"
+	});
+	server.registerTool("get_selected_context", {
+		description: "Get the currently selected Agent Eyes code context from the local service. Use before any precise UI or page code modification.",
+		inputSchema: { baseUrl: zod.z.string().optional().describe("Agent Eyes local service base URL, default http://127.0.0.1:5678") }
+	}, async ({ baseUrl }) => {
+		try {
+			const normalized = normalizeSelectedContextPayload(await getSelectedContext(baseUrl || DEFAULT_BASE_URL));
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(normalized, null, 2)
+				}],
+				structuredContent: normalized
+			};
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: String(error instanceof Error ? error.message : error)
+				}],
+				isError: true
+			};
+		}
+	});
+	server.registerTool("ensure_agents_rule", {
+		description: "Create or update AGENTS.md in the project root with the Agent Eyes workflow rule.",
+		inputSchema: { projectRoot: zod.z.string().optional().describe("Project root directory. Defaults to current working directory.") }
+	}, async ({ projectRoot }) => {
+		const rootDir = path.default.resolve(projectRoot || process.cwd());
+		try {
+			const packageMeta = readProjectPackageMeta(rootDir);
+			const packageManager = detectPackageManager(rootDir);
+			const installCommand = packageManager === "pnpm" ? "pnpm add -D code-inspector-plugin" : packageManager === "yarn" ? "yarn add -D code-inspector-plugin" : "npm i -D code-inspector-plugin";
+			const agentsResult = ensureAgentsRule(rootDir);
+			const result = {
+				rootDir,
+				packageJsonPath: packageMeta.packageJsonPath,
+				packageExists: packageMeta.packageExists,
+				pluginInstalled: packageMeta.pluginInstalled,
+				packageManager,
+				installCommand,
+				...agentsResult
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				structuredContent: result
+			};
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: String(error instanceof Error ? error.message : error)
+				}],
+				isError: true
+			};
+		}
+	});
+	return server;
+}
+async function startAgentEyesMcpServer() {
+	const server = createAgentEyesMcpServer();
+	const transport = new __modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport();
+	await server.connect(transport);
+	return server;
+}
+Object.defineProperty(exports, "createAgentEyesMcpServer", {
+	enumerable: true,
+	get: function() {
+		return createAgentEyesMcpServer;
+	}
+});
+Object.defineProperty(exports, "startAgentEyesMcpServer", {
+	enumerable: true,
+	get: function() {
+		return startAgentEyesMcpServer;
+	}
+});

package/dist/src-DMIK-7Qu.mjs

@@ -0,0 +1,181 @@
+import fs from "fs";
+import path from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var DEFAULT_BASE_URL = "http://127.0.0.1:5678";
+var agentEyesRuleSection = `## Agent Eyes Workflow
+
+For any task that may modify UI, DOM structure, styles, component behavior, page content, or selected elements:
+
+1. First verify that \`code-inspector-plugin\` is installed in this project.
+2. Before making any code change, request \`GET http://127.0.0.1:5678/context/selected\`.
+3. If the response contains \`data: null\`, do not guess the target code.
+4. Ask the user to open Agent Eyes, select the target element, and keep the selection panel open.
+5. Only after a non-null context is returned may you use that context to locate and modify code precisely.
+
+Prefer multi-selection fields when available:
+
+- \`activeSelectionId\`
+- \`selections\` / \`contexts\`
+- \`data.active\` and \`data.selections\`
+
+If only single-selection fields exist, use \`filePath\`, \`line\`, \`column\`, \`elementName\`, \`dom\`, and \`domPath\`.
+
+If \`code-inspector-plugin\` is missing:
+
+- \`pnpm add -D code-inspector-plugin\`
+- \`yarn add -D code-inspector-plugin\`
+- \`npm i -D code-inspector-plugin\`
+
+Then add the minimal bundler configuration required by the current project before continuing.
+`;
+function detectPackageManager(rootDir) {
+	if (fs.existsSync(path.join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.existsSync(path.join(rootDir, "yarn.lock"))) return "yarn";
+	if (fs.existsSync(path.join(rootDir, "package-lock.json"))) return "npm";
+	return "npm";
+}
+function readProjectPackageMeta(rootDir) {
+	const packageJsonPath = path.join(rootDir, "package.json");
+	if (!fs.existsSync(packageJsonPath)) return {
+		packageJsonPath,
+		packageExists: false,
+		pluginInstalled: false
+	};
+	try {
+		const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+		return {
+			packageJsonPath,
+			packageExists: true,
+			pluginInstalled: !!{
+				...pkg?.dependencies || {},
+				...pkg?.devDependencies || {}
+			}["code-inspector-plugin"]
+		};
+	} catch {
+		return {
+			packageJsonPath,
+			packageExists: true,
+			pluginInstalled: false
+		};
+	}
+}
+function getAgentsFileStatus(rootDir) {
+	const agentsPath = path.join(rootDir, "AGENTS.md");
+	const exists = fs.existsSync(agentsPath);
+	const content = exists ? fs.readFileSync(agentsPath, "utf-8") : "";
+	return {
+		agentsPath,
+		exists,
+		hasRule: content.includes("## Agent Eyes Workflow"),
+		content
+	};
+}
+async function getSelectedContext(baseUrl) {
+	const response = await fetch(`${baseUrl.replace(/\/$/, "")}/context/selected`, { headers: { Accept: "application/json" } });
+	if (!response.ok) throw new Error(`request failed: ${response.status}`);
+	return response.json();
+}
+function normalizeSelectedContextPayload(payload) {
+	const topSelections = Array.isArray(payload?.selections) ? payload.selections : [];
+	const topContexts = Array.isArray(payload?.contexts) ? payload.contexts : [];
+	const dataSelections = Array.isArray(payload?.data?.selections) ? payload.data.selections : [];
+	const dataContexts = Array.isArray(payload?.data?.contexts) ? payload.data.contexts : [];
+	const contexts = topContexts.length > 0 ? topContexts : topSelections.length > 0 ? topSelections : dataContexts.length > 0 ? dataContexts : dataSelections.length > 0 ? dataSelections : payload?.data?.filePath ? [payload.data] : [];
+	const activeSelectionId = String(payload?.activeSelectionId || payload?.data?.activeSelectionId || payload?.active?.id || payload?.data?.active?.id || "");
+	const active = payload?.active || payload?.data?.active || contexts.find((item) => item?.id && item.id === activeSelectionId) || payload?.data || contexts[0] || null;
+	return {
+		...payload,
+		data: payload?.data ?? active,
+		active,
+		activeSelectionId: activeSelectionId || active?.id || "",
+		contexts,
+		selections: contexts
+	};
+}
+function ensureAgentsRule(rootDir) {
+	const agentsMeta = getAgentsFileStatus(rootDir);
+	let nextContent = "";
+	if (!agentsMeta.exists) nextContent = `# Project Agent Rules\n\n${agentEyesRuleSection}\n`;
+	else nextContent = agentsMeta.hasRule ? agentsMeta.content.replace(/## Agent Eyes Workflow[\s\S]*$/m, agentEyesRuleSection.trimEnd()) : `${agentsMeta.content.trimEnd()}\n\n${agentEyesRuleSection}\n`;
+	fs.writeFileSync(agentsMeta.agentsPath, nextContent, "utf-8");
+	return {
+		agentsPath: agentsMeta.agentsPath,
+		created: !agentsMeta.exists,
+		updated: agentsMeta.exists
+	};
+}
+function createAgentEyesMcpServer() {
+	const server = new McpServer({
+		name: "agent-eyes-mcp",
+		version: "0.0.1"
+	});
+	server.registerTool("get_selected_context", {
+		description: "Get the currently selected Agent Eyes code context from the local service. Use before any precise UI or page code modification.",
+		inputSchema: { baseUrl: z.string().optional().describe("Agent Eyes local service base URL, default http://127.0.0.1:5678") }
+	}, async ({ baseUrl }) => {
+		try {
+			const normalized = normalizeSelectedContextPayload(await getSelectedContext(baseUrl || DEFAULT_BASE_URL));
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(normalized, null, 2)
+				}],
+				structuredContent: normalized
+			};
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: String(error instanceof Error ? error.message : error)
+				}],
+				isError: true
+			};
+		}
+	});
+	server.registerTool("ensure_agents_rule", {
+		description: "Create or update AGENTS.md in the project root with the Agent Eyes workflow rule.",
+		inputSchema: { projectRoot: z.string().optional().describe("Project root directory. Defaults to current working directory.") }
+	}, async ({ projectRoot }) => {
+		const rootDir = path.resolve(projectRoot || process.cwd());
+		try {
+			const packageMeta = readProjectPackageMeta(rootDir);
+			const packageManager = detectPackageManager(rootDir);
+			const installCommand = packageManager === "pnpm" ? "pnpm add -D code-inspector-plugin" : packageManager === "yarn" ? "yarn add -D code-inspector-plugin" : "npm i -D code-inspector-plugin";
+			const agentsResult = ensureAgentsRule(rootDir);
+			const result = {
+				rootDir,
+				packageJsonPath: packageMeta.packageJsonPath,
+				packageExists: packageMeta.packageExists,
+				pluginInstalled: packageMeta.pluginInstalled,
+				packageManager,
+				installCommand,
+				...agentsResult
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				structuredContent: result
+			};
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: String(error instanceof Error ? error.message : error)
+				}],
+				isError: true
+			};
+		}
+	});
+	return server;
+}
+async function startAgentEyesMcpServer() {
+	const server = createAgentEyesMcpServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	return server;
+}
+export { startAgentEyesMcpServer as n, createAgentEyesMcpServer as t };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agent-eyes/agent-eyes-mcp",
+  "version": "0.0.2",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "typings": "./types/index.d.ts",
+  "bin": {
+    "agent-eyes-mcp": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "git@github.com:zh-lx/code-inspector.git",
+  "author": "zh-lx <18366276315@163.com>",
+  "license": "MIT",
+  "homepage": "https://inspector.fe-dev.cn/en",
+  "description": "MCP server for Agent Eyes selected context and AGENTS.md setup.",
+  "files": [
+    "dist",
+    "types",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "keywords": [
+    "mcp",
+    "agent-eyes",
+    "code-inspector",
+    "model-context-protocol"
+  ],
+  "bugs": {
+    "url": "https://github.com/zh-lx/code-inspector/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.3.3",
+    "typescript": "^5.5.4",
+    "vite": "^4.3.9"
+  },
+  "scripts": {
+    "clear": "rimraf ./dist && rimraf ./types",
+    "build": "node ./scripts/build.mjs",
+    "pub": "pnpm publish",
+    "pub:beta": "pnpm publish --tag beta"
+  }
+}

package/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createAgentEyesMcpServer(): McpServer;
+export declare function startAgentEyesMcpServer(): Promise<McpServer>;