Skip to content

Commit b0e1f2b

Browse files
authored
feat(mcp): serve per-page resource templates and list_changed (#417)
Agents can read one page's component tree, signal graph, injector tree, NgRx store, forms or router as pangular://page/{pageId}/<name>, and get resources list_changed when a page connects or goes away. devframe 1.2.5 has no resource templates, so the local patches gain resourceTemplates and onResourcesChanged route options, like prompts. Refs #372.
1 parent e0d0ebe commit b0e1f2b

14 files changed

Lines changed: 1127 additions & 66 deletions

File tree

‎apps/docs/src/content/agents/mcp-server.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,10 @@ The argument is your own text. The server puts it on one line, cuts it at 200 ch
259259

260260
The stdio server offers no prompts. Like the instructions, the prompts need a devframe patch that devframe 1.2.5 does not ship, so an installed package offers none until devframe ships it.
261261

262+
### Resource templates
263+
264+
The HTTP endpoint also lists a resource template for each page-scoped resource, such as `pangular://page/{pageId}/component-tree`, and sends `notifications/resources/list_changed` when a page starts reporting or expires. See [Read one page](./resources.md#read-one-page).
265+
262266
### Tool names
263267

264268
The server registers tools with a colon, as `pangular:get-routes`. MCP clients see them with an underscore, as `pangular_get-routes`. Calls with either form work.

‎apps/docs/src/content/agents/resources.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,37 @@ Every form the page reported (Signal Forms, reactive and template-driven), with
7878

7979
The active route tree (params, data, guards, resolvers) and recent navigations of each page. When the data is too large, the resource returns the URL and recent navigations of each page, and points to `inspect-route`, `explain-navigation` and `list-routes`.
8080

81+
## Read one page
82+
83+
The six resources above hold every connected page. When several tabs or apps are connected, read one page through its own resource instead.
84+
85+
### Page resource templates
86+
87+
The HTTP endpoint lists one *MCP resource template per resource in `resources/templates/list`. Put a page id from [`list-pages`](./tools.md#list-pages) in the URI:
88+
89+
| Template | Same data as |
90+
| ----------------------------------------- | ------------------------- |
91+
| `pangular://page/{pageId}/component-tree` | `pangular:component-tree` |
92+
| `pangular://page/{pageId}/signal-graph` | `pangular:signal-graph` |
93+
| `pangular://page/{pageId}/injector-tree` | `pangular:injector-tree` |
94+
| `pangular://page/{pageId}/ngrx-store` | `pangular:ngrx-store` |
95+
| `pangular://page/{pageId}/forms` | `pangular:forms` |
96+
| `pangular://page/{pageId}/router` | `pangular:router` |
97+
98+
Each one returns the JSON of its resource with only that page in it, with the same `_untrusted` field and the same summary when it is too large. The selection made in the panel (`selectedId` and the like) is left out, since it belongs to no page. If no page with that id reports the data, the answer is a markdown note that lists the pages that do.
99+
100+
A template follows its resource: it is left out when the inspector is off through `inspectors` or `agent.tools`.
101+
102+
### Per-page entries in the list
103+
104+
Some clients don't read templates. For them, `resources/list` also names one resource per reporting page, such as `pangular://page/<pageId>/component-tree`.
105+
106+
### List changes
107+
108+
When a page starts reporting or expires, the server sends `notifications/resources/list_changed`, so a client can list the resources again. Changes settle for half a second first, and a report from a page that is already listed sends nothing.
109+
110+
Like the prompts, the templates need a devframe patch that devframe 1.2.5 does not ship. The stdio server has no templates, since no page connects to it.
111+
81112
## Shared state
82113

83114
The devtools keep their live data in shared-state keys. Every key is also listed as a resource, at `devframe://state/<key>` with the key encoded.

‎apps/docs/src/content/contributing/development.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,15 +45,16 @@ pnpm install
4545

4646
`patches/` holds `pnpm patch` changes to the built files of `devframe`, `@devframes/agentic` and `@devframes/hub` 1.2.5, listed under `patchedDependencies` in `pnpm-workspace.yaml`. They add what devframe doesn't ship:
4747

48-
| Patch | What it adds | Used by |
49-
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
50-
| `instructions` | An MCP route option, sent as `instructions` in the `initialize` result. Patched in `devframe`, `@devframes/hub` and `@devframes/agentic`. | `pangularMcp()` in `packages/devtools/src/agent-mcp.ts` |
51-
| `prompts` | An MCP route option with prompt templates. `@devframes/agentic` declares the `prompts` capability and answers `prompts/list` and `prompts/get` (invalid params for an unknown prompt or a missing required argument). Patched in `devframe`, `@devframes/hub` and `@devframes/agentic`. | `pangularMcpPrompts()` in `packages/devtools/src/agent-prompts.ts`, through `pangularMcp()` |
52-
| `mcpContent` answers | `@devframes/agentic` sends a tool result's `mcpContent` blocks (`text` and `image`) as the MCP content, instead of the result as JSON. | `screenshot-component`, through `withMcpContent()` in `rpc/component-screenshots.ts` |
48+
| Patch | What it adds | Used by |
49+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
50+
| `instructions` | An MCP route option, sent as `instructions` in the `initialize` result. Patched in `devframe`, `@devframes/hub` and `@devframes/agentic`. | `pangularMcp()` in `packages/devtools/src/agent-mcp.ts` |
51+
| `prompts` | An MCP route option with prompt templates. `@devframes/agentic` declares the `prompts` capability and answers `prompts/list` and `prompts/get` (invalid params for an unknown prompt or a missing required argument). Patched in `devframe`, `@devframes/hub` and `@devframes/agentic`. | `pangularMcpPrompts()` in `packages/devtools/src/agent-prompts.ts`, through `pangularMcp()` |
52+
| `resourceTemplates` | MCP route options for resource templates and a host hook for resource list changes. `@devframes/agentic` answers `resources/templates/list`, reads a URI through the first template that matches it (`{name}` variables only, one URI segment each), adds each template's `list()` entries to `resources/list`, and sends `notifications/resources/list_changed` when `onResourcesChanged` calls back. Patched in `devframe`, `@devframes/hub` and `@devframes/agentic`. | `pangularMcpResourceTemplates()` and `pangularMcpPagesChanged()` in `packages/devtools/src/agent-page-resources.ts`, through `pangularMcp()` |
53+
| `mcpContent` answers | `@devframes/agentic` sends a tool result's `mcpContent` blocks (`text` and `image`) as the MCP content, instead of the result as JSON. | `screenshot-component`, through `withMcpContent()` in `rpc/component-screenshots.ts` |
5354

5455
The `exposeSharedState` filter, which hides the shared-state keys of an inspector with `agent.tools.<name>: false`, is part of devframe since 1.2.4 and needs no patch.
5556

56-
The patches apply only inside this repository. An app that installs the published package gets no server `instructions` and no prompts, and `screenshot-component` answers with its text note only, until devframe ships them. Each patch names an exact version and file names with build hashes, so a devframe upgrade needs the patches redone with `pnpm patch`, or removed once devframe has the feature.
57+
The patches apply only inside this repository. An app that installs the published package gets no server `instructions`, no prompts and no page resource templates, and `screenshot-component` answers with its text note only, until devframe ships them. Each patch names an exact version and file names with build hashes, so a devframe upgrade needs the patches redone with `pnpm patch`, or removed once devframe has the feature.
5758

5859
## Project structure
5960

‎docs/CONTEXT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ An MCP prompt: a ready request for one workflow, such as `debug-error` or `fix-f
9393
_Avoid_: template, command, skill (a skill is a `SKILL.md` folder the agent reads)
9494

9595
**Resource**:
96-
Live state an agent reads as JSON over MCP, such as `pangular:component-tree`. It holds what the connected pages reported, so it is empty when no page is connected.
96+
Live state an agent reads as JSON over MCP, such as `pangular:component-tree`. It holds what the connected pages reported, so it is empty when no page is connected. Each page-scoped resource also has a per-page resource template, `pangular://page/{pageId}/<name>`, that holds one page (`packages/devtools/src/agent-page-resources.ts`).
9797
_Avoid_: snapshot, feed, state dump
9898

9999
**Source scan**:

‎packages/devtools/src/__tests__/agent-metadata.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
type AgentEntryKind,
1717
type PangularConfig,
1818
} from '../config.ts';
19+
import { PAGE_RESOURCE_NAMES } from '../agent-page-resources.ts';
1920
import { createPangular, type PangularHostOptions } from '../devframe.ts';
2021
import { travelServerPlugin } from '../../../../src/app/devtools/travel-plugin.server.ts';
2122

@@ -112,6 +113,18 @@ describe('agent metadata', () => {
112113
expect(Object.keys(AGENT_ENTRIES).filter((name) => !kinds.has(name))).toEqual(page);
113114
});
114115

116+
// Per-page MCP resource templates are route options, not agent registrations,
117+
// so they have no entry of their own: each one follows its page resource's entry.
118+
it('maps each per-page resource template to a page resource entry', () => {
119+
for (const name of PAGE_RESOURCE_NAMES) {
120+
expect(AGENT_ENTRIES[name], name).toMatchObject({ kind: 'resource', page: true });
121+
}
122+
const pageResources = Object.keys(AGENT_ENTRIES).filter(
123+
(name) => AGENT_ENTRIES[name]?.kind === 'resource' && AGENT_ENTRIES[name]?.page,
124+
);
125+
expect(sorted(pageResources)).toEqual(sorted(PAGE_RESOURCE_NAMES));
126+
});
127+
115128
it('keeps each entry consistent', () => {
116129
for (const [name, entry] of Object.entries(AGENT_ENTRIES)) {
117130
expect(name, name).not.toMatch(/^(pangular|plugin):/);

0 commit comments

Comments
 (0)