# agent-connector

Descriptive product route map for agent-connector. Detailed API contracts, host
tables, examples, and generated support claims live in `llms-full.txt`; current
public host coverage lives at https://agent-connector.ai/coverage.

## Product Scope

agent-connector is an SDK and CLI for MCP package authors. The one-line promise is
"deploy one MCP to every agent host" — host meaning any config-owning surface, so
terminal CLIs, IDE extensions and desktop apps alike, not CLIs only. The framing is
"focus on the implementation, not the distribution": the author stays in their MCP
server and never hand-maintains a per-host integration, package format, or install
path.

A connector package declares one MCP server plus optional hooks, commands, skills,
subagents, memory, statusline, actions, telemetry, and per-host overrides. The CLI
renders those surfaces into each supported host's native files, verifies install
health, and can wrap stdio servers for local per-tool token telemetry.

A separate connector-free usage track reads agent host session logs read-only and
reports host-level token totals by platform, project, session, model, or day. It
does not provide per-MCP or per-tool attribution; those numbers come from a
developer-owned connector using the serve telemetry proxy.

## Audience Routes

- MCP developer track: build a branded MCP integration. Package metadata supplies
  public identity; `@ken-jo/agent-connector/sdk` supplies authoring helpers;
  `@ken-jo/agent-connector/cli` exposes lifecycle commands through the package's
  own bin. Framework packaging artifacts are produced by the framework CLI.
- Agent host usage track: inspect local host usage logs without authoring or
  installing a connector. Relevant verbs are `usage report`, `usage export`, and
  `usage leaderboard`.

## Authoring Map

- Package identity: `package.json` is the normal source for package name, MCP
  display name, bin, and version. Explicit connector identity fields are mainly
  for legacy or multi-instance cases.
- MCP launch shapes: package runner, local Node or process server, Python server
  launched with uv, CLI server mode, and remote HTTP server URL are all valid
  families. Pick the shape that matches the product.
- SDK entrypoints: `@ken-jo/agent-connector/sdk` exports `defineConnector`, the
  typed `define*` helpers, host capability introspection helpers, and public
  types. Full field tables are in `llms-full.txt` sections 2 and 9.
- Offline checks: `@ken-jo/agent-connector/sdk/test` exposes `explain`,
  `explainHooks`, and `simulate` for adapter behavior before writing host files.

## CLI Map

- Branded connector package CLI: `detect`, `install`, `uninstall`, `upgrade`,
  `doctor`, `status`, `telemetry`, `leaderboard`.
- Framework CLI: `package` emits distribution artifacts such as host plugin
  bundles and MCP standard manifests. See `llms-full.txt` section 3 for format
  names and requirements.
- Internal host entrypoints: `serve`, `hook`, `statusline`, `action`, and
  `usage-event` are commands that generated host config may reference.
- Marketplace installs: supported where a host has a driver; exact host list and
  driver shape are maintained in `llms-full.txt` and the registry.

## Support And Coverage

- Coverage page: https://agent-connector.ai/coverage is canonical for current
  host support, tier, surface, type, server support, verification level, and star
  index display.
- Full reference: `llms-full.txt` contains supported platform tables by hook
  paradigm, canonical hook events, content surfaces, statusline/action contracts,
  telemetry model, CLI reference, SDK reference, and host caveats.
- Skill route: `skills/agent-connector/SKILL.md` is the small agent-facing router;
  detailed task references are under `skills/agent-connector/references/`.

## Links

- README: `README.md`
- Architecture: `docs/ARCHITECTURE.md`
- Full LLM reference: `llms-full.txt`
- Example connector: `examples/acme-db/agent-connector.config.mjs`