spec: Define adapter onboarding pipeline — end-to-end workflow for new API targets

[mickdarling]

Summary

Define a standardized, repeatable pipeline for onboarding new API targets into the MCPAQL ecosystem. The current tooling (interrogator, schema builder, generator) handles the mechanical steps, but there is no higher-level workflow that manages the full lifecycle from "we want to support API X" through to "the adapter is published, tested, and maintained."

As the adapter ecosystem scales, this pipeline becomes critical infrastructure — not a nice-to-have.

Problem

Today, creating a new adapter requires ad-hoc orchestration:

1. Identify the target API and its transport/protocol characteristics
2. Determine whether existing tooling supports it (HTTP? Native? New protocol?)
3. Run the interrogator (if applicable) or hand-author the discovery bundle
4. Review and override CRUDE classifications
5. Build the adapter schema
6. Generate the adapter package
7. Run conformance tests
8. Test against the live API
9. Review security implications (danger levels, confirmation requirements)
10. Document the adapter
11. Publish / submit to collection

Each step is manual. There's no tracking, no standard checklist, no way to parallelize across multiple adapters, and no feedback loop from production usage back to the adapter definition.

Proposal: Adapter Onboarding Pipeline

Pipeline Stages

┌─────────────────────────────────────────────────────────────┐
│  Stage 0: TRIAGE                                            │
│  • Identify target API / application / protocol             │
│  • Classify: HTTP REST, GraphQL, gRPC, native-*, other      │
│  • Determine transport plugin requirements                  │
│  • Estimate scope (operation count, auth complexity)         │
│  • Decision: proceed / defer / reject                       │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 1: DISCOVERY                                         │
│  • Run interrogator (MCP servers, sdef, OpenAPI, etc.)      │
│  • OR hand-author discovery bundle from docs/SDK            │
│  • Capture raw API surface                                  │
│  • Produce discovery bundle                                 │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 2: CLASSIFICATION                                    │
│  • Review CRUDE endpoint assignments                        │
│  • Assign danger levels                                     │
│  • Identify confirmation requirements                       │
│  • Flag ambiguous operations for human review                │
│  • Produce overrides file                                   │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 3: GENERATION                                        │
│  • Build adapter schema from discovery bundle + overrides   │
│  • Generate adapter package (server code, types, config)    │
│  • Generate tool names per naming convention (#235)         │
│  • Set annotations (title, hints)                           │
│  • Produce licensing artifacts                              │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 4: VALIDATION                                        │
│  • Run conformance tests                                    │
│  • Run differential validator (source vs adapter)           │
│  • Test against live API (smoke tests)                      │
│  • Security review (injection vectors, auth handling)       │
│  • Performance benchmarks (latency, token usage)            │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 5: PUBLICATION                                       │
│  • Documentation (README, usage examples, limitations)      │
│  • Submit to collection / npm / registry                    │
│  • Announce availability                                    │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 6: MAINTENANCE                                       │
│  • Monitor upstream API changes                             │
│  • Re-interrogate periodically                              │
│  • Differential analysis (what changed since last capture)  │
│  • Version bump adapter schema                              │
│  • Regression testing                                       │
└─────────────────────────────────────────────────────────────┘

Pipeline Tooling

Stage	Existing Tool	Gap
Triage	None	Need triage checklist / intake form
Discovery	mcpaql-interrogate (MCP), sdef parser	Need OpenAPI/Swagger ingestion, GraphQL introspection
Classification	Schema builder with overrides	Need classification review UI or structured review workflow
Generation	mcpaql-generate-adapter	Need naming convention support (#235), annotation generation
Validation	mcpaql-conformance, mcpaql-diff	Need live API smoke test harness, security scanner
Publication	Manual	Need automated submission to collection, npm publish workflow
Maintenance	mcpaql-diff	Need scheduled re-interrogation, change detection, alerting

Discovery Source Expansion

The interrogator currently supports:

• MCP servers (Streamable HTTP) ✅
• macOS scripting dictionaries (.sdef) ✅ (PR in flight)

Future discovery sources needed:

• OpenAPI / Swagger — parse spec files, map paths to CRUDE operations
• GraphQL introspection — query schema, map queries/mutations to CRUDE
• gRPC reflection — service discovery, map RPCs to CRUDE
• SDK analysis — parse TypeScript/Python SDK types to infer operations
• Documentation scraping — extract API surface from docs when no machine-readable spec exists

Each source type needs its own interrogation module that produces the same discovery-bundle.json output.

Automation Opportunities

• Batch onboarding: Given a list of target APIs, run stages 0-3 in parallel, queue stage 4 for human review
• CI/CD for adapters: Re-interrogate + diff + regenerate on schedule, auto-PR if changes detected
• DollhouseMCP agent: The applescript-adapter-engineer agent pattern generalizes — a pipeline orchestrator agent that drives the full workflow
• Collection integration: Auto-submit generated adapters to the DollhouseMCP collection for community review

Acceptance Criteria

• Pipeline stages defined with clear inputs/outputs per stage
• Triage checklist / intake form specified
• Discovery source expansion roadmap documented
• Validation stage requirements specified (conformance, security, smoke tests)
• Maintenance / re-interrogation workflow specified
• Automation strategy documented
• Interaction with naming convention (spec: Define adapter-scoped tool naming convention and annotation requirements #235) and annotation requirements defined

Dependencies

• spec: Define adapter-scoped tool naming convention and annotation requirements #235 — Adapter-scoped tool naming convention
• spec: Define native-applescript transport plugin specification #227-233 — native-applescript transport (first non-HTTP pipeline instance)

References

• Interrogator: @mcpaql/tools (src/interrogate.ts)
• Schema Builder: @mcpaql/adapter-generator (src/schema-builder.ts)
• Generator: @mcpaql/adapter-generator (src/generator.ts)
• Conformance: @mcpaql/tools (src/conformance.ts)
• Differential: @mcpaql/tools (src/differential.ts)
• Discovery Bundle: docs/adapter/discovery-bundle.md

[mickdarling]

Pipeline Walkthrough: Apple Mail — First End-to-End Run (2026-04-04)

Successfully ran the full adapter onboarding pipeline for Apple Mail, the first native-applescript adapter. Documenting the steps, commands, outputs, and observations for future reference.

Stage 1: Discovery (Interrogation)

Command:

cd ~/Developer/Organizations/MCPAQL/tools
npx tsx src/sdef-cli.ts --app Mail --out /tmp/apple-mail-pipeline

Output:

• discovery-bundle.json — 304 operations from 4 suites
• warnings.json — 22 classification warnings
• sdef-parsed.json — raw parsed sdef structure
• capture-metadata.json — source metadata

Observations:

• sdef auto-located at /System/Applications/Mail.app/Contents/Resources/Mail.sdef
• 304 operations is a large surface — real adapters will need aggressive overrides to pare this down to useful operations
• maps_to format produced: native-applescript:{type}:{target} (e.g., native-applescript:get_property:message.subject)

Stage 2: Classification (Schema Build)

Command:

cd ~/Developer/Organizations/MCPAQL/adapter-generator
npx tsx src/schema-cli.ts --input /tmp/apple-mail-pipeline/discovery-bundle.json --out /tmp/apple-mail-pipeline

Output:

• adapter-schema.json — full CRUDE-classified schema (180 read, 111 update, 4 create, 1 delete, 8 execute)
• adapter-provenance.json — generation metadata
• schema-build-report.json — warnings + operation details

Observations:

• The schema builder correctly detected native-applescript transport from source metadata
• No overrides file was used — a production adapter would need one to rename operations, adjust danger levels, and prune the surface
• The read/update split is heavily weighted toward property get/set operations

Stage 3: Generation

Command:

npx tsx src/generate-cli.ts --input /tmp/apple-mail-pipeline/adapter-schema.json \
  --provenance /tmp/apple-mail-pipeline/adapter-provenance.json \
  --out /tmp/apple-mail-pipeline/server

Output: Complete MCP server package:

• src/server.ts — 14KB, native-applescript server with JXA execution, sanitization, introspection
• src/schema.json — 231KB adapter schema
• src/provenance.json — generation metadata
• package.json, tsconfig.json, README.md

Observations:

• Generator correctly produced native-applescript server (osascript/JXA path, not HTTP proxy)
• Server includes validateParamKey, validateJxaIdentifier, sanitizeForJxa security validators
• Package name auto-derived as @mcpaql/generated-Mail Terminology-adapter — needs override for cleaner naming

Stage 4: Validation (Smoke Test)

Commands:

cd /tmp/apple-mail-pipeline/server
npm install
echo '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | npx tsx src/server.ts

Result: Server responds with {"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"Mail Terminology-adapter","version":"0.1.0"}}

Pipeline Gaps Identified

1. No overrides workflow — The 304-operation surface is too large for practical use. Need a guided overrides authoring step between stages 1 and 2.
2. Package naming — Generator derives name from schema, which comes from sdef application name ("Mail Terminology"). Needs a clean name override.
3. No conformance test — Stage 4 was a manual smoke test. mcpaql-conformance should have a native-applescript profile.
4. No live operation test — Verified server starts, didn't test actual Mail operations through the generated server.
5. No publication step — The generated package sits in /tmp. Need a workflow for moving it to examples or npm.

Time & Cost

• Total pipeline execution: ~10 seconds (interrogation + schema build + generation + npm install)
• No LLM cost for pipeline execution itself — all deterministic tooling
• The reviews/fixes during development were the expensive part (~$15-20 in Claude review runs)

[mickdarling]

Updated Pipeline Stages (reflecting Apple Mail learnings, 2026-04-04)

The original pipeline had 6 stages. Based on the Apple Mail end-to-end run, the pipeline now has 8 stages with two critical additions:

Stage 1:   DISCOVERY          — Interrogate sdef/API → discovery bundle (304 ops)
Stage 2:   CLASSIFICATION     — Schema build → CRUDE-classified schema
Stage 2.5: OPERATION DESIGN   — NEW: Composite operation surface design (304 → 26)
Stage 3:   TEMPLATE RESEARCH  — NEW: JXA/API pattern profiling + template authoring
Stage 4:   GENERATION         — Generate server package with templates + curation
Stage 5:   VALIDATION         — Smoke test, live CRUD, conformance
Stage 6:   DEPLOYMENT         — Install to ~/.mcpaql/adapters/, register as MCP server
Stage 7:   PUBLICATION        — Submit to collection / npm / registry
Stage 8:   MAINTENANCE        — Re-interrogate, diff, version bump

Stage 2.5: Operation Design (NEW)

Input: Raw discovery bundle (304 atomic operations)
Output: Curated operation list (26 composite operations) + curation.json

Process:

1. Parse sdef → extract commands, key classes, properties, elements
2. Identify domain objects (message, account, mailbox — not rich_text, paragraph)
3. Design composite operations that bundle atomic properties into useful calls
4. Map each to a CRUDE endpoint
5. Write curation.json (include list + exclude patterns)

This stage reduces 304 raw operations to ~26 useful ones. Without it, the adapter is a noisy surface of atomic property reads that no LLM can navigate effectively.

Stage 3: Template Research (NEW)

Input: Curated operation list + target application
Output: templates.json with tested JXA scripts + performance metadata

Process:

1. For each operation, research the correct JXA execution pattern
2. Test candidate patterns (batch, filter, iterator) at multiple scales
3. Eliminate non-viable patterns with documented reasoning
4. Author the winning template with sanitized parameter interpolation
5. Validate each template against the live application
6. Record performance characteristics and known limitations

Critical finding: Different access patterns have wildly different performance:

• Index iteration: works at any scale
• Batch property reads: timeout at 1600+ messages
• whose filters: timeout at any scale
• Full enumeration: timeout at 1600+ messages

Without this stage, the generated server is a correct-looking shell that doesn't actually work.

Updated Pipeline Duration Estimate

Stage	Time	Automation Potential
Discovery	~10 seconds	Fully automated
Classification	~10 seconds	Fully automated
Operation Design	~30 minutes	Partially automatable (sdef parsing + heuristics)
Template Research	~2-4 hours	Partially automatable (profiling), templates need human/LLM
Generation	~10 seconds	Fully automated
Validation	~15 minutes	Partially automatable
Deployment	~2 minutes	Fully automated

Total: ~3-5 hours for a new application adapter, with the bulk in operation design and template research.