metorial/metorial

Overview

This repository is Metorial’s integration catalog and the SDK it is written in, not the Metorial platform. It holds 1,149 integration packages under integrations/, plus the Slates stack they target: a typed JSON-RPC protocol (@slates/proto), an authoring SDK (@slates/provider, re-exported as slates), a handler that serves a slate over that protocol (@slates/provider-handler), a client (@slates/client), cross-provider adapters such as chat, and a CLI and test kit. Each integration is a small Bun/TypeScript package that declares auth methods, config, tools and trigger groups with Zod schemas.

What turns a slate into something an agent can call lives elsewhere. Credential storage, the OAuth redirect host, scheduling of polling and token refresh, webhook ingress, MCP exposure and the hosted API all belong to the separate metorial-platform repo and the hosted service. The README’s “Tech Stack” section (Docker MCP containers, a Go engine, MongoDB) describes that wider product. The code here contains no MCP server and no Docker runtime. Integrations are bundled with ncc into single files, and slate.json options such as timeout (capped at 900 s, “the AWS Lambda hard limit”) point to deployment as serverless functions (slate.schema.json).

The code is licensed under FSL-1.1-ALv2: source-available now, converting to Apache 2.0 after two years, with competing commercial use prohibited until then.

Architecture

flowchart LR
  P["Metorial platform (not in repo)"] --> CL["@slates/client"]
  CL --> TR["Transport (local in-process)"]
  TR --> H["provider-handler: JSON-RPC methods"]
  H --> S["Slate: spec + tools + trigger groups"]
  S --> AU["SlateAuth methods (OAuth, token)"]
  S --> TL["SlateTool.handleInvocation"]
  S --> TG["Trigger groups (webhook / polling)"]
  TL --> API["Third-party API (axios)"]
  AD["Adapters, e.g. chat"] --> S
  CLI["slates CLI + test kit"] --> CL

Component	Path	Role
Integrations	integrations/<name>/	1,149 packages: slate.json manifest, src/index.ts exporting provider = Slate.create(...)
Protocol	packages/proto/	Zod schemas for slates/* messages, version string, handler manager
Provider SDK	packages/provider/ (+ packages/slates)	SlateSpecification, SlateAuth, SlateTool, SlateTrigger, trigger groups, errors, axios helpers
Provider handler	packages/provider-handler/	Implements every slates/* request against a Slate: auth, config, actions, triggers
Client	packages/client/	Typed client and createLocalSlateTransport
Adapters	packages/adapter/, adapters/chat/	Cross-provider contracts (the chat adapter: 28 tools, 9 triggers; implemented by Slack)
Shared helpers	packages/oauth-*, *-recipes, slack-tools	Reusable OAuth flows and API recipes for families of integrations
CLI and tests	packages/cli/, packages/test/, test-integrations/	Run tools and triggers locally against profiles; MCP-compatible schema checks

How a request flows

Take a host invoking Slack’s get_team_info tool:

1. Connect. The host creates a transport. In this repo that is createLocalSlateTransport, which builds the provider handler in-process and feeds each JSON-RPC message to SlatesProviderProtoHandlerManager.handleInput (transport.ts).
2. Set context. The host sends notifications: slates/hello (protocol), slates/participant.set, slates/auth.set (the auth output, validated against the spec’s auth schema), slates/config.set and slates/session.start (provider-handler/index.ts). The handler keeps these in local state. It stores nothing.
3. Discover. slates/actions.list maps each action to id, name, description, tags, scopes, auth methods and JSON Schemas converted from Zod (spec.ts).
4. Invoke. slates/action.tool.invoke looks up the tool, validates the input against its Zod schema, and builds a SlateContext with config, input and auth output. Public tools get a SlatePublicContext with no auth (provider-handler/index.ts). Missing session context fails with precondition_failed (L304-L329).
5. Run. handleInvocation runs inside traceProviderCall and runWithContext. Slack’s tool creates a client from ctx.auth.token, calls the API, and returns { output, message } (get-team-info.ts).
6. Return. Attachments from the result and the context are merged, any auth secrets embedded in attachment URLs are redacted, attachments may be routed through direct upload, and HTTP traces are attached (provider-handler/index.ts). Errors are mapped to slate codes such as request.rate_limited or auth.required (provider.ts).

Key components

Slate and tools

Slate.create({ spec, tools, triggers, adapters, triggerGroups }) merges adapter actions into the action list. It rejects duplicate adapters, conflicting action keys, and more than one manual-webhook trigger group (slate.ts). Tools use a builder: SlateTool.create(spec, { name, key, description, tags }).scopes(...).input(zod).output(zod).handleInvocation(fn).build() (tool.ts). readOnly/destructive tags and per-tool OAuth scope requirements are first-class, so a host can filter tools by what a connection was granted.

Auth methods

SlateAuth.create().output(schema) chains several methods. Slack has bot OAuth, user OAuth and token methods. The integration owns the provider-specific parts: building the authorize URL, exchanging the code at /oauth.v2.access, refreshing tokens, and loading a profile (slack auth.ts). The handler exposes these as slates/auth.authorization_url.get, …callback.handle and …token_refresh.handle. The host passes in client id and secret and keeps the result (provider-handler/index.ts). Deciding when to refresh, and where tokens live, is the platform’s job.

Trigger groups

A trigger group is either polling (with intervalSeconds, default and protocol minimum 600 s) or webhook, with automatic or manual registration and a process handler (triggerGroup.ts, proto triggerGroup.ts). process turns a raw request into events, each with routing matchers and an optional idempotency key. The handler then works out which triggers match each event (provider-handler/index.ts). Slack’s events group shows the pattern well: manual setup instructions, a five-minute replay window, and HMAC-SHA256 verification of v0:timestamp:body (eventsTriggerGroup.ts).

Adapters

An adapter is a cross-provider contract. ChatAdapter lists about 65 capability flags. Each flag maps to metorial_chat$… tools or triggers, or to nothing for pure feature flags such as content_tables (adapter.ts). The contract defines 28 tools and 9 triggers. Any chat provider that implements it lets an agent send a message through the same tool shape. At this commit Slack is the only integration that does.

Extending it

• New integration. Copy an existing package under integrations/. Add a slate.json (name in @scope/name form, categories, skills), a spec.ts with config and auth, tools built with SlateTool.create, and export provider = Slate.create(...) from src/index.ts (slack index.ts).
• Reuse. Shared OAuth packages (oauth-google, oauth-microsoft, oauth-zoho) and recipe packages cover provider families.
• Test locally. bun run integrations:cli <integration> … runs tools, auth setup and trigger processing against saved profiles. @slates/test checks that every tool schema stays MCP-compatible.

Running it

• Tooling. Bun 1.4 and Turbo. bun run build:integrations builds the packages, then each integration with ncc.
• Locally. Through the slates CLI or createLocalSlateTransport in your own process. The provider handler needs the host to supply auth output and config. There is no server to start.
• In production. Through Metorial’s hosted platform or the separately published platform repo, which add the credential vault, OAuth setup sessions, MCP endpoints and the agent SDKs (metorial-node, metorial-python) shown in the README.

Strengths and caveats

• Strength: breadth with consistent shape. More than a thousand integrations share one SDK, typed Zod I/O, scopes, read-only/destructive tags and structured error codes.
• Strength: well-designed trigger model. Trigger groups split delivery (webhook or polling) from routing (matchers per trigger), with idempotency keys and real signature checks.
• Strength: stateless providers. A slate keeps no credentials of its own. All state arrives through protocol messages, which keeps the code easy to sandbox and deploy as functions.
• Caveat: not runnable as a product on its own. Token storage, refresh scheduling, webhook ingress and MCP exposure are all outside this repo.
• Caveat: execution is plain in-process code. No retries or rate limiting in the handler. Pagination and backoff are left to each integration’s author.
• Caveat: stale README. Its stack description (Docker MCP containers, Go, MongoDB) does not match this code base and can mislead evaluators.
• Caveat: FSL license. It is source-available for two years per release, not OSI open source.

Sources: code at 54e6a25, verified Q&A.