Adapter patterns are where the protocol meets the target system
These pages are the browse-first guide to how MCP-AQL changes shape across different environments. The formal rules still live in the spec and contract docs, but the pattern pages help implementers choose the right modeling, safety, and runtime posture before they drop into the details.
On this page
Jump to a section
Use the outline to move through longer pages without losing your place.
Related reading
What this section is for
Use this hub when you know you need adapter guidance, but you have not yet decided which target-system shape best matches the thing you are adapting.
- Start here to compare the major environment types quickly.
- Use the child pages for environment-specific caveats and examples.
- Cross-check each decision against the website-hosted spec pages instead of bouncing back to repo Markdown.
How to read it alongside the spec
The pattern pages are implementation-facing guidance, not normative rules. They narrow the problem and then route you to the correct spec material.
Pattern Library
Pick the closest environment first. The child pages are there to turn that choice into better contract and runtime decisions.
MCP Server
Primary protocol fitFor native MCP tool surfaces that need introspection-preserving consolidation into CRUDE or single-mode MCP-AQL operations.
Application
Product API fitFor desktop, mobile, and product-function surfaces where user-facing actions need a clearer operation contract.
Cloud Service
External API fitFor remote APIs where quotas, retries, pagination, and provider failure semantics shape the adapter design.
Operating System
Local execution fitFor file, process, and system-level operations where permission, confirmation, and policy controls must be explicit.
Website / Web API
Web workflow fitFor retrieval-heavy or action-heavy web flows where scraping, APIs, navigation, and side effects can overlap.
Repo-Synced Implementation Reference
The implementation architecture is now mirrored onto the website too, so these pattern pages can point into real runtime docs instead of stopping at conceptual guidance.
Architecture Overview
Read the internal adapter shape, request flow, and design principles from the reference adapter repo.
Universal Runtime
See how schema loading, dispatch, request building, response handling, and error mapping are expected to work.
Development Guide
Use the practical build guidance when you move from choosing a pattern to implementing one.
Testing Guide
Cover handler tests, routing tests, introspection checks, and conformance workflow from the same website docs experience.
Migration Guide
Use the MCP server migration guide when you are consolidating an existing tool surface into MCP-AQL operations.
Implementation ADRs
Browse the accepted implementation decisions behind the reference adapter architecture and plugin pipeline.
Cross-Cutting Questions
What is being adapted?
Name the real upstream surface clearly: tools, app actions, cloud endpoints, local system operations, or website flows.
Where is the safety boundary?
The right pattern often turns on where cost, permissions, confirmation, or destructive behavior actually lives.
Which spec pages matter most?
The hub helps answer that question early so implementers can go deeper with less wandering and less duplication.