@devframes/agentic 1.2.6 → 1.3.1

package/dist/connect/index.mjs

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/server";
-import { diagnostics, listLiveDevframeInstances, probeDevframeOrigin } from "devframe/internal";
+import { LIST_CLIENTS_TOOL, diagnostics, listLiveDevframeInstances, probeDevframeOrigin } from "devframe/internal";
 import { toAgentToolName } from "devframe/utils/agent-tool-name";
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -25,13 +25,15 @@ function buildInstanceRequestHeaders(url, token) {
 	if (token) headers.authorization = `Bearer ${token}`;
 	return headers;
 }
+/** Wire name of the built-in tab-listing tool an instance exposes once a browser tab connects. */
+const LIST_CLIENTS_NAME = toAgentToolName(LIST_CLIENTS_TOOL);
 const INDEX_TOOL = toAgentToolName("devframe:connect:list-instances");
 const CALL_TOOL = toAgentToolName("devframe:connect:call-tool");
 const MCP_DISABLED_HINT = "This instance runs without an MCP route. Restart it with the --mcp flag to expose its tools, then list instances again.";
 const GATEWAY_TOOLS = [{
 	name: INDEX_TOOL,
 	title: "Discover running devframes",
-	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
+	description: "Discover every running devframe dev server on this machine and list each one's MCP tools, plus the browser tabs connected to it (`mcp.clients`). Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
 	inputSchema: {
 		type: "object",
 		properties: {}
@@ -57,7 +59,7 @@ const GATEWAY_TOOLS = [{
 			},
 			args: {
 				type: "object",
-				description: "Arguments object for the tool. Omit for zero-argument tools."
+				description: "Arguments object for the tool. Omit for zero-argument tools. Tools forwarded from a browser tab accept `client_id` (from `mcp.clients` in list-instances) to target one tab; omitted, the most recently focused tab runs it."
 			}
 		},
 		required: ["port", "tool"],
@@ -125,7 +127,7 @@ async function index(options) {
 		try {
 			entry.mcp = {
 				url,
-				tools: await listInstanceTools(url, resolveAuthToken(options.authToken, record))
+				...await indexInstanceMcp(url, resolveAuthToken(options.authToken, record))
 			};
 		} catch (error) {
 			entry.mcp = {
@@ -163,8 +165,18 @@ async function probePort(port, base = "/", timeoutMs) {
 		startedAt: 0
 	};
 }
-async function listInstanceTools(url, token) {
-	return withInstanceClient(url, token, async (client) => (await client.listTools()).tools);
+async function indexInstanceMcp(url, token) {
+	return withInstanceClient(url, token, async (client) => {
+		const tools = (await client.listTools()).tools;
+		if (!tools.some((tool) => tool.name === LIST_CLIENTS_NAME)) return { tools };
+		return {
+			tools,
+			clients: (await client.callTool({
+				name: LIST_CLIENTS_NAME,
+				arguments: {}
+			})).structuredContent?.clients ?? []
+		};
+	});
 }
 async function call(options, args) {
 	if (typeof args.port !== "number" || typeof args.tool !== "string") throw diagnostics.DF0049();

package/dist/mcp/index.mjs

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import process from "node:process";
-import { Server, createMcpHandler } from "@modelcontextprotocol/server";
+import { ProtocolError, ProtocolErrorCode, Server, createMcpHandler } from "@modelcontextprotocol/server";
 import { DEVFRAME_EVENTS } from "devframe/constants";
 import { argsToJsonSchema, diagnostics, formatMcpError, getMcpContent, returnToJsonSchema, stringifyForMcp } from "devframe/internal";
 import { createHostContext } from "devframe/node";
@@ -29,19 +29,31 @@ function buildMcpServerFromContext(ctx, options) {
 	}, {
 		capabilities: {
 			tools: { listChanged: true },
-			resources: { listChanged: true }
+			resources: { listChanged: true },
+			...options.prompts?.size ? { prompts: { listChanged: false } } : {}
 		},
 		...options.instructions ? { instructions: options.instructions } : {}
 	});
 	registerToolHandlers(server, ctx, options.exposeSharedState);
-	registerResourceHandlers(server, ctx, options.exposeSharedState);
+	const templates = options.resourceTemplates ?? [];
+	registerResourceHandlers(server, ctx, options.exposeSharedState, templates);
+	if (templates.length) server.setRequestHandler("resources/templates/list", async () => ({ resourceTemplates: templates.map(({ template: { uriTemplate, name, title, description, mimeType } }) => ({
+		uriTemplate,
+		name,
+		title,
+		description,
+		mimeType
+	})) }));
+	if (options.prompts?.size) registerPromptHandlers(server, options.prompts);
 	return server;
 }
 /**
 * Publish devframe's `list_changed` events through a set of typed sinks:
 * `tools()` for tool-list changes and `resources()` for resource-list
-* changes (shared-state keys are surfaced as resources). Returns an
-* unsubscribe function.
+* changes (shared-state keys are surfaced as resources). An optional host
+* subscription (`onResourcesChanged`) also publishes through `resources()`
+* each time it calls `notify()`. Returns an unsubscribe function, which also
+* removes the host subscription; a `notify()` after that does nothing.
 *
 * The HTTP path passes the handler's `notify` bus sugar; the stdio path
 * passes the pinned server's `send*ListChanged` methods, which `serveStdio`
@@ -49,7 +61,7 @@ function buildMcpServerFromContext(ctx, options) {
 *
 * @internal
 */
-function bridgeListChanged(ctx, sinks) {
+function bridgeListChanged(ctx, sinks, onResourcesChanged) {
 	const offManifest = ctx.agent.events.on(DEVFRAME_EVENTS.bus.agentManifestChanged, () => {
 		sinks.tools();
 		sinks.resources();
@@ -57,9 +69,15 @@ function bridgeListChanged(ctx, sinks) {
 	const offKeyAdded = ctx.rpc.sharedState.onKeyAdded(() => {
 		sinks.resources();
 	});
+	let active = true;
+	const offHost = onResourcesChanged?.(() => {
+		if (active) sinks.resources();
+	}, ctx);
 	return () => {
+		active = false;
 		offManifest();
 		offKeyAdded();
+		offHost?.();
 	};
 }
 /**
@@ -72,6 +90,8 @@ async function createMcpServer(definition, options = {}) {
 		transport,
 		reason: "Only stdio transport is supported in this release."
 	});
+	const resourceTemplates = compileResourceTemplates(options.resourceTemplates);
+	const prompts = compilePrompts(options.prompts);
 	const ctx = await createHostContext({
 		cwd: process.cwd(),
 		mode: "dev",
@@ -93,7 +113,9 @@ async function createMcpServer(definition, options = {}) {
 		serverName: options.serverName ?? `${definition.id} (devframe)`,
 		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
 		exposeSharedState: options.exposeSharedState ?? true,
-		instructions: options.instructions
+		instructions: options.instructions,
+		resourceTemplates,
+		prompts
 	};
 	let handle;
 	try {
@@ -107,7 +129,7 @@ async function createMcpServer(definition, options = {}) {
 				resources: () => {
 					server.sendResourceListChanged().catch(() => {});
 				}
-			});
+			}, options.onResourcesChanged);
 			const priorOnClose = server.onclose;
 			server.onclose = () => {
 				unbridge();
@@ -238,7 +260,7 @@ function registerToolHandlers(server, ctx, exposeSharedState) {
 		}
 	});
 }
-function registerResourceHandlers(server, ctx, exposeSharedState) {
+function registerResourceHandlers(server, ctx, exposeSharedState, templates) {
 	const stateFilter = sharedStateFilter(exposeSharedState);
 	server.setRequestHandler("resources/list", async () => {
 		const resources = ctx.agent.list().resources.map((resource) => ({
@@ -256,6 +278,10 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 				mimeType: "application/json"
 			});
 		}
+		for (const { template } of templates) for (const entry of await template.list?.(ctx) ?? []) resources.push({
+			...entry,
+			mimeType: entry.mimeType ?? template.mimeType
+		});
 		return { resources };
 	});
 	server.setRequestHandler("resources/read", async (request) => {
@@ -278,10 +304,143 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 				text: stringifyForMcp(state.value())
 			}] };
 		}
+		for (const { template, match } of templates) {
+			const params = match(uri);
+			if (!params) continue;
+			const content = await template.read(params, uri, ctx);
+			return { contents: [{
+				uri,
+				mimeType: content.mimeType ?? template.mimeType ?? "application/json",
+				text: content.text ?? stringifyForMcp(content.json)
+			}] };
+		}
 		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
 	});
 }
 /**
+* Index prompts by name, once per endpoint. A repeated name throws
+* `DF0085`, since `prompts/get` finds a prompt by its name.
+*
+* @internal
+*/
+function compilePrompts(prompts = []) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const prompt of prompts) {
+		if (byName.has(prompt.name)) throw diagnostics.DF0085({ name: prompt.name });
+		byName.set(prompt.name, prompt);
+	}
+	return byName;
+}
+/**
+* Serve `prompts/list` and `prompts/get`. An unknown name, or a required
+* argument that is missing or empty, is an invalid-params error. An error
+* thrown by `get` goes to the MCP client.
+*/
+function registerPromptHandlers(server, prompts) {
+	server.setRequestHandler("prompts/list", async () => ({ prompts: [...prompts.values()].map(({ name, title, description, arguments: args }) => ({
+		name,
+		title,
+		description,
+		...args?.length ? { arguments: args.map((argument) => ({
+			name: argument.name,
+			description: argument.description,
+			required: argument.required
+		})) } : {}
+	})) }));
+	server.setRequestHandler("prompts/get", async (request) => {
+		const { name, arguments: given = {} } = request.params;
+		const prompt = prompts.get(name);
+		if (!prompt) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `[devframe/mcp] unknown prompt "${name}"`);
+		const missing = (prompt.arguments ?? []).filter((argument) => argument.required && !(Object.hasOwn(given, argument.name) && given[argument.name])).map((argument) => argument.name);
+		if (missing.length) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `[devframe/mcp] prompt "${name}" needs the argument(s): ${missing.join(", ")}`);
+		const { description, messages } = await prompt.get(given);
+		return {
+			description,
+			messages
+		};
+	});
+}
+/** One `{name}` expression of a URI template. */
+const TEMPLATE_EXPRESSION_RE = /\{([^{}]*)\}/;
+/** RFC 6570 `varname`: letters, digits and `_`, with single dots between them. */
+const TEMPLATE_VARNAME_RE = /^\w+(?:\.\w+)*$/;
+/**
+* Compile resource templates to URI matchers, once per endpoint. Only RFC
+* 6570 level 1 is supported: plain `{name}` expressions. Each expression
+* matches a non-empty value with no `/`, and its value is percent-decoded,
+* so an encoded `%2F` reads back as `/`. A URI with malformed
+* percent-encoding matches no template. Any other template syntax, and two
+* expressions with nothing between them, throw `DF0084`.
+*
+* @internal
+*/
+function compileResourceTemplates(templates = []) {
+	return templates.map((template) => {
+		const { name, uriTemplate } = template;
+		const invalid = (reason) => diagnostics.DF0084({
+			name,
+			uriTemplate,
+			reason
+		});
+		const parts = uriTemplate.split(TEMPLATE_EXPRESSION_RE);
+		const literals = parts.filter((_, index) => index % 2 === 0);
+		const names = parts.filter((_, index) => index % 2 === 1);
+		if (literals.some((literal) => /[{}]/.test(literal))) throw invalid("a `{` or `}` is outside an expression.");
+		names.forEach((varname, index) => {
+			if (!TEMPLATE_VARNAME_RE.test(varname)) throw invalid(`the expression "{${varname}}" is not a plain \`{name}\`.`);
+			if (names.indexOf(varname) !== index) throw invalid(`the name "${varname}" is used more than once.`);
+			if (index > 0 && literals[index] === "") throw invalid(`"{${names[index - 1]}}" and "{${varname}}" have nothing between them, so a URI cannot show where one ends.`);
+		});
+		return {
+			template,
+			match: (uri) => matchTemplate(uri, literals, names)
+		};
+	});
+}
+/**
+* Match `uri` in one pass from left to right, with no regular expression, so
+* the time grows with the URI length only and a crafted URI cannot block the
+* process. Each value runs to the first place the next literal appears
+* outside a `%XX` escape (the last value runs to the tail). A value must not
+* be empty or contain `/`.
+* The params object has no prototype, so a variable such as `__proto__`
+* keeps its value.
+*/
+function matchTemplate(uri, literals, names) {
+	const head = literals[0];
+	const tail = literals.at(-1);
+	const params = Object.create(null);
+	if (names.length === 0) return uri === head ? params : void 0;
+	if (!uri.startsWith(head) || !uri.endsWith(tail)) return void 0;
+	const end = uri.length - tail.length;
+	let position = head.length;
+	for (let index = 0; index < names.length; index++) {
+		const isLast = index === names.length - 1;
+		const next = literals[index + 1];
+		const stop = isLast ? end : findLiteral(uri, next, position);
+		if (stop <= position) return void 0;
+		const raw = uri.slice(position, stop);
+		if (raw.includes("/")) return void 0;
+		try {
+			params[names[index]] = decodeURIComponent(raw);
+		} catch {
+			return;
+		}
+		position = stop + (isLast ? 0 : next.length);
+	}
+	return params;
+}
+/**
+* The first place `literal` appears after the value that starts at `start`
+* (which must not be empty), or -1. A place inside a `%XX` escape of the
+* value is skipped, so `{a}D{b}` reads `a%2DbDc` as `a-b` and `c`.
+*/
+function findLiteral(uri, literal, start) {
+	let at = uri.indexOf(literal, start + 1);
+	while (at !== -1 && (uri[at - 1] === "%" || at - 2 >= start && uri[at - 2] === "%")) at = uri.indexOf(literal, at + 1);
+	return at;
+}
+/**
 * The content blocks a tool result carries through `withMcpContent`, checked
 * and copied field by field, or `undefined` when it carries none. Invalid
 * blocks throw DF0081, which the `tools/call` handler turns into an
@@ -429,11 +588,15 @@ async function isAuthorized(req, authorization) {
 function createMcpFetchHandler(ctx, options) {
 	const allowedOrigins = options.allowedOrigins;
 	const authorization = options.authorization ?? false;
+	const resourceTemplates = compileResourceTemplates(options.resourceTemplates);
+	const prompts = compilePrompts(options.prompts);
 	const handler = createMcpHandler(() => buildMcpServerFromContext(ctx, {
 		serverName: options.serverName,
 		serverVersion: options.serverVersion,
 		exposeSharedState: options.exposeSharedState,
-		instructions: options.instructions
+		instructions: options.instructions,
+		resourceTemplates,
+		prompts
 	}));
 	const unbridge = bridgeListChanged(ctx, {
 		tools: () => {
@@ -442,7 +605,7 @@ function createMcpFetchHandler(ctx, options) {
 		resources: () => {
 			handler.notify.resourcesChanged();
 		}
-	});
+	}, options.onResourcesChanged);
 	const originOnlyDefault = allowedOrigins === void 0 && authorization === false;
 	async function handle(req, connection) {
 		const origin = req.headers.get("origin") ?? void 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/agentic",
   "type": "module",
-  "version": "1.2.6",
+  "version": "1.3.1",
   "description": "Agent-surface implementation for devframe: installing it next to devframe enables the MCP adapter (devframe/adapters/mcp) and the devframe connect gateway.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -30,19 +30,19 @@
     "dist"
   ],
   "peerDependencies": {
-    "devframe": "1.2.6"
+    "devframe": "1.3.1"
   },
   "dependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/server": "^2.3.1",
-    "h3": "^2.0.1",
+    "h3": "^2.0.7",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@types/node": "^26.6.4",
-    "devframe": "1.2.6",
-    "tsdown": "^0.23.0",
+    "@types/node": "^26.6.5",
+    "devframe": "1.3.1",
+    "tsdown": "0.23.0",
     "valibot": "^1.5.0"
   },
   "scripts": {