@gxp-dev/tools 2.0.71 → 2.0.72

package/mcp/lib/api-tools.js

@@ -0,0 +1,456 @@
+/**
+ * Extended MCP API tools (Phase 3).
+ *
+ * Builds on the existing search_api_endpoints / get_endpoint_details to add:
+ *   - api_list_tags              : enumerate all OpenAPI tags
+ *   - api_list_operation_ids     : enumerate operations, optionally filtered by tag
+ *   - api_get_operation_parameters : deep detail for a single operation id
+ *   - api_find_endpoints_by_schema : search by request/response field names
+ *   - api_generate_dependency    : build the GxP dependency JSON from a
+ *                                   tag + selected operations/events,
+ *                                   optionally appending to app-manifest.json
+ *
+ * The dependency shape mirrors bin/lib/commands/add-dependency.js:
+ *   { identifier, model, permissionKey, permissions: [], operations: {}, events: {} }
+ */
+
+const fs = require("fs")
+const path = require("path")
+const { fetchSpec } = require("./specs")
+
+/* ---------------------------------- utils --------------------------------- */
+
+function contentResult(obj) {
+	return {
+		content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+	}
+}
+
+function walkOperations(spec) {
+	const out = []
+	if (!spec || !spec.paths) return out
+	for (const [p, methods] of Object.entries(spec.paths)) {
+		for (const [method, op] of Object.entries(methods)) {
+			if (typeof op !== "object" || op === null) continue
+			if (
+				!["get", "post", "put", "patch", "delete", "options", "head"].includes(
+					method,
+				)
+			) {
+				continue
+			}
+			out.push({ path: p, method: method.toUpperCase(), op })
+		}
+	}
+	return out
+}
+
+/**
+ * Return the list of distinct field names mentioned anywhere in a JSON-ish
+ * object, walking $ref via the components registry shallowly.
+ */
+function schemaFieldNames(schema, components, depth = 0, seen = new Set()) {
+	if (!schema || depth > 4) return []
+	if (schema.$ref && components) {
+		const refName = schema.$ref.split("/").pop()
+		if (seen.has(refName)) return []
+		seen.add(refName)
+		const target = components?.schemas?.[refName]
+		return schemaFieldNames(target, components, depth + 1, seen)
+	}
+	const names = []
+	if (schema.properties && typeof schema.properties === "object") {
+		for (const [name, subSchema] of Object.entries(schema.properties)) {
+			names.push(name)
+			names.push(...schemaFieldNames(subSchema, components, depth + 1, seen))
+		}
+	}
+	if (schema.items) {
+		names.push(...schemaFieldNames(schema.items, components, depth + 1, seen))
+	}
+	if (Array.isArray(schema.allOf)) {
+		for (const sub of schema.allOf) {
+			names.push(...schemaFieldNames(sub, components, depth + 1, seen))
+		}
+	}
+	return names
+}
+
+function findOperationById(spec, operationId) {
+	for (const { path: p, method, op } of walkOperations(spec)) {
+		if (op.operationId === operationId) {
+			return { path: p, method, op }
+		}
+	}
+	return null
+}
+
+/* ------------------------------ tool schemas ------------------------------ */
+
+const EXT_API_TOOLS = [
+	{
+		name: "api_list_tags",
+		description:
+			"List every tag in the OpenAPI spec with endpoint counts. Use this to discover platform 'models' (attendees, projects, events, etc.) before building a dependency.",
+		inputSchema: { type: "object", properties: {}, required: [] },
+	},
+	{
+		name: "api_list_operation_ids",
+		description:
+			"Enumerate operation IDs in the OpenAPI spec. Optionally filter by tag.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				tag: {
+					type: "string",
+					description:
+						"Filter to operations under this tag (e.g. 'Attendees'). Omit for all.",
+				},
+			},
+			required: [],
+		},
+	},
+	{
+		name: "api_get_operation_parameters",
+		description:
+			"Look up a single operation by id and return its path, method, parameters, requestBody schema, response schemas, and required permissions.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				operationId: {
+					type: "string",
+					description: "OpenAPI operationId (e.g. 'attendees.index').",
+				},
+			},
+			required: ["operationId"],
+		},
+	},
+	{
+		name: "api_find_endpoints_by_schema",
+		description:
+			"Search endpoints by structural hints: field names present in the request or response bodies, URL path substrings, or HTTP method. Combine any filters — all are AND'd.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				request_field: {
+					type: "string",
+					description:
+						"Find endpoints whose request body schema mentions this field name.",
+				},
+				response_field: {
+					type: "string",
+					description:
+						"Find endpoints whose response schema mentions this field name.",
+				},
+				path_pattern: {
+					type: "string",
+					description: "Substring that must appear in the path.",
+				},
+				method: {
+					type: "string",
+					description: "HTTP method filter (GET, POST, etc.).",
+				},
+				tag: {
+					type: "string",
+					description: "Restrict to one tag.",
+				},
+			},
+			required: [],
+		},
+	},
+	{
+		name: "api_generate_dependency",
+		description:
+			"Build the GxP dependency JSON (for app-manifest.json dependencies[]) from a tag and an explicit list of operationIds and/or asyncapi event names. Optionally append it to an app-manifest.json file.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				identifier: {
+					type: "string",
+					description:
+						"Short slug used by plugin code to reference the dependency (e.g. 'attendees').",
+				},
+				tag: {
+					type: "string",
+					description: "OpenAPI tag name — becomes the dependency's 'model'.",
+				},
+				operationIds: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"Operation IDs to include. Omit to include every operation under the tag.",
+				},
+				eventNames: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"AsyncAPI event names to wire up in the dependency's events map.",
+				},
+				writeTo: {
+					type: "string",
+					description:
+						"Optional path to an app-manifest.json. When provided, the dependency is appended/replaced in manifest.dependencies[] and the file is rewritten.",
+				},
+			},
+			required: ["identifier", "tag"],
+		},
+	},
+]
+
+/* ---------------------------------- core ---------------------------------- */
+
+async function listTags() {
+	const spec = await fetchSpec("openapi")
+	const tagMeta = new Map()
+	for (const t of spec.tags || []) {
+		tagMeta.set(t.name, {
+			name: t.name,
+			description: t.description || "",
+			pathCount: 0,
+		})
+	}
+	for (const { op } of walkOperations(spec)) {
+		for (const tag of op.tags || []) {
+			if (!tagMeta.has(tag)) {
+				tagMeta.set(tag, { name: tag, description: "", pathCount: 0 })
+			}
+			tagMeta.get(tag).pathCount++
+		}
+	}
+	return Array.from(tagMeta.values()).sort((a, b) =>
+		a.name.localeCompare(b.name),
+	)
+}
+
+async function listOperationIds(tag) {
+	const spec = await fetchSpec("openapi")
+	const out = []
+	for (const { path: p, method, op } of walkOperations(spec)) {
+		if (!op.operationId) continue
+		if (tag && !(op.tags || []).includes(tag)) continue
+		out.push({
+			operationId: op.operationId,
+			method,
+			path: p,
+			tags: op.tags || [],
+			summary: op.summary || "",
+		})
+	}
+	return out
+}
+
+async function getOperationParameters(operationId) {
+	const spec = await fetchSpec("openapi")
+	const found = findOperationById(spec, operationId)
+	if (!found) return null
+
+	const { path: p, method, op } = found
+	const permission =
+		op["x-permission"] ||
+		op["x-permissionKey"] ||
+		op.security?.[0]?.permission ||
+		null
+
+	return {
+		operationId,
+		path: p,
+		method,
+		tags: op.tags || [],
+		summary: op.summary || "",
+		description: op.description || "",
+		parameters: op.parameters || [],
+		requestBody: op.requestBody || null,
+		responses: op.responses || {},
+		permission,
+		security: op.security || spec.security || [],
+	}
+}
+
+async function findEndpointsBySchema(filters) {
+	const spec = await fetchSpec("openapi")
+	const components = spec.components || {}
+	const {
+		request_field: reqField,
+		response_field: respField,
+		path_pattern: pathPattern,
+		method: methodFilter,
+		tag,
+	} = filters || {}
+
+	const out = []
+	for (const { path: p, method, op } of walkOperations(spec)) {
+		if (methodFilter && methodFilter.toUpperCase() !== method) continue
+		if (pathPattern && !p.includes(pathPattern)) continue
+		if (tag && !(op.tags || []).includes(tag)) continue
+
+		if (reqField) {
+			const reqSchema = op.requestBody?.content?.["application/json"]?.schema
+			const fields = schemaFieldNames(reqSchema, components)
+			if (!fields.includes(reqField)) continue
+		}
+		if (respField) {
+			// Prefer a 2xx response; fall back to any.
+			const responses = op.responses || {}
+			const preferred =
+				responses["200"] ||
+				responses["201"] ||
+				responses["204"] ||
+				Object.values(responses)[0]
+			const respSchema = preferred?.content?.["application/json"]?.schema
+			const fields = schemaFieldNames(respSchema, components)
+			if (!fields.includes(respField)) continue
+		}
+
+		out.push({
+			operationId: op.operationId || null,
+			method,
+			path: p,
+			tags: op.tags || [],
+			summary: op.summary || "",
+		})
+	}
+	return out
+}
+
+async function generateDependency({
+	identifier,
+	tag,
+	operationIds,
+	eventNames,
+	writeTo,
+}) {
+	const openapi = await fetchSpec("openapi")
+
+	// Discover operations under the tag.
+	const scoped = []
+	for (const { path: p, method, op } of walkOperations(openapi)) {
+		if (!(op.tags || []).includes(tag)) continue
+		if (operationIds && operationIds.length > 0) {
+			if (!operationIds.includes(op.operationId)) continue
+		}
+		scoped.push({ path: p, method, op })
+	}
+
+	if (scoped.length === 0) {
+		return {
+			ok: false,
+			error: `No operations found for tag="${tag}"${
+				operationIds
+					? ` matching operationIds=${JSON.stringify(operationIds)}`
+					: ""
+			}.`,
+		}
+	}
+
+	const operations = {}
+	const permissions = new Set()
+	let permissionKey = null
+	for (const { path: p, method, op } of scoped) {
+		if (!op.operationId) continue
+		const cleanOpId = op.operationId.replace(/^portal\.v1\.project\./, "")
+		operations[cleanOpId] = `${method.toLowerCase()}:${p}`
+
+		const perm = op["x-permission"] || op.security?.[0]?.permission || null
+		if (perm) permissions.add(perm)
+
+		const key = op["x-permission-key"] || op["x-permissionKey"] || null
+		if (!permissionKey && key) permissionKey = key
+	}
+
+	const events = {}
+	if (Array.isArray(eventNames)) {
+		for (const name of eventNames) {
+			events[name] = name
+		}
+	}
+
+	const dependency = {
+		identifier,
+		model: tag,
+		permissionKey,
+		permissions: Array.from(permissions).sort(),
+		operations,
+		events,
+	}
+
+	const result = { ok: true, dependency, wrote: false }
+
+	if (writeTo) {
+		const absPath = path.resolve(process.cwd(), writeTo)
+		let manifest = { dependencies: [] }
+		if (fs.existsSync(absPath)) {
+			manifest = JSON.parse(fs.readFileSync(absPath, "utf-8"))
+		}
+		if (!Array.isArray(manifest.dependencies)) {
+			manifest.dependencies = []
+		}
+		const existingIdx = manifest.dependencies.findIndex(
+			(d) => d.identifier === identifier,
+		)
+		if (existingIdx >= 0) {
+			manifest.dependencies[existingIdx] = dependency
+			result.replaced = true
+		} else {
+			manifest.dependencies.push(dependency)
+			result.replaced = false
+		}
+		fs.writeFileSync(absPath, JSON.stringify(manifest, null, "\t"))
+		result.wrote = true
+		result.file = absPath
+	}
+
+	return result
+}
+
+/* --------------------------------- dispatch ------------------------------- */
+
+async function handleExtApiToolCall(name, args = {}) {
+	switch (name) {
+		case "api_list_tags":
+			return contentResult({ tags: await listTags() })
+
+		case "api_list_operation_ids":
+			return contentResult({
+				operations: await listOperationIds(args.tag),
+			})
+
+		case "api_get_operation_parameters": {
+			const detail = await getOperationParameters(args.operationId)
+			if (!detail) {
+				return contentResult({
+					error: `Operation not found: ${args.operationId}`,
+				})
+			}
+			return contentResult(detail)
+		}
+
+		case "api_find_endpoints_by_schema":
+			return contentResult({
+				results: await findEndpointsBySchema(args || {}),
+			})
+
+		case "api_generate_dependency":
+			return contentResult(await generateDependency(args))
+
+		default:
+			throw new Error(`Unknown ext api tool: ${name}`)
+	}
+}
+
+function isExtApiTool(name) {
+	return EXT_API_TOOLS.some((t) => t.name === name)
+}
+
+module.exports = {
+	EXT_API_TOOLS,
+	handleExtApiToolCall,
+	isExtApiTool,
+	// Exported for testing
+	walkOperations,
+	schemaFieldNames,
+	listTags,
+	listOperationIds,
+	getOperationParameters,
+	findEndpointsBySchema,
+	generateDependency,
+}

package/mcp/lib/config-ops.js

@@ -0,0 +1,234 @@
+/**
+ * JSON-pointer operations + GxP-aware walkers used by the MCP config tools.
+ *
+ * Paths are RFC-6901 JSON pointers:
+ *   "/additionalTabs/0/cards/1/fieldsList/2"
+ * Empty or "/" means "the whole document".
+ *
+ * All functions are pure: they operate on a parsed doc and return either a
+ * value (readers) or a new doc (writers). No file IO here.
+ */
+
+function parsePointer(pointer) {
+	if (pointer === "" || pointer === "/") {
+		return []
+	}
+	if (!pointer.startsWith("/")) {
+		throw new Error(`Invalid JSON pointer (must start with "/"): ${pointer}`)
+	}
+	return pointer
+		.slice(1)
+		.split("/")
+		.map((segment) =>
+			decodeURIComponent(segment.replace(/~1/g, "/").replace(/~0/g, "~")),
+		)
+}
+
+function encodeSegment(segment) {
+	return String(segment).replace(/~/g, "~0").replace(/\//g, "~1")
+}
+
+function buildPointer(segments) {
+	if (!segments.length) return ""
+	return "/" + segments.map(encodeSegment).join("/")
+}
+
+function isIndex(segment) {
+	return /^\d+$/.test(segment)
+}
+
+function getByPointer(doc, pointer) {
+	const segments = parsePointer(pointer)
+	let cur = doc
+	for (const seg of segments) {
+		if (cur === null || cur === undefined) return undefined
+		if (Array.isArray(cur)) {
+			if (!isIndex(seg)) return undefined
+			cur = cur[Number(seg)]
+		} else if (typeof cur === "object") {
+			cur = cur[seg]
+		} else {
+			return undefined
+		}
+	}
+	return cur
+}
+
+function getParent(doc, pointer) {
+	const segments = parsePointer(pointer)
+	if (!segments.length) {
+		throw new Error("Cannot get parent of root")
+	}
+	const last = segments[segments.length - 1]
+	const parent = getByPointer(doc, buildPointer(segments.slice(0, -1)))
+	return { parent, key: last, isIndex: isIndex(last) }
+}
+
+/**
+ * Produce a deep-cloned document with the value at `pointer` set to `value`.
+ * Throws if the parent doesn't exist.
+ */
+function setByPointer(doc, pointer, value) {
+	const clone = structuredClone(doc)
+	const segments = parsePointer(pointer)
+	if (!segments.length) {
+		return value
+	}
+	let cur = clone
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i]
+		if (cur[seg] === undefined || cur[seg] === null) {
+			throw new Error(
+				`Path does not exist at "${buildPointer(segments.slice(0, i + 1))}"`,
+			)
+		}
+		cur = cur[seg]
+	}
+	const last = segments[segments.length - 1]
+	if (Array.isArray(cur) && isIndex(last)) {
+		cur[Number(last)] = value
+	} else {
+		cur[last] = value
+	}
+	return clone
+}
+
+function deleteByPointer(doc, pointer) {
+	const clone = structuredClone(doc)
+	const segments = parsePointer(pointer)
+	if (!segments.length) {
+		throw new Error("Cannot delete root")
+	}
+	let cur = clone
+	for (let i = 0; i < segments.length - 1; i++) {
+		cur = cur[segments[i]]
+		if (cur === undefined) {
+			throw new Error(`Path does not exist: ${pointer}`)
+		}
+	}
+	const last = segments[segments.length - 1]
+	if (Array.isArray(cur) && isIndex(last)) {
+		cur.splice(Number(last), 1)
+	} else {
+		delete cur[last]
+	}
+	return clone
+}
+
+/**
+ * Insert a value into an array at `pointer` (must point to an array) at the
+ * given position. `position` may be an integer or "end".
+ */
+function insertAt(doc, arrayPointer, item, position = "end") {
+	const clone = structuredClone(doc)
+	const arr = getByPointer(clone, arrayPointer)
+	if (!Array.isArray(arr)) {
+		throw new Error(`Pointer must reference an array: ${arrayPointer}`)
+	}
+	if (position === "end" || position === undefined) {
+		arr.push(item)
+		return { doc: clone, index: arr.length - 1 }
+	}
+	const idx = Number(position)
+	if (!Number.isInteger(idx) || idx < 0 || idx > arr.length) {
+		throw new Error(`Invalid position: ${position}`)
+	}
+	arr.splice(idx, 0, item)
+	return { doc: clone, index: idx }
+}
+
+/**
+ * Move an item from one pointer to another. Both must point to items inside
+ * arrays; targetArray is the pointer to the destination array.
+ */
+function moveItem(doc, fromPointer, targetArrayPointer, position = "end") {
+	const item = getByPointer(doc, fromPointer)
+	if (item === undefined) {
+		throw new Error(`Source does not exist: ${fromPointer}`)
+	}
+	const withoutItem = deleteByPointer(doc, fromPointer)
+
+	// If the move is within the same array and we're shifting forward, the
+	// source-removal may have reindexed the target. We recompute here: parse
+	// the target array pointer and verify it still exists after removal.
+	const targetArr = getByPointer(withoutItem, targetArrayPointer)
+	if (!Array.isArray(targetArr)) {
+		throw new Error(`Target must be an array: ${targetArrayPointer}`)
+	}
+	return insertAt(withoutItem, targetArrayPointer, item, position)
+}
+
+/**
+ * Recursively walk a configuration document and return a flat list of all
+ * cards with their JSON pointer, type, title, and a summary of children.
+ *
+ * Cards are discovered under:
+ *   additionalTabs[]                          (root array of cards)
+ *   <card>.cards[]                            (card_list)
+ *   <card>.tabsList[].cards[]                 (tabs_list)
+ */
+function listCards(doc) {
+	const out = []
+
+	function walk(node, pointer) {
+		if (!node || typeof node !== "object") return
+
+		// If node looks like a card (has `type`), record it.
+		if (typeof node.type === "string") {
+			out.push({
+				path: pointer,
+				type: node.type,
+				title: node.title ?? null,
+				tabId: node.tabId ?? null,
+				fieldCount: Array.isArray(node.fieldsList) ? node.fieldsList.length : 0,
+			})
+		}
+
+		if (Array.isArray(node.cards)) {
+			node.cards.forEach((c, i) => walk(c, `${pointer}/cards/${i}`))
+		}
+		if (Array.isArray(node.tabsList)) {
+			node.tabsList.forEach((tab, i) => {
+				if (Array.isArray(tab.cards)) {
+					tab.cards.forEach((c, j) =>
+						walk(c, `${pointer}/tabsList/${i}/cards/${j}`),
+					)
+				}
+			})
+		}
+	}
+
+	if (Array.isArray(doc?.additionalTabs)) {
+		doc.additionalTabs.forEach((c, i) => walk(c, `/additionalTabs/${i}`))
+	}
+	return out
+}
+
+/**
+ * List all fields under a fields_list card, with their JSON pointer.
+ */
+function listFields(doc, cardPointer) {
+	const card = getByPointer(doc, cardPointer)
+	if (!card || !Array.isArray(card.fieldsList)) {
+		return []
+	}
+	return card.fieldsList.map((f, i) => ({
+		path: `${cardPointer}/fieldsList/${i}`,
+		type: f.type,
+		name: f.name ?? null,
+		label: f.label ?? null,
+	}))
+}
+
+module.exports = {
+	parsePointer,
+	buildPointer,
+	getByPointer,
+	getParent,
+	setByPointer,
+	deleteByPointer,
+	insertAt,
+	moveItem,
+	listCards,
+	listFields,
+}