@gxp-dev/tools 2.0.81 → 2.0.83

package/README.md

@@ -93,20 +93,24 @@ It does **not** overwrite your source files (`src/`, `theme-layouts/`, etc.).
 - **Config linting** — AJV-based JSON Schema validation of `configuration.json` (form-builder definitions) and `app-manifest.json` (plugin metadata + defaults).
 - **Pre-commit hook** — `.githooks/pre-commit` runs Prettier, ESLint, and the GxP linter on staged files; configured automatically via the `prepare` npm script.
 - **Unit testing** — Vitest + `@vue/test-utils` wired out of the box; scaffolded tests via the MCP server.
-- **MCP server** — 29 tools for AI coding assistants (see below).
+- **MCP server** — 33 tools for AI coding assistants (see below).
 - **AI scaffolding** — pre-wired configs for Claude Code, Codex, and Gemini during `init`.
 
 ## MCP Server for AI assistants
 
-The toolkit ships `gxp-api-server` (bin `@gxp-dev/tools/mcp/gxp-api-server.js`), an MCP server exposing 29 tools across five families. Point your AI assistant at it to get API-aware, schema-aware, test-aware help inside plugin projects:
+The toolkit ships `mcp-serve` (bin `@gxp-dev/tools/mcp/mcp-serve.js`), an MCP server exposing 33 tools across seven families. It speaks MCP over stdio via the official `@modelcontextprotocol/sdk` `StdioServerTransport`. Point your AI assistant at it to get API-aware, schema-aware, test-aware help inside plugin projects:
 
 | Family                 | Tools                                                                                                                                                                                                                                                                                               |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **API spec** (6)       | `get_openapi_spec`, `get_asyncapi_spec`, `search_api_endpoints`, `search_websocket_events`, `get_endpoint_details`, `get_api_environment`                                                                                                                                                           |
-| **Extended API** (5)   | `api_list_tags`, `api_list_operation_ids`, `api_get_operation_parameters`, `api_find_endpoints_by_schema`, `api_generate_dependency`                                                                                                                                                                |
+| **Extended API** (7)   | `api_list_tags`, `api_list_operation_ids`, `api_get_operation_parameters`, `api_find_endpoints_by_schema`, `api_find_events_for_operation`, `api_list_events`, `api_generate_dependency`                                                                                                            |
 | **Config editor** (13) | `config_validate`, `config_list_field_types`, `config_list_card_types`, `config_get_field_schema`, `config_list_cards`, `config_list_fields`, `config_add_field`, `config_move_field`, `config_remove_field`, `config_add_card`, `config_move_card`, `config_remove_card`, `config_extract_strings` |
 | **Docs search** (3)    | `docs_list_pages`, `docs_search`, `docs_get_page` — full-text across `docs.gxp.dev` via its sitemap                                                                                                                                                                                                 |
 | **Test helpers** (2)   | `test_scaffold_component_test`, `test_api_route`                                                                                                                                                                                                                                                    |
+| **Data models** (1)    | `describe_data_models` — enumerate or detail OpenAPI `components.schemas` with $ref + allOf flattening                                                                                                                                                                                              |
+| **UIKit** (1)          | `list_uikit_components` — list components exported by `@gxp-dev/uikit` installed in the current project                                                                                                                                                                                             |
+
+The previous bin name `gxp-api-server` still ships as a deprecation shim — it prints a stderr notice and forwards to the same server. Update your `.mcp.json` / `.gemini/settings.json` to use `mcp-serve` going forward.
 
 Every config mutation is linter-guarded: invalid writes are refused unless `force: true`, so AI agents can't save broken state.
 

package/bin/lib/cli.js

@@ -383,8 +383,10 @@ const cli = yargs
 	.epilog(
 		[
 			"Docs:   https://docs.gxp.dev",
-			"AI/MCP: the gxp-api MCP server (bin: gxp-api-server) exposes 29 tools",
-			"        across API specs, config editing, docs search, and test helpers.",
+			"AI/MCP: the gxp-api MCP server (bin: mcp-serve) exposes 33 tools across",
+			"        API specs, config editing, docs search, test helpers, data",
+			"        models, and UIKit components. (gxp-api-server still works as a",
+			"        deprecation shim.)",
 		].join("\n"),
 	)
 	.help("h")

package/bin/lib/commands/init.js

@@ -180,8 +180,9 @@ function copyBundleFiles(projectPath, paths, overwrite = false) {
 		},
 		// Canonical project-scoped MCP config files. The AI CLIs each look for
 		// their own file at the project root and auto-load the `gxp-api` server
-		// from there. The `gxp-api-server` binary is installed on PATH by
-		// @gxp-dev/tools, so no extra install step is required.
+		// from there. The `mcp-serve` binary is installed on PATH by
+		// @gxp-dev/tools, so no extra install step is required. (The legacy
+		// `gxp-api-server` name still works as a deprecation shim.)
 		{
 			src: "mcp.json",
 			dest: ".mcp.json",

package/bin/lib/utils/ai-scaffold.js

@@ -973,10 +973,10 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
 
 	const mcpFixCommand =
 		{
-			claude: "claude mcp add gxp-api gxp-api-server",
-			codex: "codex mcp add gxp-api gxp-api-server",
+			claude: "claude mcp add gxp-api mcp-serve",
+			codex: "codex mcp add gxp-api mcp-serve",
 			gemini:
-				"add the `gxp-api` server to `~/.gemini/settings.json` under `mcpServers` with command `gxp-api-server`",
+				"add the `gxp-api` server to `~/.gemini/settings.json` under `mcpServers` with command `mcp-serve`",
 		}[provider] || "see the provider's MCP docs"
 
 	return [
@@ -986,16 +986,18 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
 		"",
 		`Start a new GxP plugin development session. First read \`${instructionFile}\` and \`app-instructions.md\` in this project — they describe the workflow, conventions, and the full set of tools available to you.${claudeAgentHint}`,
 		"",
-		"**Step 0 — smoke-test the `gxp-api` MCP server before asking me anything.** The server is defined in `.mcp.json` / `.gemini/settings.json` at the project root and provided by the `gxp-api-server` binary that ships with `@gxp-dev/tools` (already on your PATH — verify with `which gxp-api-server`). Call `api_list_tags` immediately:",
+		"**Step 0 — smoke-test the `gxp-api` MCP server before asking me anything.** The server is defined in `.mcp.json` / `.gemini/settings.json` at the project root and provided by the `mcp-serve` binary that ships with `@gxp-dev/tools` (already on your PATH — verify with `which mcp-serve`). Call `api_list_tags` immediately:",
 		"- If it returns a list of tags → the MCP is live; load the tag list into memory so your first question to me can be grounded in the platform's actual resources (attendees, events, quizzes, posts, forms, etc.) rather than abstract categories.",
 		`- If \`api_list_tags\` (or any other \`api_*\` / \`config_*\` / \`docs_*\` tool) is not available, the MCP didn't register. Tell me so and suggest I run \`${mcpFixCommand}\`, then restart this session. Do not proceed without the MCP — every operationId, event, and dependency you plan with must come from it.`,
 		"",
-		"You have the `gxp-api` MCP server available with 29 tools across five families:",
+		"You have the `gxp-api` MCP server available with 33 tools across seven families:",
 		"- **API spec discovery** — `search_api_endpoints`, `api_list_operation_ids`, `api_get_operation_parameters`, `api_find_endpoints_by_schema`, `api_generate_dependency`, `get_endpoint_details`, `api_list_tags`.",
 		"- **WebSocket events** — `api_find_events_for_operation` (maps an operationId to the AsyncAPI events it triggers), `api_list_events`, `search_websocket_events`.",
 		"- **Config editing** — `config_add_card`, `config_add_field`, `config_list_field_types`, `config_get_field_schema`, `config_extract_strings`, `config_validate`, etc. Every mutation is linter-guarded against the schemas in `bin/lib/lint/schemas/`.",
 		"- **Docs search** — `docs_search`, `docs_get_page`, `docs_list_pages` (full-text search across docs.gxp.dev).",
 		"- **Test helpers** — `test_scaffold_component_test`, `test_api_route`.",
+		"- **Data models** — `describe_data_models` (enumerate or detail OpenAPI components.schemas; walks allOf and resolves $ref by name).",
+		"- **UIKit** — `list_uikit_components` (list components exported by `@gxp-dev/uikit` installed in this project).",
 		"",
 		"Follow the full workflow from the instructions: (1) understand the feature, (2) discover data sources via MCP, (3) plan including the admin configuration form, (4) implement, (5) **sync the manifest and build the admin form**, (6) test with real broadcasts, (7) final `gxdev lint --all`.",
 		"",
@@ -1033,8 +1035,8 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
  */
 function registerMcpWithProviderCli(provider) {
 	const commands = {
-		claude: ["mcp", "add", "gxp-api", "gxp-api-server"],
-		codex: ["mcp", "add", "gxp-api", "gxp-api-server"],
+		claude: ["mcp", "add", "gxp-api", "mcp-serve"],
+		codex: ["mcp", "add", "gxp-api", "mcp-serve"],
 	}
 	const args = commands[provider]
 	if (!args) {
@@ -1117,7 +1119,7 @@ function launchInteractiveAISession(
 			"   The `gxp-api` MCP server is configured in .mcp.json / .gemini/settings.json",
 		)
 		console.log(
-			"   at the project root (binary: gxp-api-server, installed with @gxp-dev/tools).",
+			"   at the project root (binary: mcp-serve, installed with @gxp-dev/tools).",
 		)
 		console.log(
 			"   The agent will smoke-test it first, then greet you and ask what you want",

package/mcp/gxp-api-server.js

@@ -1,484 +1,28 @@
 #!/usr/bin/env node
 
 /**
- * GxP API Specs MCP Server
+ * Deprecated bin. Forwards to the same stdio MCP server as `mcp-serve`,
+ * but prints a one-time stderr notice on startup so existing scaffolded
+ * projects keep working while users migrate their MCP configs to the new
+ * name. This shim will be removed in a future major release.
  *
- * Provides API documentation (OpenAPI, AsyncAPI, Webhooks) to AI coding assistants
- * via the Model Context Protocol (MCP).
+ * Migration:
+ *   - claude:  `claude mcp add gxp-api mcp-serve`
+ *   - codex:   `codex mcp add gxp-api mcp-serve`
+ *   - gemini:  set "command": "mcp-serve" in ~/.gemini/settings.json
+ *   - .mcp.json / .gemini/settings.json:  swap "gxp-api-server" -> "mcp-serve"
  *
- * Features:
- * - Fetches specs based on VITE_API_ENV environment variable
- * - Caches specs in memory for performance
- * - Provides tools for fetching full specs or searching endpoints
- *
- * Usage:
- *   node mcp/gxp-api-server.js
- *
- * Configure in your AI tool's MCP settings to enable API-aware assistance.
- */
-
-const readline = require("readline")
-const {
-	ENVIRONMENT_URLS,
-	getEnvironment,
-	getEnvUrls,
-	fetchSpec,
-} = require("./lib/specs")
-
-/**
- * Search OpenAPI spec for endpoints matching a query
- */
-function searchEndpoints(spec, query) {
-	const results = []
-	const queryLower = query.toLowerCase()
-
-	if (spec.paths) {
-		for (const [path, methods] of Object.entries(spec.paths)) {
-			for (const [method, details] of Object.entries(methods)) {
-				if (
-					typeof details === "object" &&
-					(path.toLowerCase().includes(queryLower) ||
-						details.summary?.toLowerCase().includes(queryLower) ||
-						details.description?.toLowerCase().includes(queryLower) ||
-						details.operationId?.toLowerCase().includes(queryLower) ||
-						details.tags?.some((t) => t.toLowerCase().includes(queryLower)))
-				) {
-					results.push({
-						path,
-						method: method.toUpperCase(),
-						summary: details.summary || "",
-						description: details.description || "",
-						operationId: details.operationId || "",
-						tags: details.tags || [],
-						parameters: details.parameters || [],
-						requestBody: details.requestBody || null,
-						responses: Object.keys(details.responses || {}),
-					})
-				}
-			}
-		}
-	}
-
-	return results
-}
-
-/**
- * Search AsyncAPI spec for channels/events matching a query.
- *
- * Matches across:
- *   - components.messages (event name, summary, description, x-triggered-by)
- *   - channels            (channel name, description)
- *
- * For messages, the returned `eventName` is what you pass to
- * store.listen(eventName, permissionIdentifier, callback) on the client.
- */
-function searchEvents(spec, query) {
-	const results = []
-	const queryLower = query.toLowerCase()
-
-	const messages = spec?.components?.messages || {}
-	for (const [eventName, message] of Object.entries(messages)) {
-		if (typeof message !== "object" || message === null) continue
-		const trigger = message["x-triggered-by"] || ""
-		if (
-			eventName.toLowerCase().includes(queryLower) ||
-			message.summary?.toLowerCase().includes(queryLower) ||
-			message.description?.toLowerCase().includes(queryLower) ||
-			trigger.toLowerCase().includes(queryLower)
-		) {
-			results.push({
-				kind: "event",
-				eventName,
-				summary: message.summary || "",
-				description: message.description || "",
-				triggeredBy: trigger || null,
-				payloadRef: message.payload?.$ref || null,
-			})
-		}
-	}
-
-	if (spec.channels) {
-		for (const [channel, details] of Object.entries(spec.channels)) {
-			if (
-				channel.toLowerCase().includes(queryLower) ||
-				details.description?.toLowerCase().includes(queryLower)
-			) {
-				const operations = []
-				if (details.publish) {
-					operations.push({
-						type: "publish",
-						summary: details.publish.summary || "",
-						message: details.publish.message || null,
-					})
-				}
-				if (details.subscribe) {
-					operations.push({
-						type: "subscribe",
-						summary: details.subscribe.summary || "",
-						message: details.subscribe.message || null,
-					})
-				}
-
-				results.push({
-					kind: "channel",
-					channel,
-					description: details.description || "",
-					operations,
-				})
-			}
-		}
-	}
-
-	return results
-}
-
-/**
- * Get endpoint details by path and method
- */
-function getEndpointDetails(spec, path, method) {
-	const methodLower = method.toLowerCase()
-	const endpoint = spec.paths?.[path]?.[methodLower]
-
-	if (!endpoint) {
-		return null
-	}
-
-	return {
-		path,
-		method: method.toUpperCase(),
-		summary: endpoint.summary || "",
-		description: endpoint.description || "",
-		operationId: endpoint.operationId || "",
-		tags: endpoint.tags || [],
-		parameters: endpoint.parameters || [],
-		requestBody: endpoint.requestBody || null,
-		responses: endpoint.responses || {},
-		security: endpoint.security || spec.security || [],
-	}
-}
-
-// MCP Server Implementation
-const {
-	CONFIG_TOOLS,
-	handleConfigToolCall,
-	isConfigTool,
-} = require("./lib/config-tools")
-
-const {
-	EXT_API_TOOLS,
-	handleExtApiToolCall,
-	isExtApiTool,
-} = require("./lib/api-tools")
-
-const {
-	DOCS_TOOLS,
-	handleDocsToolCall,
-	isDocsTool,
-} = require("./lib/docs-tools")
-
-const {
-	TEST_TOOLS,
-	handleTestToolCall,
-	isTestTool,
-} = require("./lib/test-tools")
-
-const SERVER_INFO = {
-	name: "gxp-api-server",
-	version: "2.0.0",
-	description:
-		"GxP toolkit MCP server: API specs, config/manifest editing, documentation search, and plugin test helpers for AI coding assistants.",
-}
-
-const API_TOOLS = [
-	{
-		name: "get_openapi_spec",
-		description:
-			"Fetch the full OpenAPI specification for the GxP API. Returns the complete spec including all endpoints, schemas, and documentation.",
-		inputSchema: {
-			type: "object",
-			properties: {},
-			required: [],
-		},
-	},
-	{
-		name: "get_asyncapi_spec",
-		description:
-			"Fetch the AsyncAPI specification for GxP WebSocket events. Returns channel definitions, message schemas, and event documentation.",
-		inputSchema: {
-			type: "object",
-			properties: {},
-			required: [],
-		},
-	},
-	{
-		name: "search_api_endpoints",
-		description:
-			"Search for API endpoints matching a query. Searches path, summary, description, operation ID, and tags.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				query: {
-					type: "string",
-					description:
-						"Search term to find matching endpoints (e.g., 'attendee', 'check-in', 'event')",
-				},
-			},
-			required: ["query"],
-		},
-	},
-	{
-		name: "search_websocket_events",
-		description:
-			"Search AsyncAPI events matching a query. Searches components.messages (event name, summary, description, x-triggered-by) and channel definitions. The returned eventName is what you pass to store.listen(eventName, permissionIdentifier, callback).",
-		inputSchema: {
-			type: "object",
-			properties: {
-				query: {
-					type: "string",
-					description:
-						"Search term to find matching events (e.g., 'message', 'created', 'updated')",
-				},
-			},
-			required: ["query"],
-		},
-	},
-	{
-		name: "get_endpoint_details",
-		description:
-			"Get detailed information about a specific API endpoint including parameters, request body, and responses.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				path: {
-					type: "string",
-					description: "API endpoint path (e.g., '/api/v1/attendees')",
-				},
-				method: {
-					type: "string",
-					description: "HTTP method (GET, POST, PUT, PATCH, DELETE)",
-				},
-			},
-			required: ["path", "method"],
-		},
-	},
-	{
-		name: "get_api_environment",
-		description:
-			"Get the current API environment configuration including base URL and spec URLs.",
-		inputSchema: {
-			type: "object",
-			properties: {},
-			required: [],
-		},
-	},
-]
-
-// Final tool set surfaced to MCP clients: API spec tools + extended API tools
-// + config-editor tools + doc-search tools + test tools.
-const TOOLS = [
-	...API_TOOLS,
-	...EXT_API_TOOLS,
-	...CONFIG_TOOLS,
-	...DOCS_TOOLS,
-	...TEST_TOOLS,
-]
-
-/**
- * Handle MCP tool calls
- */
-async function handleToolCall(name, args) {
-	if (isConfigTool(name)) {
-		return handleConfigToolCall(name, args)
-	}
-	if (isExtApiTool(name)) {
-		return handleExtApiToolCall(name, args)
-	}
-	if (isDocsTool(name)) {
-		return handleDocsToolCall(name, args)
-	}
-	if (isTestTool(name)) {
-		return handleTestToolCall(name, args)
-	}
-	switch (name) {
-		case "get_openapi_spec": {
-			const spec = await fetchSpec("openapi")
-			return {
-				content: [
-					{
-						type: "text",
-						text: JSON.stringify(spec, null, 2),
-					},
-				],
-			}
-		}
-
-		case "get_asyncapi_spec": {
-			const spec = await fetchSpec("asyncapi")
-			return {
-				content: [
-					{
-						type: "text",
-						text: JSON.stringify(spec, null, 2),
-					},
-				],
-			}
-		}
-
-		case "search_api_endpoints": {
-			const spec = await fetchSpec("openapi")
-			const results = searchEndpoints(spec, args.query)
-			return {
-				content: [
-					{
-						type: "text",
-						text:
-							results.length > 0
-								? JSON.stringify(results, null, 2)
-								: `No endpoints found matching "${args.query}"`,
-					},
-				],
-			}
-		}
-
-		case "search_websocket_events": {
-			const spec = await fetchSpec("asyncapi")
-			const results = searchEvents(spec, args.query)
-			return {
-				content: [
-					{
-						type: "text",
-						text:
-							results.length > 0
-								? JSON.stringify(results, null, 2)
-								: `No events found matching "${args.query}"`,
-					},
-				],
-			}
-		}
-
-		case "get_endpoint_details": {
-			const spec = await fetchSpec("openapi")
-			const details = getEndpointDetails(spec, args.path, args.method)
-			return {
-				content: [
-					{
-						type: "text",
-						text: details
-							? JSON.stringify(details, null, 2)
-							: `Endpoint not found: ${args.method} ${args.path}`,
-					},
-				],
-			}
-		}
-
-		case "get_api_environment": {
-			const env = getEnvironment()
-			const urls = getEnvUrls()
-			return {
-				content: [
-					{
-						type: "text",
-						text: JSON.stringify(
-							{
-								environment: env,
-								...urls,
-							},
-							null,
-							2,
-						),
-					},
-				],
-			}
-		}
-
-		default:
-			throw new Error(`Unknown tool: ${name}`)
-	}
-}
-
-/**
- * Process MCP JSON-RPC request
+ * The notice is written to stderr (not stdout) so it doesn't corrupt the
+ * MCP JSON-RPC stream the client is reading.
  */
-async function processRequest(request) {
-	const { method, params, id } = request
-
-	try {
-		let result
-
-		switch (method) {
-			case "initialize":
-				result = {
-					protocolVersion: "2024-11-05",
-					capabilities: {
-						tools: {},
-					},
-					serverInfo: SERVER_INFO,
-				}
-				break
-
-			case "tools/list":
-				result = { tools: TOOLS }
-				break
-
-			case "tools/call":
-				result = await handleToolCall(params.name, params.arguments || {})
-				break
-
-			case "notifications/initialized":
-				// No response needed for notifications
-				return null
-
-			default:
-				throw new Error(`Unknown method: ${method}`)
-		}
-
-		return { jsonrpc: "2.0", id, result }
-	} catch (error) {
-		return {
-			jsonrpc: "2.0",
-			id,
-			error: {
-				code: -32603,
-				message: error.message,
-			},
-		}
-	}
-}
-
-/**
- * Main server loop
- */
-async function main() {
-	const rl = readline.createInterface({
-		input: process.stdin,
-		output: process.stdout,
-		terminal: false,
-	})
-
-	for await (const line of rl) {
-		if (!line.trim()) continue
 
-		try {
-			const request = JSON.parse(line)
-			const response = await processRequest(request)
+process.stderr.write(
+	"[gxp-api-server] DEPRECATED: this bin name will be removed in a future major release. Use `mcp-serve` instead — update your .mcp.json / .gemini/settings.json or rerun `claude mcp add gxp-api mcp-serve`.\n",
+)
 
-			if (response) {
-				console.log(JSON.stringify(response))
-			}
-		} catch (error) {
-			console.log(
-				JSON.stringify({
-					jsonrpc: "2.0",
-					id: null,
-					error: {
-						code: -32700,
-						message: `Parse error: ${error.message}`,
-					},
-				}),
-			)
-		}
-	}
-}
+const { startServer } = require("./lib/server")
 
-// Run server
-main().catch(console.error)
+startServer().catch((err) => {
+	console.error(err && err.stack ? err.stack : err)
+	process.exit(1)
+})