Example adapter configurations for MCP-AQL (Model Context Protocol - Advanced Agent API Adapter Query Language).
This repository contains example adapter schemas that demonstrate how to use MCP-AQL to wrap real-world APIs. These examples are non-normative reference material.
For normative protocol specifications, see the spec repository.
| Example | Description | API |
|---|---|---|
| GitHub API Adapter | Complete adapter for GitHub REST API v3 | GitHub REST API |
| Example | Description | Source |
|---|---|---|
| GitHub MCP Golden Path | End-to-end capture, discovery bundle, generated schema, adapter, and validation artifacts | GitHub MCP server |
| Playwright MCP Golden Path | End-to-end capture, discovery bundle, generated schema, adapter, and validation artifacts | Playwright MCP server |
| Example | Description | Source |
|---|---|---|
| AirPods Head-Tracking Adapter | Live head-pose streaming (~25 Hz yaw/pitch/roll) behind a CRUDE surface, with a WebSocket HUD and a gaze-driven window-focus sidecar. Runnable today: anyone with AirPods Pro and an Apple Silicon Mac can use it — prebuilt binaries are linked in its README. | AirPods Pro IMU via Apple's CMHeadphoneMotionManager |
| Shortcut Remote JIT Adapter | Just-in-time observational HID discovery of an undocumented $30 keypad: captured raw reports, mechanically derived the byte layout, and emitted a CRUDE adapter with a live HUD, layered keystroke dispatch, and a kill-switch menu-bar app. Companion to the AirPods adapter (hardware-trigger recenter). | XP-Pen Shortcut Remote (Hanvon Ugee ACK05) via raw HID |
The current golden-path tooling supports upstream source MCP servers over streamable_http.
The generated adapters themselves run as local MCP servers over stdio, so a typical demo flow today looks like:
- start or expose the upstream MCP server over HTTP
- generate or use the committed MCP-AQL adapter artifacts
- run the generated adapter locally as a
stdioMCP server - connect your MCP client to that generated adapter
Why this is cleaner right now:
- the upstream HTTP server can stay up independently of your MCP client lifecycle
- the local generated adapter can be started and stopped by your MCP host without also having to supervise the upstream source server
- this is especially helpful for stateful MCP servers like Playwright, where restarting the upstream process may reset browser state
Each example adapter is a Markdown file with YAML front matter following the Adapter Element Type Specification. The front matter contains all operation mappings, and the Markdown body provides human-readable documentation.
- Copy an example adapter as a starting point
- Modify the
target,auth, andoperationssections for your API - Load the adapter schema in the universal adapter runtime
| Repository | Purpose |
|---|---|
| spec | Protocol specification, schemas, conformance tests |
| mcpaql-adapter | Reference adapter implementation |
| adapter-generator | Tool to generate adapters from API specs |
- Documentation: CC BY 4.0
- Code/schemas/tests: AGPL-3.0
See LICENSE, COMMERCIAL-LICENSE.md, NOTICE.md, and TRADEMARKS.md for details.