Universal Adapter Runtime Specification

// Pseudocode
function loadAdapter(filePath: string): AdapterSchema {
  const content = readFile(filePath);
  const { frontMatter, body } = parseFrontMatter(content);
  const schema = parseYaml(frontMatter);
  return { ...schema, documentation: body };
}

---
name: github-api
type: adapter
version: "1.0.0"
# ... rest of schema
---

# Documentation body (optional)

interface OperationIndex {
  // Maps operation name to definition and CRUDE category
  [operationName: string]: {
    definition: OperationDefinition;
    endpoint: 'create' | 'read' | 'update' | 'delete' | 'execute';
  };
}

function buildOperationIndex(schema: AdapterSchema): OperationIndex {
  const index: OperationIndex = {};

  for (const endpoint of ['create', 'read', 'update', 'delete', 'execute']) {
    const operations = schema.operations[endpoint] || [];
    for (const op of operations) {
      if (index[op.name]) {
        throw new Error(`Duplicate operation name: ${op.name}`);
      }
      index[op.name] = { definition: op, endpoint };
    }
  }

  return index;
}

interface ValidationError {
  path: string;      // JSON path to invalid field (e.g., "operations.read[0].params.owner")
  message: string;   // Human-readable error description
  expected?: string; // What was expected
  received?: string; // What was received
}

{
  "path": "operations.read[0].name",
  "message": "Operation name is required",
  "expected": "non-empty string",
  "received": "undefined"
}

interface OperationRequest {
  operation: string;
  params?: Record<string, unknown>;
}

async function dispatch(
  request: OperationRequest,
  adapter: LoadedAdapter
): Promise<OperationResult> {
  // 1. Find operation
  const entry = adapter.operationIndex[request.operation];
  if (!entry) {
    return {
      success: false,
      error: `Unknown operation: ${request.operation}`
    };
  }

  // 2. Validate params
  const validationResult = validateParams(request.params || {}, entry.definition);
  if (!validationResult.valid) {
    return {
      success: false,
      error: validationResult.error
    };
  }

  // 3. Apply defaults
  const params = applyDefaults(request.params || {}, entry.definition);

  // 4. Execute via plugin pipeline
  try {
    const response = await executePipeline(entry.definition, params, adapter);
    return response;
  } catch (error) {
    return mapError(error, adapter);
  }
}

function validateEndpoint(operation: string, calledEndpoint: string, index: OperationIndex): void {
  const entry = index[operation];
  if (!entry) return; // Will fail at dispatch

  if (entry.endpoint.toLowerCase() !== calledEndpoint.toLowerCase()) {
    throw new Error(
      `Operation '${operation}' must be called via mcp_aql_${entry.endpoint}, not mcp_aql_${calledEndpoint}`
    );
  }
}

function substitutePath(template: string, params: Record<string, unknown>): string {
  return template.replace(/\{(\w+)\}/g, (match, name) => {
    const value = params[name];
    if (value === undefined) {
      throw new Error(`Missing required path parameter: ${name}`);
    }
    return encodeURIComponent(String(value));
  });
}

function safeEncode(value: string): string {
  // Check if value appears to be already encoded
  try {
    const decoded = decodeURIComponent(value);
    // If decoding succeeds and differs from input, it was encoded
    if (decoded !== value) {
      return value; // Already encoded, preserve as-is
    }
  } catch {
    // decodeURIComponent throws on invalid sequences
    // Value is not properly encoded, so encode it
  }
  return encodeURIComponent(value);
}

// Input: { ids: [1, 2, 3] }
// Template: "/items/{ids}"
// Result: "/items/1%2C2%2C3"

function stringifyValue(value: unknown): string {
  if (Array.isArray(value)) {
    return value.map(String).join(',');
  }
  return String(value);
}

function parseMapping(mapsTo: string): { method: string; path: string } {
  const [method, ...pathParts] = mapsTo.split(' ');
  return {
    method: method.toUpperCase(),
    path: pathParts.join(' ')
  };
}

function buildUrl(adapter: AdapterSchema, path: string, queryParams: Record<string, unknown>): string {
  const url = new URL(path, adapter.target.base_url);

  for (const [key, value] of Object.entries(queryParams)) {
    if (value !== undefined) {
      url.searchParams.append(key, String(value));
    }
  }

  return url.toString();
}

interface SuccessResult {
  success: true;
  data: unknown; // Deserialized response body
}

interface ErrorResult {
  success: false;
  error: string; // Human-readable error message
}

function parseResponse(httpResponse: TransportResponse): OperationResult {
  let body: unknown;

  try {
    body = JSON.parse(httpResponse.body);
  } catch (parseError) {
    // Handle malformed JSON responses (e.g., HTML error pages, truncated responses)
    return handleMalformedResponse(httpResponse, parseError);
  }

  if (httpResponse.status >= 200 && httpResponse.status < 300) {
    return { success: true, data: body };
  }

  // Extract error message from response
  const message = extractErrorMessage(body, httpResponse);
  return { success: false, error: message };
}

function extractErrorMessage(body: unknown, response: TransportResponse): string {
  // Try common error response formats
  if (typeof body === 'object' && body !== null) {
    if ('message' in body) return String(body.message);
    if ('error' in body) {
      if (typeof body.error === 'string') return body.error;
      if (typeof body.error === 'object' && 'message' in body.error) {
        return String(body.error.message);
      }
    }
    if ('errors' in body && Array.isArray(body.errors)) {
      return body.errors.map(e => e.message || String(e)).join('; ');
    }
  }

  // Fallback to status text
  return `${response.status} ${response.statusText}`;
}

function handleMalformedResponse(
  response: TransportResponse,
  parseError: Error
): OperationResult {
  // Check Content-Type to provide better error messages
  const contentType = response.headers['content-type'] || '';

  if (contentType.includes('text/html')) {
    // Likely an error page (nginx 502, Apache error, etc.)
    return {
      success: false,
      error: {
        code: 'SERIALIZATION_PARSE_ERROR',
        message: `Server returned HTML instead of JSON (HTTP ${response.status})`,
        details: {
          content_type: contentType,
          body_preview: response.body.substring(0, 200)
        }
      }
    };
  }

  // Generic JSON parse failure
  return {
    success: false,
    error: {
      code: 'SERIALIZATION_PARSE_ERROR',
      message: `Failed to parse response as JSON: ${parseError.message}`,
      details: {
        content_type: contentType,
        body_preview: response.body.substring(0, 200)
      }
    }
  };
}

function mapHttpError(status: number, body: unknown): string {
  const bodyMessage = extractErrorMessage(body, { status, statusText: '' });

  switch (status) {
    case 400:
      return `Invalid request: ${bodyMessage}`;
    case 401:
      return `Authentication required: ${bodyMessage}`;
    case 403:
      return `Permission denied: ${bodyMessage}`;
    case 404:
      return `Not found: ${bodyMessage}`;
    case 409:
      return `Conflict: ${bodyMessage}`;
    case 422:
      return `Validation failed: ${bodyMessage}`;
    case 429:
      return `Rate limit exceeded: ${bodyMessage}`;
    case 500:
      return `Server error: ${bodyMessage}`;
    case 502:
      return `Bad gateway: ${bodyMessage}`;
    case 503:
      return `Service unavailable: ${bodyMessage}`;
    case 504:
      return `Gateway timeout: ${bodyMessage}`;
    default:
      return `HTTP ${status}: ${bodyMessage}`;
  }
}

function handleIntrospect(params: { query: string; name?: string }, adapter: LoadedAdapter): OperationResult {
  if (params.query === 'operations') {
    return introspectOperations(params.name, adapter);
  }
  if (params.query === 'types') {
    return introspectTypes(params.name, adapter);
  }
  return { success: false, error: `Unknown introspection query: ${params.query}` };
}

{
  "operation": "introspect",
  "params": { "query": "operations" }
}

{
  "success": true,
  "data": {
    "operations": [
      { "name": "get_repo", "endpoint": "read", "description": "Get repository details" },
      { "name": "create_repo", "endpoint": "create", "description": "Create a repository" }
    ]
  }
}

{
  "operation": "introspect",
  "params": { "query": "operations", "name": "get_repo" }
}

{
  "success": true,
  "data": {
    "operation": {
      "name": "get_repo",
      "endpoint": "read",
      "description": "Get repository details",
      "params": [
        { "name": "owner", "type": "string", "required": true, "description": "Repository owner" },
        { "name": "repo", "type": "string", "required": true, "description": "Repository name" }
      ]
    }
  }
}

trust:
  level: generated  # generated | community | verified | official

rate_limits:
  quotas:
    limits:
      - metric: calls_per_hour
        warn: 4000
        hard_stop: 5000

operations:
  read:
    - name: list_repos
      pagination:
        style: link_header

// Malicious input attempt:
params: { filename: "../../../etc/passwd" }

// After encoding:
path: "/files/..%2F..%2F..%2Fetc%2Fpasswd"  // Slashes are encoded, path traversal blocked

// BAD: Exposes credential in error
throw new Error(`Auth failed with token: ${token}`);

// GOOD: Redacts credential
throw new Error(`Auth failed with token: ${token.substring(0, 4)}...`);

function sanitizeError(error: Error, isDevelopment: boolean): string {
  if (isDevelopment) {
    return error.message; // Full details in development
  }

  // Production: generic message with error code only
  return `Operation failed: ${error.code || 'INTERNAL_ERROR'}`;
}

const MAX_RESPONSE_SIZE = 10 * 1024 * 1024; // 10 MB default

if (response.body.length > MAX_RESPONSE_SIZE) {
  throw new Error('Response exceeds maximum size limit');
}