0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/docs/.vale.ini
arctic-char 840d155d20
docs: @mastra/connect — platform integrations guide, quickstart, API + provider reference (#25863)
## Summary

Documentation for `@mastra/connect` and Mastra platform providers,
written against the current API on `main`. Replaces the stale closed PR
#23354 (written pre-`tools()` rename, before `channels()` existed).

### New pages

**Docs (platform sidebar, `Connect` category):**
- `/docs/mastra-platform/connect/overview` — what Connect is and the
getting-started path: connect a provider with the `mastra connect` CLI
(#25865), set the environment, wire `tools()` into a first agent
- `/docs/mastra-platform/connect/connections` — managing connections:
OAuth vs API-key auth, naming, multiple connections per provider,
re-auth, and the security model (server-held credentials, platform
proxy)
- `/docs/mastra-platform/connect/providers` — provider table (22 toolset
providers, 888 tools) with logos, the 9 hosted-MCP providers with links
to each provider's MCP docs, and setup walkthroughs for API-key
providers (Resend, PostHog, …)
- `/docs/mastra-platform/connect/tools` — `tools()` usage: scoping with
`integrations`/`allowTools`/`disallowTools`, per-request filtering with
a dynamic `tools` function and `requestContext`, connection pinning, MCP
providers, opt-in tool approval with `requireApproval` (#25740), and
call-time toolsets
- `/docs/mastra-platform/connect/channels` — `channels()` usage: wiring
into `new Mastra({ channels })`, per-channel credentials
(`slack-channels`, Telegram, Discord), provider options, and varying an
agent's toolset by channel via the `channel` request-context entry

**Reference:**
- `/reference/connect/tools` — `tools()` options tables, resolver
lifecycle (stale-while-revalidate cache,
`invalidate`/`refresh`/`disconnect`), connection resolution order,
`requireApproval` policy, error codes
- `/reference/connect/channels` — `channels()` options, `getRoutes()`,
per-provider overrides, reserved-field rejection
- `/reference/connect/credential` — `credential()` discriminated union
(`oauth2` / `api_key`), error codes
- `/reference/connect/providers` — generated per-tool reference for all
22 toolset providers, regenerated by
`docs/scripts/gen-connect-providers.mjs` (also added here)

Also adds the `ProviderLogo` component (theSVG-sourced marks with
light/dark mono tinting) and cross-links from `/docs/agents/tools` and
`/docs/channels`.

### Release scope

Matches what ships in v1:
- `environment()` is not documented — it isn't being released.
- Anthropic, Microsoft Teams, Stripe, and Twitter/X are excluded from
the provider docs and the generated reference.
- Reflects the `slack` → `slack-channels` split (#25332), the
`connect()` → `tools()` rename, and the `autoApproveTools` →
`requireApproval` approval model (#25740).

### Notes
- `reference/connect/providers.mdx` is generated from the provider tool
sources; rerun `node docs/scripts/gen-connect-providers.mjs .` when
providers are added or synced.

## Test plan
- [x] `pnpm validate` (666 files, sidebars sorted, all docs linked,
`new` tags within window)
- [x] `pnpm lint:remark` and `pnpm lint:prose` (Vale) — 0 errors
- [x] `pnpm format:mdx:check` — clean
- [x] Full production docs build — all pages compile; links and heading
anchors resolve (the only broken-anchor warnings are pre-existing on an
unrelated harness page)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds documentation that explains how to connect provider
accounts to Mastra and use them with agents and chat channels. It also
adds API references and a generated list of supported provider tools.

## Changes

- Added Connect guides for setup, connections, providers, tools, and
channels.
- Added API references for `tools()`, `channels()`, and `credential()`,
plus a generated reference for 22 provider toolsets.
- Added a `ProviderLogo` component and Connect entries in the
documentation sidebars.
- Added Connect links from the channels documentation. The follow-up
commit reverted the link from `/docs/agents/tools`.
- Moved the provider-reference generator to `packages/connect/scripts`
and added it to the package build task.
- Documented the v1 exclusions: `environment()`, Anthropic, Microsoft
Teams, Stripe, and Twitter/X.

## Validation

The author reports that `pnpm validate` passed for 666 files, `pnpm
lint:remark` and `pnpm lint:prose` reported no errors, and `pnpm
format:mdx:check` was clean. The author also reports that the production
docs build compiled all pages and resolved links and heading anchors,
with pre-existing broken-anchor warnings on an unrelated harness page.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: Justin Levine <20596508+jal-co@users.noreply.github.com>
Co-authored-by: Shane Thomas <shane@codekarate.com>
Co-authored-by: LekoArts <lekoarts@gmail.com>
2026-10-07 10:04:43 -04:00

76 lines
2.3 KiB