diff --git a/plugins/agent-auth/agents/setup-scalekit.md b/plugins/agent-auth/agents/setup-scalekit.md index 7227f6f..ed43763 100644 --- a/plugins/agent-auth/agents/setup-scalekit.md +++ b/plugins/agent-auth/agents/setup-scalekit.md @@ -18,7 +18,7 @@ Hard rules: - NEVER ask the user to paste SCALEKIT_CLIENT_SECRET into chat. - NEVER hardcode credentials in code samples; always use environment variables. - Prefer creating a local verification script (verify.js / verify.py / verify.go / Verify.java) and running it, but only if the user wants you to write files. -- When using agent auth for nodejs, use npm install @scalekit-sdk/node@2.2.0-beta.1 +- When using agent auth for nodejs, use npm install @scalekit-sdk/node Workflow: 1) Determine language/runtime (Node.js, Python, Go, Java) and where env vars should live (.env, shell, CI secrets). diff --git a/plugins/agent-auth/rules/live-metadata-first.mdc b/plugins/agent-auth/rules/live-metadata-first.mdc new file mode 100644 index 0000000..ac0d247 --- /dev/null +++ b/plugins/agent-auth/rules/live-metadata-first.mdc @@ -0,0 +1,24 @@ +--- +description: Treat live Agent Auth metadata as the source of truth for tool names, connector coverage, and schemas. Static docs are directional guidance, not guaranteed truth. +alwaysApply: true +--- + +# Live Metadata First + +Treat live Agent Auth metadata as the source of truth for: + +- tool names +- connector coverage +- `input_schema` +- `output_schema` + +## Implications + +- Static connector notes are not exhaustive. +- Example code is not a catalog. +- Schema discovery should happen before guessing tool inputs. +- When credentials are available, prefer live lookup over prose documentation. + +## Fallback behavior + +If live credentials are unavailable, docs can still guide setup and workflow design, but they must be presented as directional guidance rather than guaranteed current truth. \ No newline at end of file diff --git a/plugins/agent-auth/rules/terminology.mdc b/plugins/agent-auth/rules/terminology.mdc new file mode 100644 index 0000000..95c6f79 --- /dev/null +++ b/plugins/agent-auth/rules/terminology.mdc @@ -0,0 +1,23 @@ +--- +description: Enforces consistent Agent Auth terminology across skills, code, and docs. Prevents confusing connector, connection, and connected account. +alwaysApply: true +--- + +# Terminology + +Use these terms consistently: + +- **connector**: the integration (e.g., Gmail, Slack, Salesforce) +- **connection**: the environment-level dashboard configuration +- **connected account**: the per-user authorization record +- **tool**: the executable action exposed by a connector + +## Preferred wording + +- Prefer `connector` in explanations to users. +- Use `provider` only when the SDK or API field literally uses that name. +- Do not imply that `connection_name` is always the same as the connector slug. + +## Why this rule exists + +The old language mixed `provider`, `connector`, and `connection_name` too freely. This rule keeps the Agent Auth model stable across skills and docs. \ No newline at end of file diff --git a/plugins/agent-auth/rules/tool-selection.mdc b/plugins/agent-auth/rules/tool-selection.mdc new file mode 100644 index 0000000..8fc0eac --- /dev/null +++ b/plugins/agent-auth/rules/tool-selection.mdc @@ -0,0 +1,27 @@ +--- +description: Keep the tool set as small as possible before handing it to an LLM. Too many tools degrade selection accuracy and parameter filling. +alwaysApply: true +--- + +# Tool Selection + +Keep the tool set as small as possible before handing it to an LLM. + +## Rules + +- Start from the workflow, not the full catalog. +- Discover only the connector or tool family relevant to the task. +- Inspect `input_schema` before execution when required fields are unclear. +- Avoid sending broad connector-wide tool lists to the model unless the task truly needs them. + +## Why this matters + +Too many tools degrade tool selection and parameter filling. Constraining the tool set improves both latency and correctness. + +## Practical pattern + +1. Identify the user goal. +2. Discover a narrow candidate set. +3. Inspect schema. +4. Validate with one live execution if needed. +5. Wire only the proven tools into the agent workflow. \ No newline at end of file diff --git a/plugins/agent-auth/skills/agent-auth/SKILL.md b/plugins/agent-auth/skills/agent-auth/SKILL.md index 05bf999..82f0913 100644 --- a/plugins/agent-auth/skills/agent-auth/SKILL.md +++ b/plugins/agent-auth/skills/agent-auth/SKILL.md @@ -7,6 +7,17 @@ description: Integrates Scalekit Agent Auth into a project to handle OAuth flows Scalekit handles the full OAuth lifecycle — authorization, token storage, and refresh — so agents can act on behalf of users in Gmail, Slack, Notion, Calendar, and other connectors. +## Mental model + +Keep these terms straight: + +- **connector**: the integration (e.g., Gmail, Slack, Salesforce) +- **connection**: the environment-level dashboard configuration +- **connected account**: the per-user authorization record +- **tool**: the executable action exposed by a connector + +Prefer live tool discovery over hand-maintained catalogs. If the user needs the current tool list or schema, use the Scalekit SDK's tool discovery methods. + **Required env vars**: `SCALEKIT_CLIENT_ID`, `SCALEKIT_CLIENT_SECRET`, `SCALEKIT_ENV_URL` → Get from [app.scalekit.com](https://app.scalekit.com): Developers → Settings → API Credentials @@ -39,7 +50,7 @@ actions = scalekit.actions **Node.js** ```bash -npm install @scalekit-sdk/node@2.2.0-beta.1 +npm install @scalekit-sdk/node ``` ```typescript import { ScalekitClient } from '@scalekit-sdk/node'; @@ -223,7 +234,7 @@ for (const msg of messages) { Replace `"gmail"` with any supported connector name: `slack`, `notion`, `calendar`, etc. The SDK workflow (Steps 1–3) is identical for all connectors. Only the downstream API call (Step 4) changes. -For connector-specific API details, see [CONNECTORS.md](CONNECTORS.md). +For connector-specific API details, see [agent-connectors](../references/agent-connectors/README.md). ## Building agents @@ -302,3 +313,8 @@ For an overview of supported providers and their capabilities, see [providers.md For comprehensive token management including refresh, security, and monitoring, see [token-management.md](../references/token-management.md). For configuring your own OAuth credentials per connector (whitelabeling, dedicated quotas), see [byoc.md](../references/byoc.md). + +## When to switch skills + +- Use `building-agent-mcp-server` when the user wants to expose Agent Auth tools over the MCP protocol. +- Use `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist. diff --git a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md b/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md index b8e85b7..b23dab9 100644 --- a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md +++ b/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md @@ -156,3 +156,15 @@ asyncio.run(main()) > **Note — MCP client compatibility:** You can test this MCP server with popular clients like MCP Inspector, Claude Desktop, and other spec-compliant implementations. Note that ChatGPT's beta connector feature may not work properly as it's still in beta and doesn't fully adhere to the MCP specification yet. Full working example: [github.com/scalekit-inc/python-connect-demos/tree/main/mcp](https://github.com/scalekit-inc/python-connect-demos/tree/main/mcp) + +## Deep reference + +- Connected accounts lifecycle and states: [connected-accounts.md](../../references/connected-accounts.md) +- Connection configuration: [connections.md](../../references/connections.md) +- Code samples by framework: [code-samples.md](../../references/code-samples.md) +- Bring your own OAuth credentials: [byoc.md](../../references/byoc.md) + +## When to switch skills + +- Use `agent-auth` when the user wants to integrate Agent Auth directly (SDK, not MCP). +- Use `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist. diff --git a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md b/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md index 152ffd3..7d59e99 100644 --- a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md +++ b/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md @@ -60,3 +60,9 @@ Work through each section in order — earlier sections are blockers for later o - OAuth authorization completion rate (initiated vs completed) - Per-service API error rates (distinguish auth errors from service errors) - Token expiry distribution (are tokens being refreshed proactively?) + +## Deep reference + +- Connected accounts lifecycle and states: [connected-accounts.md](../../references/connected-accounts.md) +- Connection configuration: [connections.md](../../references/connections.md) +- Bring your own OAuth credentials: [byoc.md](../../references/byoc.md) diff --git a/plugins/full-stack-auth/rules/redirect-urls.mdc b/plugins/full-stack-auth/rules/redirect-urls.mdc new file mode 100644 index 0000000..d2252c3 --- /dev/null +++ b/plugins/full-stack-auth/rules/redirect-urls.mdc @@ -0,0 +1,27 @@ +--- +description: Enforces redirect URL rules for all OAuth and OIDC flows. Catches trailing-slash mismatches, scheme errors, and port mismatches before they cause auth failures. +alwaysApply: true +globs: ["**/*.{js,ts,py,go,java}"] +--- + +# Redirect URL Rules + +All OAuth and OIDC flows in Scalekit require registered redirect URLs. + +## Rules + +- The `redirect_uri` parameter in authorization requests must exactly match a URL registered in the Scalekit dashboard. +- Register both development (`http://localhost:*`) and production (`https://`) redirect URLs. +- The `post_logout_redirect_uri` must also be allowlisted in the dashboard under Post Logout URLs. +- Never use wildcard redirect URLs in production. + +## Common mistakes + +- Trailing slash mismatch: `https://app.com/callback` vs `https://app.com/callback/`. +- Scheme mismatch: `http://` registered but `https://` used in code (or vice versa). +- Port mismatch in development: registering `:3000` but the app runs on `:3001`. + +## Where to configure + +Scalekit Dashboard → Settings → Redirect URLs (for auth callbacks) +Scalekit Dashboard → Settings → Post Logout URLs (for logout redirects) \ No newline at end of file diff --git a/plugins/full-stack-auth/rules/terminology.mdc b/plugins/full-stack-auth/rules/terminology.mdc new file mode 100644 index 0000000..e30469c --- /dev/null +++ b/plugins/full-stack-auth/rules/terminology.mdc @@ -0,0 +1,23 @@ +--- +description: Enforces consistent Scalekit product naming across full-stack-auth, modular-sso, modular-scim, and mcp-auth plugins. Prevents mixing old and new terminology. +alwaysApply: true +--- + +# Terminology + +Use these terms consistently: + +- **Full Stack Auth (FSA)**: Scalekit manages the entire auth lifecycle (login, sessions, users). +- **Modular SSO**: enterprise SSO integration where the app manages its own users and sessions. Scalekit handles only the SSO handshake. +- **SCIM provisioning**: directory sync for automatic user and group lifecycle management via webhooks. +- **Admin portal**: customer-facing iframe for self-serve SSO and SCIM configuration. +- **MCP server auth**: OAuth 2.1 authorization for Model Context Protocol servers. + +## Preferred wording + +- Use `Modular SSO` when the app manages its own sessions. Use `Full Stack Auth SSO` when Scalekit manages everything. +- Do not mix Agent Auth terminology (connectors, connected accounts, tools) in auth contexts. Agent Auth is about agent-to-tool authentication. + +## Why this rule exists + +The product surfaces (Full Stack Auth, Modular SSO, SCIM, MCP Auth) overlap but serve different architectures. This rule prevents confusion when the agent switches between plugins. \ No newline at end of file diff --git a/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md b/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md index 389d2f1..7780ead 100644 --- a/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md +++ b/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md @@ -5,6 +5,17 @@ description: Implements Scalekit full-stack authentication (FSA) including sign- # Scalekit Full-Stack Authentication +## Mental model + +Scalekit acts as an OIDC/OAuth 2.0 provider for your application: + +- **Auth URL**: redirects the user to Scalekit's login page (or their IdP for SSO) +- **Callback**: exchanges the authorization code for tokens (ID, access, refresh) +- **Access token**: short-lived, carries roles and permissions +- **Refresh token**: long-lived, used to renew access tokens without re-login + +One integration enables: magic links, social sign-ins, enterprise SSO, workspaces, MCP authentication, SCIM provisioning, and user management. + ## Setup Install the SDK and set credentials in `.env`: @@ -93,3 +104,10 @@ All SDK methods follow the same pattern across languages with minor naming conve ## What this unlocks One integration enables: Magic Link & OTP, social sign-ins, enterprise SSO, workspaces, MCP authentication, SCIM provisioning, and user management. + +## When to switch skills + +- Use `modular-sso` (in the modular-sso plugin) when the app manages its own users and sessions and needs only SSO. +- Use `modular-scim` (in the modular-scim plugin) for SCIM provisioning alongside existing auth. +- Use `mcp-auth` (in the mcp-auth plugin) for OAuth 2.1 authorization on MCP servers. +- Use `production-readiness-scalekit` for a pre-launch checklist. diff --git a/plugins/mcp-auth/skills/add-mcp-auth/SKILL.md b/plugins/mcp-auth/skills/add-mcp-auth/SKILL.md index 7a8d690..23fa3d3 100644 --- a/plugins/mcp-auth/skills/add-mcp-auth/SKILL.md +++ b/plugins/mcp-auth/skills/add-mcp-auth/SKILL.md @@ -39,6 +39,25 @@ Activate when the user asks to: --- +## Critical prerequisites + +- MCP OAuth 2.1 auth only works with **Streamable HTTP transport** — SSE and stdio transports do not support auth. +- Your MCP server must be registered in the Scalekit dashboard before tokens can be validated. +- HTTPS is required in production (HTTP is acceptable for localhost development). + +## Implementation approaches + +| Approach | Framework | Complexity | Best for | +|---|---|---|---| +| FastMCP + Scalekit provider | Python | Low | Simple MCP servers, quick start | +| FastAPI + FastMCP | Python | Medium | Apps needing advanced authorization and existing FastAPI routes | +| Express.js + custom middleware | Node.js | Medium | Node.js apps, fine-grained token control | + +Each approach has a dedicated skill with full walkthroughs: +- `mcp-auth-fastmcp-scalekit` — FastMCP + Scalekit provider +- `mcp-auth-fastapi-fastmcp-scalekit` — FastAPI + FastMCP +- `mcp-auth-expressjs-scalekit` — Express.js with custom middleware + ## Procedure ### 1) Scalekit dashboard setup (resource server registration) @@ -121,3 +140,9 @@ See `references/SECURITY.md`. Minimum: - Deep technical notes: `references/REFERENCE.md` - Scope design patterns: `references/SCOPES.md` - Production hardening: `references/SECURITY.md` + +## When to switch skills + +- Use `full-stack-auth` (in the full-stack-auth plugin) for browser-based authentication flows. +- Use `production-readiness-scalekit` for a pre-launch MCP auth checklist. +- Use a framework-specific sub-skill (`mcp-auth-fastmcp-scalekit`, `mcp-auth-expressjs-scalekit`, `mcp-auth-fastapi-fastmcp-scalekit`) for a guided implementation in your stack. diff --git a/plugins/modular-scim/skills/modular-scim/SKILL.md b/plugins/modular-scim/skills/modular-scim/SKILL.md index 00446e7..448c7f9 100644 --- a/plugins/modular-scim/skills/modular-scim/SKILL.md +++ b/plugins/modular-scim/skills/modular-scim/SKILL.md @@ -228,3 +228,9 @@ After deploying the webhook endpoint: - Full Go/Java SDK examples → [REFERENCE.md](REFERENCE.md) - Webhook event payload schemas → [EVENTS.md](EVENTS.md) - RBAC group-to-role mapping patterns → [RBAC.md](RBAC.md) + +## When to switch skills + +- Use `full-stack-auth` (in the full-stack-auth plugin) when building login/signup flows, not just provisioning. +- Use `modular-sso` (in the modular-sso plugin) for enterprise SSO alongside SCIM. +- Use `production-readiness-scalekit` for a pre-launch provisioning checklist. diff --git a/plugins/modular-sso/skills/modular-sso/SKILL.md b/plugins/modular-sso/skills/modular-sso/SKILL.md index 15aa426..75de278 100644 --- a/plugins/modular-sso/skills/modular-sso/SKILL.md +++ b/plugins/modular-sso/skills/modular-sso/SKILL.md @@ -404,7 +404,7 @@ Prevent failed redirects by checking SSO configuration before redirecting: **Node.js:** ```javascript -const domain = email.split('@').toLowerCase(); [reddit](https://www.reddit.com/r/ClaudeAI/comments/1qb1024/ultimate_claude_skillmd_autobuilds_any_fullstack/) +const domain = email.split('@').pop().toLowerCase(); const connections = await scalekit.connections.listConnectionsByDomain({ domain @@ -571,4 +571,9 @@ app.post('/logout', (req, res) => { **Use progressive enhancement**: Start with basic SSO, add advanced features iteratively **Monitor authentication flows**: Track success rates and common failure points -``` \ No newline at end of file + +## When to switch skills + +- Use `full-stack-auth` (in the full-stack-auth plugin) when Scalekit should manage the full auth lifecycle (login, sessions, users). +- Use `modular-scim` (in the modular-scim plugin) for SCIM provisioning alongside SSO. +- Use `production-readiness-scalekit` for a pre-launch SSO checklist. \ No newline at end of file