AdaMCP - MCP Server for AdaEngine

AdaMCP exposes a live AdaEngine application as an MCP server. It is built for inspection-first workflows: world/entity/resource introspection, render capture, and AdaUI tree inspection with a small set of safe UI actions.

📚 Check documentation to learn more

Current platform support

The important distinction is:

• MCP clients can live anywhere and connect over HTTP or stdio.
• The host runtime now builds on the broader Apple surface, while stdio remains primarily a local host transport and HTTP is the main cross-device option.

What you get 🌸

• 😳 World, entity, component, resource, and asset inspection.
• 📸 Screenshot capture for live render output.
• 💉 AdaUI inspection tools such as ui.list_windows, ui.get_tree, ui.get_node, ui.find_nodes, ui.capture_node_screenshot, and ui.hit_test.
• 🧑‍🏫 AdaUI diagnostics and safe actions such as focus traversal, deterministic tap, and scroll-to-node.
• 📦 MCP resources under ada://..., including ada://ui/windows, ada://ui/window/{id}, ada://ui/tree/{id}, and ada://ui/node/{windowId}/{nodeRef}.

Embedding in an AdaEngine app ⚒️

Until the package is published, add it as a local SwiftPM dependency:

dependencies: [
    .package(url: "https://github.com/AdaEngine/AdaMCP.git", branch: "main")
]

Then add the plugin to your app:

import AdaEngine
import AdaMCPPlugin

@main
struct ExampleApp: App {
    var body: some AppScene {
        WindowGroup {
            RootView()
        }
        .addPlugins(
            MCPPlugin(configuration: .init(
                enableHTTP: true,
                enableStdio: true,
                host: "127.0.0.1",
                port: 2510,
                endpoint: "/mcp",
                serverName: "example-app",
                serverVersion: "0.1.0",
                instructions: "Inspect the live AdaEngine runtime."
            ))
        )
    }
}

Connect from an agent with npx

Install the MCP server in your agent configuration with the npm package:

{
  "mcpServers": {
    "adamcp": {
      "command": "npx",
      "args": ["-y", "adamcp@latest"]
    }
  }
}

The adamcp CLI speaks MCP over stdio to the agent. It discovers live AdaEngine apps through AdaMCP discovery manifests and connects to the selected app over HTTP. If no app is running, the router starts successfully and tells the agent to build and launch the AdaEngine app before continuing.

Useful overrides:

• ADAMCP_URL or --url connects directly to an HTTP MCP endpoint.
• ADAMCP_SERVER or --server selects a discovery manifest by exact id or unique serverName.
• ADAMCP_DISCOVERY_DIR or --discovery-dir points at a custom manifest directory.
• ADAMCP_STDIO_COMMAND or --stdio-command launches an AdaEngine app/server as a child stdio MCP process and proxies bytes transparently.

When multiple live apps are found, use the router tools adamcp.list_servers and adamcp.select_server. Before publishing, make sure the npm registry target has the adamcp package name available; the local npm config used during development currently returns 404 for npm view adamcp.

AdaUI surface

AdaUI support is intentionally inspection-first. The main flow is:

1. Locate windows or nodes.
2. Inspect the live tree and layout diagnostics.
3. Apply a limited, deterministic action.
4. Re-read the tree or diagnostics to verify the result.

External callers should target nodes by accessibilityIdentifier. ui.find_nodes can also search by nodeType or viewType, for example to locate all scroll views. runtimeId is returned in payloads as a session-local helper, but it is not intended to be a durable contract.