Repository navigation
feat(mcp): add appduct_list_events MCP tool (#125) - #144
Merged
Merged
Conversation
V3RON
commented
Oct 2, 2026
| | --- | --- | | ||
| | `appduct_connect` | Creates a connection link and opens it on a booted iOS Simulator or Android emulator it finds. If there's none, it returns a QR code for you to scan. | | ||
| | `appduct_wait_for_session` | Waits until the device connects. | | ||
| | `appduct_list_events` | Lists the events your app declared, as one-line signatures with descriptions. `name` filters to a glob, e.g. `"cart.*"`, and an exact name also returns the payload schema. Returns 50 at a time unless given `limit`; takes `offset`. Call it before waiting on an event. | `appduct events ls` | |
Contributor
Author
There was a problem hiding this comment.
nit: this table has two columns (Tool | What it does), so the third cell appduct events ls is dropped when the page renders and readers never see the CLI equivalent. Fold it into the description, e.g. "... Call it before waiting on an event. CLI: appduct events ls."
| Four more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name. | ||
|
|
||
| The other two give an agent a pull surface over `postEvent()`-pushed app events: `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time. | ||
| The other three give an agent a pull surface over `postEvent()`-pushed app events. `appduct_list_events` lists the events the app declared (`appduct events ls`) as signatures with descriptions, plus the payload schema when `name` is an exact name, so an agent learns the names before it waits on one. `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time. |
Contributor
Author
There was a problem hiding this comment.
nit: the paragraph above still opens with "Four more built-in tools", but it now covers two connection tools plus "the other three" here, five in all. Change "Four" to "Five" on line 226.
5 tasks done
…e-wire-and-list-th' into issue-125-add-appduct-list-events-mcp-tool
V3RON
added this pull request to stack #148
October 2, 2026 09:41
V3RON
marked this pull request as ready for review
October 2, 2026 09:41
This was referenced Oct 2, 2026
6 failing -> 0 failing
…e-wire-and-list-th' into issue-125-add-appduct-list-events-mcp-tool # Conflicts: # CHANGELOG.md
… page (#124) 2 failing -> 0 failing
…e-wire-and-list-th' into issue-125-add-appduct-list-events-mcp-tool
…e-wire-and-list-th' into issue-125-add-appduct-list-events-mcp-tool
Base automatically changed from
issue-124-declare-events-over-the-wire-and-list-th
to
main
October 2, 2026 11:16
…-list-events-mcp-tool # Conflicts: # CHANGELOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #125
Stacked on #143 (issue #124): base is that branch, not main. Part of #95.
What changed
Agents get an
appduct_list_eventsMCP tool that lists the events an app declared, with descriptions, and the payload schema whennameis an exact name. Docs: shipped skill, both READMEs, website,docs/ARCHITECTURE.md.Acceptance criteria
totalmcp-server.test.ts"returns one signature line with its description per declared event..."name: "cart.*"returns only matching eventspayload_schematotal: 0appduct events lsskills/appduct/SKILL.md,references/cli.md(already listedevents lsfrom #124)E2E evidence
Target: iOS simulator (iPhone 16 Pro, iOS 26.4), Expo playground, commit 53d4a1d. Branch daemon with isolated APPDUCT_STATE_DIR and OS-assigned wssPort (wssPort: 0).
Smoke: SMOKE_OK (throwing_tool: exit 72, type tool_execution_error)
Feature: appduct_list_events through
appduct mcp(stdio MCP client) against the live session; no SDK declares events yet.Checklist
CHANGELOG.mdhas an entry underUnreleased(writing-changelogskill), or the change is not user-visiblewriting-user-docsskill), or the change is not user-visibleindex.ts; no new directnode:*I/O outside an adapterarchitectureskill applied, exceptions explained abovedocs/ARCHITECTURE.mdupdated if a surface it describes changedOut of scope
policy-and-audit.integration.test.ts"a prompt tool call from the CLI (no consent channel)..." failed once in the full run and passed on rerun, untouched by this change; no issue filed yet.Status
Implement: done (5/5 green) Review: round 1, approve (2 nits fixed) E2E: pass (iOS) Ready: yes