Adapter Generator Specification

interface AdapterSchema {
  /**
   * Schema format version
   */
  schema_version: '1.0';

  /**
   * Adapter metadata
   */
  adapter: {
    /** Unique adapter identifier */
    name: string;
    /** Human-readable display name */
    display_name: string;
    /** Adapter version (semver) */
    version: string;
    /** Brief description */
    description: string;
    /** Target API being adapted */
    target_api: {
      name: string;
      base_url: string;
      version?: string;
    };
  };

  /**
   * Authentication configuration
   */
  auth?: {
    type: 'api_key' | 'oauth2' | 'bearer' | 'basic' | 'none';
    config?: Record<string, unknown>;
  };

  /**
   * Operation definitions by endpoint
   */
  endpoints: {
    create?: OperationDefinition[];
    read?: OperationDefinition[];
    update?: OperationDefinition[];
    delete?: OperationDefinition[];
    execute?: OperationDefinition[];
  };

  /**
   * Custom type definitions
   */
  types?: TypeDefinition[];
}

interface OperationDefinition {
  /** Operation name (snake_case) */
  name: string;
  /** Human-readable description */
  description: string;
  /** Input parameters */
  params: ParameterDefinition[];
  /** Output schema */
  returns: TypeReference;
  /** Danger level for security classification */
  danger_level?: 'safe' | 'reversible' | 'destructive' | 'dangerous' | 'forbidden';
  /** HTTP method and path for target API */
  http?: {
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    path: string;
  };
}

interface ParameterDefinition {
  name: string;
  type: TypeReference;
  required: boolean;
  description?: string;
  default?: unknown;
}

type TypeReference =
  | 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array'
  | { array: TypeReference }
  | { object: Record<string, TypeReference> }
  | { ref: string };

interface TypeDefinition {
  name: string;
  fields: ParameterDefinition[];
}

{
  "success": false,
  "error": {
    "code": "SCHEMA_INVALID_TYPE",
    "message": "Field 'endpoints.read[0].params[0].required' expected boolean, got string",
    "details": {
      "field_path": "endpoints.read[0].params[0].required",
      "expected_type": "boolean",
      "actual_type": "string",
      "actual_value": "true",
      "suggestion": "Use `required: true` instead of `required: \"true\"`"
    }
  }
}

schema_version: '1.0'
adapter:
  name: example_api
  display_name: Example API
  version: 1.0.0
  description: Example adapter for demonstration
  target_api:
    name: Example Service
    base_url: https://api.example.com/v1
endpoints:
  read:
    - name: get_item
      description: Retrieve an item by ID
      params:
        - name: id
          type: string
          required: true
      returns: object
      http:
        method: GET
        path: /items/{id}

schema_version: '1.0'
adapter:
  name: github_api
  display_name: GitHub API
  version: 1.0.0
  description: MCP-AQL adapter for GitHub REST API
  target_api:
    name: GitHub REST API
    base_url: https://api.github.com
    version: '2022-11-28'
auth:
  type: bearer
  config:
    header_name: Authorization
    prefix: 'Bearer '
types:
  - name: Repository
    fields:
      - name: id
        type: integer
        required: true
      - name: name
        type: string
        required: true
      - name: full_name
        type: string
        required: true
      - name: private
        type: boolean
        required: true
endpoints:
  read:
    - name: get_repo
      description: Get a repository by owner and name
      params:
        - name: owner
          type: string
          required: true
        - name: repo
          type: string
          required: true
      returns:
        ref: Repository
      http:
        method: GET
        path: /repos/{owner}/{repo}
  delete:
    - name: delete_repo
      description: Delete a repository
      params:
        - name: owner
          type: string
          required: true
        - name: repo
          type: string
          required: true
      returns: object
      danger_level: destructive
      http:
        method: DELETE
        path: /repos/{owner}/{repo}

function validateSchemaVersion(schema) {
  const supportedVersions = ['1.0', '1.1'];
  const deprecatedVersions = ['0.9'];

  if (supportedVersions.includes(schema.schema_version)) {
    return { valid: true };
  }

  if (deprecatedVersions.includes(schema.schema_version)) {
    return {
      valid: false,
      code: 'SCHEMA_VERSION_DEPRECATED',
      message: `Schema version '${schema.schema_version}' is deprecated`,
      migration_guide: 'https://mcpaql.org/docs/schema-migration'
    };
  }

  return {
    valid: false,
    code: 'SCHEMA_VERSION_UNSUPPORTED',
    message: `Unknown schema version '${schema.schema_version}'`,
    supported_versions: supportedVersions
  };
}

# {Adapter Display Name}

> Generated by MCP-AQL Adapter Generator v{version}

## Overview

{Description from schema}

## Installation

{Language-specific installation instructions}

## Usage

{Basic usage example}

## Operations

### Create Operations
{List with descriptions}

### Read Operations
{List with descriptions}

### Update Operations
{List with descriptions}

### Delete Operations
{List with descriptions}

### Execute Operations
{List with descriptions}

## Provenance

This adapter was generated from schema `{schema_fingerprint}`.
See MCPAQL-PROVENANCE.json for full generation metadata.

## License

This adapter is dual-licensed:
- AGPL-3.0 for open source use (see LICENSE)
- Commercial license available (see COMMERCIAL-LICENSE.md)

# Attribution Notice

This software was generated using the MCP-AQL Adapter Generator.

## MCP-AQL Project

- Website: https://mcpaql.org
- Specification: https://github.com/MCPAQL/spec
- Generator: https://github.com/MCPAQL/adapter-generator

## License

This adapter is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
A commercial license is available for organizations that cannot comply with AGPL terms.

## Third-Party Components

{List any third-party libraries used in generated code}

## Generation Information

- Generator Version: {generator_version}
- Generated: {timestamp}
- Schema: {schema_fingerprint}

# Commercial Licensing

This MCP-AQL adapter is dual-licensed:

## Open Source License (AGPL-3.0)

The default license for this adapter is the GNU Affero General Public License v3.0.
This license requires that:

- Source code modifications are shared under the same license
- Network use (e.g., SaaS) triggers distribution requirements
- Attribution is maintained

See the LICENSE file for full terms.

## Commercial License

Organizations that cannot comply with AGPL-3.0 requirements may obtain a commercial license.

### Commercial License Benefits

- No copyleft obligations
- No source code disclosure requirements
- Priority support available
- Custom terms available

### Contact

For commercial licensing inquiries:

- Email: licensing@mcpaql.org
- Website: https://mcpaql.org/licensing

## Contributor License Agreement

Contributors to this adapter may be asked to sign a CLA to enable dual licensing.

interface ProvenanceInfo {
  /**
   * MCP-AQL specification version the generator targets
   */
  mcpaql_spec_version: string;

  /**
   * Generator identification
   */
  generator: {
    /** Generator name (e.g., "mcpaql-adapter-generator") */
    name: string;
    /** Generator version (semver) */
    version: string;
    /** Git commit hash of generator (if available) */
    commit?: string;
    /** Generator repository URL */
    repository?: string;
  };

  /**
   * Source schema information
   */
  schema: {
    /** SHA-256 hash of the input schema */
    fingerprint: string;
    /** Original schema filename */
    filename: string;
    /** Schema version from adapter.version */
    version: string;
  };

  /**
   * Generation metadata
   */
  generation: {
    /** ISO 8601 timestamp of generation */
    timestamp: string;
    /** Target language/platform */
    target: string;
    /** Generator options used */
    options?: Record<string, unknown>;
  };

  /**
   * Verification information
   */
  verification?: {
    /** SHA-256 hash of generated code (excluding provenance file) */
    code_hash: string;
    /** Conformance test results if run during generation */
    conformance_result?: 'passed' | 'failed' | 'skipped';
  };
}

{
  "mcpaql_spec_version": "1.0.0",
  "generator": {
    "name": "mcpaql-adapter-generator",
    "version": "1.2.3",
    "commit": "abc123def456",
    "repository": "https://github.com/MCPAQL/adapter-generator"
  },
  "schema": {
    "fingerprint": "sha256:a1b2c3d4e5f6...",
    "filename": "github-api.yaml",
    "version": "1.0.0"
  },
  "generation": {
    "timestamp": "2026-01-29T10:30:00Z",
    "target": "typescript",
    "options": {
      "strict_mode": true,
      "include_tests": true
    }
  },
  "verification": {
    "code_hash": "sha256:f6e5d4c3b2a1...",
    "conformance_result": "passed"
  }
}

function calculateFingerprint(schema: AdapterSchema): string {
  // Recursively sort object keys for canonical JSON
  function sortKeys(obj: unknown): unknown {
    if (Array.isArray(obj)) {
      return obj.map(sortKeys);
    }
    if (obj !== null && typeof obj === 'object') {
      const sorted: Record<string, unknown> = {};
      for (const key of Object.keys(obj).sort()) {
        sorted[key] = sortKeys((obj as Record<string, unknown>)[key]);
      }
      return sorted;
    }
    return obj;
  }

  const normalized = JSON.stringify(sortKeys(schema));
  const hash = crypto.createHash('sha256').update(normalized).digest('hex');
  return `sha256:${hash}`;
}

import { createEndpoints } from './operations';
import { AdapterConfig } from './types';
import { schema } from '../schema/adapter';

export class Adapter {
  private config: AdapterConfig;

  constructor(config: AdapterConfig) {
    this.config = config;
  }

  async handleRequest(endpoint: string, request: unknown) {
    const endpoints = createEndpoints(this.config);
    const handler = endpoints[endpoint];

    if (!handler) {
      return {
        success: false,
        error: {
          code: 'NOT_FOUND_OPERATION',
          message: `Unknown endpoint: '${endpoint}'`
        }
      };
    }

    return handler(request);
  }

  getSchema() {
    return schema;
  }
}

export { schema };

mcpaql-generate --schema <path> --target <language> [options]

# Human-readable output (default)
mcpaql-generate --schema adapter.yaml --target typescript

# JSON output for programmatic consumption
mcpaql-generate --schema adapter.yaml --target typescript --output-format json

{
  "success": true,
  "output_directory": "./generated",
  "files_generated": [
    "src/index.ts",
    "src/operations/read.ts",
    "LICENSE",
    "NOTICE.md"
  ],
  "provenance": {
    "schema_fingerprint": "sha256:abc123...",
    "generator_version": "1.2.3"
  },
  "warnings": []
}

{
  "success": false,
  "error": {
    "code": 2,
    "type": "SCHEMA_VALIDATION_ERROR",
    "message": "Schema validation failed",
    "details": [
      {
        "path": "endpoints.read[0].params[2].name",
        "code": "SCHEMA_INVALID_NAME",
        "message": "Parameter name 'userName' must be snake_case",
        "suggestion": "Use 'user_name' instead"
      }
    ]
  }
}

mcpaql-generate --schema github-api.yaml --target typescript --output ./adapters/github

mcpaql-generate \
  --schema adapter.yaml \
  --target typescript \
  --output ./generated \
  --config generator.config.json \
  --verbose

mcpaql-generate --schema adapter.yaml --target typescript --dry-run

# Export fixture evidence alongside the adapter using the generator's own tooling
node ./generated-adapter/scripts/export-conformance-evidence.mjs > ./generated-adapter/conformance/reference.json

# Run conformance tests on generated evidence
node scripts/run-conformance-tests.mjs test ./generated-adapter/conformance/reference.json --level 1