spec: Define Adapter Element Type specification

[mickdarling]

Summary

Define the Adapter Element Type as a first-class element in the MCP-AQL specification. Adapters are Markdown files with YAML front matter that declaratively describe how to translate MCP-AQL CRUDE operations to target API calls.

Background

MCP-AQL adapters enable LLMs to interact with any API using a consistent interface. Rather than generating per-adapter code, a universal adapter runtime interprets schema files at call time.

Format

Adapters follow the same pattern as other element types (consistent with DollhouseMCP):

• YAML front matter containing all configuration and operation mappings
• Markdown body for human-readable documentation

Critical: Explicit Type Identification

All adapter files MUST include a type field in the YAML front matter:

---
name: github-api
type: adapter          # REQUIRED - explicit element type identification
version: "1.0.0"
# ...
---

This explicit identification is required because:

• Files may exist outside standard directory structures
• Enables tooling to identify element types without path inspection
• Supports collection/portfolio systems that aggregate multiple element types
• Provides clear schema validation targets

Proposed Schema Structure

Required Fields

Field	Type	Description
name	string	Unique identifier for the adapter
type	string	MUST be "adapter"
version	string	Semver version
description	string	Human-readable purpose
target	object	API connection configuration
operations	object	CRUDE operation mappings

Target Configuration

target:
  base_url: "https://api.example.com"
  transport: http       # Plugin reference
  protocol: rest        # Plugin reference
  serialization: json   # Plugin reference

Operation Mapping

operations:
  create:
    - name: create_resource
      maps_to: POST /resources
      description: "Create a new resource"
      params:
        title: { type: string, required: true }
        body: { type: string }
      response:
        type: object
        fields: [id, title, created_at]
  
  read:
    - name: list_resources
      maps_to: GET /resources
      pagination:
        style: cursor
      supports_fields: true
  
  # ... update, delete, execute

Optional Fields

Field	Type	Description
author	string	Creator attribution
tags	string[]	Searchable keywords
triggers	string[]	Activation keywords for LLM discovery
created	string	ISO timestamp
modified	string	ISO timestamp
auth	object	Authentication configuration
trust	object	Trust level metadata (#59)
rate_limits	object	Quota management (#60)

Design Principles

1. Schema IS the adapter - No separate code, no compilation
2. Declarative over imperative - Runtime interprets, doesn't execute
3. Introspection for free - Generated directly from schema
4. Hot reloadable - Change schema, behavior changes immediately
5. Human-readable - Markdown body provides documentation

Specification Deliverables

• Define complete YAML front matter schema
• Define operation mapping structure
• Define parameter type system
• Define response mapping structure
• Define pagination style options
• Define authentication configuration options
• Document error mapping conventions
• Create JSON Schema for validation (YAML-compatible)
• Add adapter examples for common API patterns

Related Issues

• Add Trust Levels to Adapter Schema #59 - Trust Levels (trust metadata in adapter schema)
• Add Rate Limiting and Quota Management to Adapter Schema #60 - Rate Limiting (rate_limits in adapter schema)
• spec: Document adapter generator specification #21 - Adapter Generator (outputs adapter schemas)
• spec: Create JSON Schema definitions #9 - JSON Schema definitions (needs adapter schema)
• spec(conformance): Introspection MUST document all handler-supported parameters #57 - Introspection completeness (adapters guarantee this)

Related Future Issues

• Plugin Interface Specification (to be created)
• Universal Adapter Runtime Specification (to be created)

[mickdarling]

Addition: File Naming Convention

Based on discussion, adding the following naming convention specification:

Pattern: {name}-adapter.md

Adapter files MUST follow the naming pattern {name}-adapter.md where {name} matches the name field in the YAML front matter.

Examples:

adapters/
├── github-api-adapter.md
├── slack-web-adapter.md
├── stripe-2024-adapter.md

Source of Truth

The YAML front matter name and type fields are authoritative. Filenames are for human convenience and tooling efficiency.

Resolution when divergent:

• Implementations MUST use metadata values for identity
• Implementations SHOULD emit a warning if filename doesn't match metadata
• Implementations MAY offer strict mode that rejects mismatched files

Related Files

Files associated with an adapter (tests, examples, source specs) SHOULD use the same name prefix:

{name}-adapter.md              # The adapter schema (primary)
{name}-adapter-tests.yaml      # Conformance tests
{name}-adapter-examples.md     # Usage examples  
{name}-adapter-openapi.yaml    # Source API spec (if applicable)

Rationale

1. No double-dot extensions - Avoids .adapter.md pattern which resembles security attack vectors (double extension masquerading)
2. Self-describing - Filename identifies both name and type without opening
3. Glob-friendly - *-adapter.md finds all adapters
4. Shareable - File is meaningful outside directory context
5. Consistent - Same pattern applies to all element types

Glob Patterns

*-adapter.md           # All adapter schemas
*-adapter*             # Adapter and all related files
github-*               # All github-related files
*-adapter-tests.yaml   # All adapter test files

YAML Front Matter Requirement

All adapter files MUST include explicit type identification:

---
name: github-api       # MUST match filename prefix
type: adapter          # MUST be "adapter"
version: "1.0.0"
# ...
---

This provides belt-and-suspenders identification: filename for humans, metadata for machines.