@gxp-dev/tools 2.0.81 → 2.0.83

package/mcp/lib/uikit-tools.js

@@ -0,0 +1,181 @@
+/**
+ * MCP tools for @gxp-dev/uikit introspection.
+ *
+ *   - list_uikit_components : enumerate components exported by the version
+ *     of @gxp-dev/uikit installed in the *plugin project's* node_modules
+ *     (not the toolkit's). Resolves the package relative to process.cwd(),
+ *     parses named exports out of dist/index.d.ts, and returns sorted
+ *     PascalCase names plus the package version.
+ *
+ * We parse the .d.ts with a regex pair (no TS AST) because the file is the
+ * built output and is shaped by the package's own build, not by us. Edge
+ * cases that the regex misses (e.g. nested namespace exports) are
+ * acceptable: the agent gets a strong starting set and can fall back to
+ * docs_search for anything unusual.
+ */
+
+const fs = require("fs")
+const path = require("path")
+
+function contentResult(obj) {
+	return {
+		content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+	}
+}
+
+/**
+ * Resolve @gxp-dev/uikit from the given cwd. Returns { root, pkg } where
+ * root is the absolute path to the uikit package directory and pkg is the
+ * parsed package.json, or null if uikit is not installed at any level.
+ *
+ * We mimic Node's node_modules walk-up rather than calling
+ * require.resolve("@gxp-dev/uikit/...") because the uikit's package.json
+ * declares a strict `exports` field with only `import` and `types`
+ * conditions. From a CJS context, require.resolve fails against that
+ * exports map even though the directory exists on disk. Walking the
+ * filesystem directly sidesteps it and works under npm, pnpm (where
+ * @gxp-dev/uikit is a symlink into .pnpm), and yarn workspaces.
+ */
+function resolveUikit(cwd = process.cwd()) {
+	let dir = path.resolve(cwd)
+	while (dir) {
+		const candidate = path.join(dir, "node_modules", "@gxp-dev", "uikit")
+		const pkgPath = path.join(candidate, "package.json")
+		if (fs.existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
+				if (pkg && pkg.name === "@gxp-dev/uikit") {
+					return { root: candidate, pkg }
+				}
+			} catch {
+				// malformed package.json — keep walking
+			}
+		}
+		const parent = path.dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return null
+}
+
+/**
+ * Pull named exports out of a .d.ts source string. Picks up:
+ *   - export declare const/let/var Foo
+ *   - export declare function Foo
+ *   - export declare class Foo
+ *   - export declare interface Foo
+ *   - export declare type Foo
+ *   - export declare enum Foo
+ *   - export { Foo, Bar as Baz }
+ */
+function parseNamedExports(source) {
+	const names = new Set()
+
+	const declRe =
+		/export\s+(?:declare\s+)?(?:const|let|var|function|class|interface|type|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g
+	let m
+	while ((m = declRe.exec(source)) !== null) {
+		names.add(m[1])
+	}
+
+	const braceRe = /export\s*\{([^}]+)\}/g
+	while ((m = braceRe.exec(source)) !== null) {
+		const inner = m[1]
+		for (const rawPart of inner.split(",")) {
+			const part = rawPart.trim()
+			if (!part) continue
+			const aliasMatch = part.match(
+				/^[A-Za-z_$][A-Za-z0-9_$]*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)/,
+			)
+			if (aliasMatch) {
+				names.add(aliasMatch[1])
+				continue
+			}
+			const nameMatch = part.match(/^([A-Za-z_$][A-Za-z0-9_$]*)/)
+			if (nameMatch) names.add(nameMatch[1])
+		}
+	}
+
+	return Array.from(names)
+}
+
+function listUikitComponents({ filter, cwd } = {}) {
+	const resolved = resolveUikit(cwd || process.cwd())
+	if (!resolved) {
+		return {
+			ok: false,
+			error:
+				"Could not resolve @gxp-dev/uikit from the current project. Install it with `npm install @gxp-dev/uikit` and re-run mcp-serve from the plugin project root.",
+		}
+	}
+	const { root, pkg } = resolved
+	const dtsPath = path.join(root, "dist", "index.d.ts")
+	if (!fs.existsSync(dtsPath)) {
+		return {
+			ok: false,
+			error: `@gxp-dev/uikit is installed at ${root} but dist/index.d.ts is missing. The package may not have been built.`,
+			resolved: root,
+		}
+	}
+
+	const src = fs.readFileSync(dtsPath, "utf-8")
+	const all = parseNamedExports(src)
+	const pascal = all.filter((n) => /^[A-Z]/.test(n)).sort()
+
+	let filtered = pascal
+	if (filter) {
+		const f = String(filter).toLowerCase()
+		filtered = pascal.filter((n) => n.toLowerCase().includes(f))
+	}
+
+	return {
+		ok: true,
+		package: {
+			name: pkg.name,
+			version: pkg.version || null,
+			root,
+		},
+		count: filtered.length,
+		components: filtered,
+	}
+}
+
+const UIKIT_TOOLS = [
+	{
+		name: "list_uikit_components",
+		description:
+			"Enumerate components exported by the @gxp-dev/uikit package installed in the current plugin project. Reads named exports from the built dist/index.d.ts and returns the PascalCase names plus the package version. Resolves uikit relative to the project (process.cwd()), not the toolkit, so the agent sees exactly what the project can import. Pass `filter` for a case-insensitive substring match.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				filter: {
+					type: "string",
+					description:
+						"Case-insensitive substring filter applied to component names.",
+				},
+			},
+		},
+	},
+]
+
+async function handleUikitToolCall(name, args = {}) {
+	switch (name) {
+		case "list_uikit_components":
+			return contentResult(listUikitComponents(args))
+		default:
+			throw new Error(`Unknown uikit tool: ${name}`)
+	}
+}
+
+function isUikitTool(name) {
+	return UIKIT_TOOLS.some((t) => t.name === name)
+}
+
+module.exports = {
+	UIKIT_TOOLS,
+	handleUikitToolCall,
+	isUikitTool,
+	listUikitComponents,
+	parseNamedExports,
+	resolveUikit,
+}

package/mcp/mcp-serve.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * GxP MCP Server (stdio).
+ *
+ * Primary bin: `mcp-serve`.
+ *
+ * Speaks Model Context Protocol over stdin/stdout using the official
+ * @modelcontextprotocol/sdk's StdioServerTransport. The full tool surface
+ * and wiring live in ./lib/server.js so this file stays a thin entry point.
+ *
+ * Usage:
+ *   mcp-serve
+ *   node mcp/mcp-serve.js
+ *
+ * Configure in your AI tool's MCP settings to enable API-aware,
+ * schema-aware, test-aware assistance inside plugin projects.
+ */
+
+const { startServer } = require("./lib/server")
+
+startServer().catch((err) => {
+	console.error(err && err.stack ? err.stack : err)
+	process.exit(1)
+})

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.81",
+	"version": "2.0.83",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {
@@ -39,6 +39,7 @@
 	},
 	"bin": {
 		"gxdev": "bin/gx-devtools.js",
+		"mcp-serve": "mcp/mcp-serve.js",
 		"gxp-api-server": "mcp/gxp-api-server.js"
 	},
 	"keywords": [
@@ -57,6 +58,7 @@
 	"dependencies": {
 		"@faker-js/faker": "^9.9.0",
 		"@fal-works/esbuild-plugin-global-externals": "^2.1.2",
+		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@vitejs/plugin-vue": "^6.0.6",
 		"adm-zip": "^0.5.17",
 		"ajv": "^8.18.0",

package/runtime/vite.config.js

@@ -481,7 +481,7 @@ export default defineConfig(async (ctx) => {
 				],
 				name: libName,
 				fileName: (format) => `plugin.${format}.js`,
-				cssFileName: "style.css",
+				cssFileName: "style",
 				formats: ["es"],
 			},
 			rollupOptions: {

package/template/.claude/agents/gxp-developer.md

@@ -28,7 +28,7 @@ Ask clarifying questions. Don't guess — a single clarification prevents a larg
 
 The `gxp-api` MCP server is your source of truth for the platform. Never invent endpoints or event names.
 
-**Before anything else, confirm the MCP is live** — call `api_list_tags`. The server is configured in `.mcp.json` at the project root and provided by the `gxp-api-server` binary that ships with `@gxp-dev/tools` (on PATH; verify with `which gxp-api-server`). If the `api_*` / `config_*` / `docs_*` tools aren't available, tell the user to run `claude mcp add gxp-api gxp-api-server` and restart the session. Do not proceed without it.
+**Before anything else, confirm the MCP is live** — call `api_list_tags`. The server is configured in `.mcp.json` at the project root and provided by the `mcp-serve` binary that ships with `@gxp-dev/tools` (on PATH; verify with `which mcp-serve`). If the `api_*` / `config_*` / `docs_*` tools aren't available, tell the user to run `claude mcp add gxp-api mcp-serve` and restart the session. Do not proceed without it.
 
 **API discovery:**
 

package/template/AGENTS.md

@@ -21,7 +21,7 @@ Ask clarifying questions instead of guessing. A 30-second question beats a 30-mi
 
 Use the `gxp-api` MCP server to ground the implementation in the real platform — never invent endpoints or event names.
 
-**Verify the MCP is live before planning anything** by calling `api_list_tags`. The server is defined in `.mcp.json` at the project root and provided by the `gxp-api-server` binary that ships with `@gxp-dev/tools` (on PATH — check with `which gxp-api-server`). If the `api_*` / `config_*` / `docs_*` tools aren't available, tell the user to run `claude mcp add gxp-api gxp-api-server` (or `codex mcp add …` / add it to `~/.gemini/settings.json`) and restart the session. Do not proceed without the MCP.
+**Verify the MCP is live before planning anything** by calling `api_list_tags`. The server is defined in `.mcp.json` at the project root and provided by the `mcp-serve` binary that ships with `@gxp-dev/tools` (on PATH — check with `which mcp-serve`). If the `api_*` / `config_*` / `docs_*` tools aren't available, tell the user to run `claude mcp add gxp-api mcp-serve` (or `codex mcp add …` / add it to `~/.gemini/settings.json`) and restart the session. Do not proceed without the MCP.
 
 - **Find endpoints** — `api_list_tags`, `api_list_operation_ids` (optionally scoped by tag), `search_api_endpoints` (keyword).
 - **Inspect a specific endpoint** — `api_get_operation_parameters`, `get_endpoint_details`.

package/template/GEMINI.md

@@ -18,7 +18,7 @@ Before writing anything, clarify with the client:
 
 Ground the implementation in real platform endpoints and events. Do not invent API paths or event names.
 
-**Verify the MCP is live first** — call `api_list_tags`. The server is defined in `.gemini/settings.json` at the project root and provided by the `gxp-api-server` binary that ships with `@gxp-dev/tools` (on PATH). If the tools aren't available, tell the user to add `gxp-api` to `~/.gemini/settings.json` under `mcpServers` with command `gxp-api-server`, then restart the session.
+**Verify the MCP is live first** — call `api_list_tags`. The server is defined in `.gemini/settings.json` at the project root and provided by the `mcp-serve` binary that ships with `@gxp-dev/tools` (on PATH). If the tools aren't available, tell the user to add `gxp-api` to `~/.gemini/settings.json` under `mcpServers` with command `mcp-serve`, then restart the session.
 
 - Endpoints — `api_list_tags`, `api_list_operation_ids`, `search_api_endpoints`, `api_get_operation_parameters`, `get_endpoint_details`.
 - Find by payload shape — `api_find_endpoints_by_schema`.

package/template/gemini/settings.json

@@ -1,7 +1,7 @@
 {
 	"mcpServers": {
 		"gxp-api": {
-			"command": "gxp-api-server",
+			"command": "mcp-serve",
 			"args": []
 		}
 	}

package/template/mcp.json

@@ -1,7 +1,7 @@
 {
 	"mcpServers": {
 		"gxp-api": {
-			"command": "gxp-api-server",
+			"command": "mcp-serve",
 			"args": []
 		}
 	}