Connectors gives applications and agents a consistent way to discover and use integrations. Independent adapter services expose typed operations through shared, versioned contracts. An application can call an adapter directly or reach several adapters through an optional federation host.
The aim is to make an integration useful on its own and predictable when combined with others. Provider behavior stays with its adapter; shared contracts define what callers can expect from access, results and failures.
flowchart LR
app[Application or agent] --> client[Generic client]
client --> gitlab[GitLab adapter]
client --> host[Optional federation host]
host --> kube[Kubernetes adapter]
host --> sql[SQL adapter]
For example, Kubernetes can report a database endpoint, while the SQL adapter provides bounded reads from an explicitly configured database. Discovering the endpoint supplies information; selecting its connection and granting access are separate steps.
Source release v0.2.0 packages the persistent GitLab CLI and eleven native read operations. The changelog records its scope and remaining work.
The local CLI implements setup, configured adapter management, protected connect/repair, saved-credential revalidation, connection inspection/revoke, cached operation discovery and supervised GitLab and Kubernetes reads. A local owner manages exact child processes; SQLite records metadata and a qualified Secret Service keyring stores credentials. See the GitLab CLI guide, the Kubernetes CLI guide and the runtime binding.
Disposable GitLab HTTPS and keyring fixtures prove saved-credential reuse after CLI, owner and keyring restarts. Explicit revalidation renews the 60-second validation evidence without credential re-entry. A dedicated live GitLab has now answered all eleven reads, the pinned validation, an approved merge and a raced update; see the sandbox evidence.
Ordinary HTTP endpoints no longer need adapter code. The catalog provider loads a bundle compiled from a pinned OpenAPI document — the GitLab bundle carries all 1,847 operations of the pinned source — and exposes a configured selection of them through the same local CLI, approval and audit path. Merge-request create and update have run against the live GitLab through it, with the accepted race boundary declared as a guard.
Kubernetes now has the same local lifecycle binding: a saved bearer token, an identity validated by one SelfSubjectReview probe, and its three reads through the local owner. Disposable TLS cluster and keyring fixtures prove reuse after CLI, owner and keyring restarts. Per-operation SelfSubjectAccessReview permission checks are not implemented and no result claims authorization coverage; dedicated Kubernetes sandbox acceptance remains open.
PostgreSQL now has it too, as the third execution family: it speaks its own wire protocol rather than HTTP, so the session itself is the credential check and the saved identity is the role and database. Its two reads run inside a read-only transaction with fixed statement and lock timeouts. A loopback wire fixture proves the journey; dedicated sandbox acceptance remains open. See the PostgreSQL CLI guide. MCP and the remaining providers follow. The explicit network commands below remain compatible.
This repository contains a working local data/discovery slice and a broader, reviewed specification baseline. The local v0.1.0 milestone is a specification milestone: it stabilizes the selected Kubernetes, GitLab and SQL contracts and models. Its newer auth, governance and persistence semantics still require runtime implementation. See the changelog for that boundary.
The current services provide:
| Adapter | Implemented operations | Binding |
|---|---|---|
| GitLab | project.get, issues.list, file.get, pipelines.list, pipeline.get, pipeline.jobs, job.get, job.trace, merge_request.get, merge_requests.list, merge_request.validate |
GitLab API v4, with a configured project allowlist; exact-commit CI, bounded traces, MR update windows and pinned-head validation observations |
| Kubernetes | resources.list, endpoints.discover, optionally hosts.discover, and optionally the helm_releases.* release reads |
Kubernetes API, with namespace and resource-kind restrictions; saved bearer token through the local CLI. Helm release values and manifests are disclosed only as redacted projections |
| SQL | schema.list, query.read |
PostgreSQL, with read-only transactions and execution deadlines; saved password through the local CLI |
They can run as separate Rust services, with a generic CLI and one-hop federation. This slice does not advertise writes, managed OAuth acquisition, durable events, process execution or media sessions. Other adapters have designs and, in some cases, authored native models; their presence does not mean they can run.
The local CLI is specified under CLI contracts:
setup, adapters, connections and operations, with per-adapter TOML startup
configuration and protected credential entry into local keyring custody. Its ESS
binding and generated parser supply the production management handlers above.
Qualified keyring storage and the
connection registry have disposable runtime
tests. Approval-signing key management supplies
protected key initialization, rotation, recovery, revocation and retirement.
The clock check verifies an explicitly configured time
source under declared source and local timer assumptions.
On current main, local approval commands manage policy,
prepare exact subjects and issue protected proofs for explicitly selected private-protocol-two
write adapters. The development checkout also joins a local-only
guarded GitLab merge through private protocol two,
including approval, audit and same-key result observation. A live GitLab merge
request has been merged through it, and a replayed business key after an owner crash
issued no second merge. The wider write failure matrix remains open. MCP binding and complete multi-provider
acceptance remain implementation work. The executable
also provides describe, invoke and serve.
Build this source release locally; binary/package distribution and deployment are not configured. Historical runtime verification and the specification checkpoint describe what was checked and its limits.
Build from the repository root with Rust 1.88.0 or later:
cargo build --workspace --lockedOrdinary builds use checked-in generated Rust. They do not require ESS or refresh vendor specifications; Cargo may need to download dependencies on the first build.
Choose an adapter configuration from examples, set its permitted resources and private credential references, then follow Run adapter services. For an end-to-end local exercise with disposable Kubernetes and PostgreSQL services, use the live acceptance recipe.
The development guide covers the full gate, pinned generation tools and embedding adapter libraries. GitLab's generation and packaging guide explains how its specification becomes a local service artifact.
- Vision: who this serves, the intended system and how we will judge success.
- Contracts: shared guarantees, versions and support status.
- Adapters: native contracts, provider ownership and extraction boundaries.
- Architecture and design: decisions, rationale and implementation boundaries.
- Documentation website: authored guides, generated contract/model views and executable examples; design and boundaries.
Run the local website with npm ci --allow-git=root and npm start from website/ after its
toolchain setup. The preview is served at
http://127.0.0.1:3100/; public hosting remains deferred. Follow a practical GitLab
request walkthrough or inspect the advanced contract exercises. Both use fictional
Rust/WASM behavior, separately from the adapter runtime; specified user authorization
is labeled separately from configured federation available today.
Agents making repository changes should start with AGENTS.md.