connectors

Willow's unified connector catalog. Every connector — built-in API connectors and remote MCP servers alike — is described by one schema and published two ways:

• npm: @mcp-s/connectors (public), bundled into db-service as the offline fallback.
• CDN: https://connectors.withwillow.ai, which db-service polls every 60s, so a merged change is live without a deploy.

The repo is private; everything it publishes is public, so connectors must never contain secrets.

Structure

src/schema/          # zod 4 schema; all types are inferred from it
src/connectors/api/  # Willow-authored tools against a vendor API: <provider>/<provider>.connector.ts (+ .tools.ts)
src/connectors/mcp/  # proxied MCP servers, tools discovered from the server: <provider>/<provider>.connector.ts
src/connectors/index.ts  # the list of published connectors
scripts/build.ts     # validates every connector and writes dist/public
test/                # schema validation + 1:1 parity with db-service's built-ins

Published files

https://connectors.withwillow.ai/index.json              # every connector, light rows + content hash
https://connectors.withwillow.ai/connectors/{id}.json    # one full definition

The same files ship in the npm package under dist/public, readable with readBundledIndex() / readBundledConnector(id).

Adding or changing a connector

1. Add src/connectors/<kind>/<provider>/<provider>.connector.ts exporting a CatalogConnector (and .tools.ts if it has them), where <kind> is api or mcp. <provider> is the product (notion), not the id (notion-official).
2. Register it in src/connectors/index.ts.
3. npm test && npm run build.
4. Open a PR. Once merged, it reaches every org on the unified-connectors beta within about a minute.

Rules the build enforces:

• No secrets. Instant OAuth (webrix-oauth) declares scopes only; client ids and secrets live in each deployment's instant_connectors table.
• Unique id. It is load-bearing: integrations resolve through it, and a catalog connector replaces a built-in with the same id, so never rename one that is in use. See Slugs.
• Exactly one of definition.api and definition.mcp. That choice is the connector's kind; there is no separate field for it.
• Folder matches kind. A connector with definition.api lives under api/, one with definition.mcp under mcp/, and every connector on disk is registered in index.ts. Who publishes an MCP server is the official label, not a folder. Moving a connector never changes its id.

Slugs

The folder is the provider. The id is the slug, and it can differ from the folder: api/notion/notion.connector.ts is notion, and mcp/notion/notion.connector.ts is notion-official.

The bare slug is reserved for the Willow API connector, even before that API exists. An MCP slug names where the server comes from. A second connector of the same kind gets its own folder (api/jira-server/). The display name stays the product name, so the setup page still groups them onto one card. The logo is the product's icon (display.icon), not the slug.

| Connector | Display name | Slug | | -------------------------------------------- | ------------ | -------------------- | | GitHub API | GitHub | github | | Shapes' MCP server, no API yet | Shapes | shapes-official | | Jira API | Jira | jira | | Jira Server, a second API | Jira Server | jira-server | | Atlassian's MCP server (Jira and Confluence) | Atlassian | atlassian-official |

Release flow

On every push to main:

• GitHub Actions (publish.yml) tests, builds and publishes @mcp-s/[email protected].<timestamp> to npm. db-service depends on "*".
• Cloudflare Workers Builds runs npm ci && npm run build and npx wrangler deploy, serving dist/public on connectors.withwillow.ai.

Pull requests run ci.yml: typecheck, tests, build.

Parity fixtures

github and gmail are 1:1 ports of db-service's built-ins. The fixtures in test/fixtures were snapshotted from db-service; to regenerate them:

cd ../db-service && npx tsx ../connectors/scripts/generate-parity-fixtures.ts