mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
## 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>
76 lines
2.3 KiB
76 lines
2.3 KiB