REPO-SYNCED SPEC DOC

MCP-AQL Specification Documentation

This directory contains the MCP-AQL specification set:

Support document

Source: spec/docs/README.md

Open Source MarkdownBrowse Full Spec Reference

On this page

Jump to a section

Use the outline to move through longer pages without losing your place.

  1. Document Organization
  2. Core Specification
  3. Plugin & Adapter Contracts
  4. Features
  5. Security
  6. Process
  7. Guides
  8. Roadmap
  9. Reading Order
  10. Cross-Repository Content
  11. Reference Profile
  12. Contributing
  13. License

This directory contains the MCP-AQL specification set:

In case of conflict, the versioned normative document takes precedence.

Implementation architecture documentation is maintained in the mcpaql-adapter repository. Example adapters are in the examples repository.

Document Organization

Core Specification

Document Description Status
v1.0.0-draft Current specification version Draft
CRUDE Pattern Standard semantic-endpoint profile and routing Draft
Endpoint Modes Semantic endpoint mode and Single mode configuration Draft
Introspection Runtime discovery system Draft
Operations Operation design guide Draft
Error Codes Structured error code system Draft (MVP)
Conformance Testing Test requirements plus the fixture-driven runner model used in this repo Draft

Plugin & Adapter Contracts

Document Description Status
Plugin Interface Contracts What each plugin type MUST provide Draft (MVP)
Element Type Specification Declarative adapter schema format Draft (MVP)
MCP Server Discovery Bundle Raw capture + normalized bundle contract for generator pipelines Draft

Features

Document Description Impl Status
Field Selection GraphQL-style response filtering Implemented
Collection Querying Preferred query contract for list/search/query operations Draft
Aggregations Server-side summaries for collection queries Draft
Computed Fields Adapter-declared derived values and _computed. paths Draft
Pagination Cursor-based pagination semantics and response shape Draft
Relationship Queries Graph traversal and relationship query conventions Draft

Security

Document Description Impl Status
Gatekeeper Multi-layer access control Implemented

Process

Document Description
RFC Process How to propose specification changes
Breaking Changes Policy for handling breaking changes
Versioning Version numbering and release process
Preliminary Launch Checklist Coordinated draft-launch criteria

Guides

Document Description
Protocol Comparison MCP-AQL vs other protocols
Cross-Domain Implementation Step-by-step guide for adapting MCP-AQL to domains beyond Dollhouse-style element management

Roadmap

Future features are tracked as GitHub issues. Key upcoming features:

Phase 0 - MVP Core:

  • Adapter Element Type (#61)
  • Plugin Interface (#62)
  • Universal Adapter Runtime (#63)
  • Structured error codes (#35)

Phase 1 - Robustness:

  • Trust levels (#59)
  • Dangerous operation classification (#49)
  • Rate limiting (#60)
  • Cursor-based pagination (#37)

Phase 2+ - Advanced:

  • Streaming responses (#43)
  • Schema versioning (#48)

Reading Order

For newcomers to MCP-AQL:

  1. v1.0.0-draft - Start with the main specification
  2. CRUDE Pattern - Understand the standard semantic-endpoint profile
  3. Operations - Learn operation design patterns
  4. Introspection - Learn the discovery system
  5. Conformance Testing - Understand conformance requirements

For adapter developers:

  1. Element Type Specification - Declarative schema format
  2. Plugin Interface Contracts - Plugin system contracts
  3. Architecture Overview - Understand adapter structure (in mcpaql-adapter repo)
  4. Development Guide - Implementation walkthrough (in mcpaql-adapter repo)
  5. Gatekeeper - Security implementation

Cross-Repository Content

MCP-AQL follows a four-level protocol model:

Level What Normative? Repository
1. Wire format Request/response JSON, error codes, introspection MUST this repo
2. Schema semantics Operation declarations, params, auth, target MUST/SHOULD this repo
3. Canonical format Markdown + YAML front matter interchange format SHOULD this repo
4. Implementation guidance Runtime architecture, plugin pipeline, dispatch Non-normative mcpaql-adapter

Example adapters: examples

Reference Profile

DollhouseMCP is treated as a practical reference profile for MCP-AQL. It validates feasibility at scale, but protocol authority remains with the normative specification in this repository.

Contributing

See CONTRIBUTING.md for guidelines on contributing to the specification.

License

  • Specification text: CC BY 4.0
  • Code/schemas/tests: AGPL-3.0

See LICENSING.md for details.