Skip to content

Commit 9e55908

Browse files
committed
feat(mcp): add a wait-for agent tool
Agents that click or navigate no longer have to poll other tools in a loop. pangular:wait-for blocks, up to timeoutMs, until a component appears or goes, a navigation settles, an HttpClient call finishes or a new error arrives. It only reads what the collectors already pushed. Refs #372.
1 parent f76a56b commit 9e55908

11 files changed

Lines changed: 861 additions & 13 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,7 @@ A tool answers with a JSON object, sent as text. Most tools answer `{ "markdown"
255255
| ----------------------------------------------------------------------------------------------------------- | ------------------------------ |
256256
| Every tool whose name starts with `list-` or `inspect-` | `{ "markdown": "..." }` |
257257
| `analog-routes`, `analog-api-routes`, `analog-server-functions`, `analog-server-calls` and `analog-content` | `{ "markdown": "..." }` |
258+
| `wait-for` | `{ "markdown": "..." }` |
258259
| `build-meta` | The project and version fields |
259260

260261
The other source scan tools answer with a JSON array, and `screenshot-component` with an image, so they send text and images only.

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

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Every agent tool the devtools expose, grouped by inspector, with wh
44
---
55

66
<ngmd-hero title="Tools" logo="https://cdn.simpleicons.org/modelcontextprotocol/71717A" gradient>
7-
Ninety-five tools, grouped by inspector. Each one answers a question you would otherwise answer by clicking through the panel.
7+
Ninety-six tools, grouped by inspector. Each one answers a question you would otherwise answer by clicking through the panel.
88
</ngmd-hero>
99

1010
# Tools
@@ -63,6 +63,29 @@ Gives the user a link that opens the panel on one tab with one item selected, an
6363

6464
The answer is a full URL, such as `http://localhost:4200/__devframes/pangular/#tab=components&id=12&page=k3x9`, when the hub serves the panel and a page has reported its address. Otherwise it is the hash to add to the panel's address. Each panel that is open and not in a background tab opens the link at once. The tool is `read`: it changes what the panel shows, not the app. See [Deep links](../getting-started/popup-and-hub.md#deep-links).
6565

66+
### wait-for
67+
68+
Waits until a condition holds on a page, then answers. Use it after a click, a navigation or an action instead of calling another tool in a loop. Reads: page. It reads what the collectors already reported and never changes the page. It answers as soon as the condition holds, or after `timeoutMs` with `Timed out after <n>ms` and the last state it saw.
69+
70+
| Condition | Holds when | Argument | Inspector |
71+
| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------ | ---------- |
72+
| `component` | A component matching `selector` is rendered. | `selector` (required) | Components |
73+
| `component-gone` | No component matches `selector` any more. | `selector` (required) | Components |
74+
| `navigation` | The router has no navigation in progress, and its URL matches `url` when given. | `url` | Router |
75+
| `http-call` | An HttpClient call finished after the wait started, and its URL matches `url` when given. | `url` | SSR & HTTP |
76+
| `error` | A new error was captured after the wait started, with the Angular code `code` when given. | `code`, such as `NG0100` | Errors |
77+
78+
| Argument | Required | What it is |
79+
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
80+
| `condition` | Yes | One of the conditions above. |
81+
| `selector` | No | An instance id, class name or host tag, as in `highlight`. |
82+
| `url` | No | Text the URL contains. `*` matches anything and a leading `^` anchors it at the start of the path, as in [fault rules](#fault-rules). |
83+
| `code` | No | An Angular error code. |
84+
| `timeoutMs` | No | How long to wait. Default 5000, at most 30000. |
85+
| `page` | No | The page id. Without it, every page counts, and `navigation` uses the most recent page. `pageId` is accepted too. |
86+
87+
Without `url`, `navigation` holds as soon as no navigation is in progress, which can be before a navigation you just started reaches the page. Pass `url` to wait for the destination. A condition is offered only while its inspector is on for agents, and the tool is dropped when all four are off.
88+
6689
### Action tools
6790

6891
Every tool has one of three safety tiers. The server sends the tier to your client as the tool's read-only and destructive hints.
@@ -81,7 +104,7 @@ When the hub is mounted, each finished call of an `action` or `destructive` tool
81104

82105
### Turn tools off
83106

84-
The server decides which tools exist. Set `agent.readOnly` to keep only the `read` tools. `change-detection` stays as a `read` tool without its `record`, `flash`, `track` and `angularProfiling` arguments, so it reads a recording the panel started. `hydration` stays as a `read` tool without its `overlay` argument, and `audit` without its `axe` argument, so it reads the last axe pass the panel ran. Set `agent.tools.<inspector>` to `false` to hide one inspector's tools and resources, and keep its tab. Turning an inspector off with `inspectors`, or blocking an action with `actions`, drops the matching tools too. A [plugin's own tools](#plugins) follow the same switches, with the tier the plugin declares. `actions.router` is the exception: `navigate` stays for `instrument` and `resolve-lazy`, and refuses `navigate`, `abort`, `replay` and `probe`. See [Inspectors and agent tools](../getting-started/configuration.md#inspectors-and-agent-tools).
107+
The server decides which tools exist. Set `agent.readOnly` to keep only the `read` tools. `change-detection` stays as a `read` tool without its `record`, `flash`, `track` and `angularProfiling` arguments, so it reads a recording the panel started. `hydration` stays as a `read` tool without its `overlay` argument, and `audit` without its `axe` argument, so it reads the last axe pass the panel ran. Set `agent.tools.<inspector>` to `false` to hide one inspector's tools and resources, and keep its tab. Turning an inspector off with `inspectors`, or blocking an action with `actions`, drops the matching tools too. `wait-for` stays while any of the Components, Router, SSR & HTTP and Errors inspectors is on, with only the conditions of the inspectors that are. A [plugin's own tools](#plugins) follow the same switches, with the tier the plugin declares. `actions.router` is the exception: `navigate` stays for `instrument` and `resolve-lazy`, and refuses `navigate`, `abort`, `replay` and `probe`. See [Inspectors and agent tools](../getting-started/configuration.md#inspectors-and-agent-tools).
85108

86109
## Source scan
87110

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,7 @@ Give every registered tool and resource an entry in `AGENT_ENTRIES` in `packages
255255
| `actions` | The `actions` keys it writes for, so blocking them drops it |
256256
| `freeModes` | The modes that still work while those actions are blocked |
257257
| `page` | `true` when it needs a connected page, the app's dev server or the panel, so the stdio MCP server leaves it out |
258+
| `anyInspector` | `true` when it stays while any of its `inspectors` is on, not only the first |
258259

259260
`packages/devtools/src/__tests__/agent-metadata.test.ts` boots the server and fails when a registered tool has no entry, or an entry has no registered tool. It also compares the derived lists with `packages/devtools/src/__tests__/fixtures/agent-metadata-derived.json`, so update that file with the tool and the reviewer sees what changed. See [Configuration](../getting-started/configuration.md).
260261

0 commit comments

Comments
 (0)