@webiny/mcp 0.0.0-unstable.6844005670

package/skills/local-development/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: webiny-local-development
+context: webiny-extensions
+description: >
+  Deploying, developing locally, managing environments, and debugging Webiny projects.
+  Use this skill when the developer asks about deployment commands (deploy, destroy, info),
+  local development with watch mode (API or Admin), the Local Lambda Development system,
+  environment management (long-lived vs short-lived, production vs dev modes), build parameters,
+  state files, debugging API/Admin/Infrastructure errors, or the redeploy-after-watch requirement.
+---
+
+# Local Development and Deployment
+
+## TL;DR
+
+Webiny is a serverless platform on AWS. Deploy with `yarn webiny deploy`, develop locally with `yarn webiny watch` (API uses Local Lambda Development, Admin runs a local React dev server). Projects support multiple environments (long-lived and short-lived). Always redeploy after stopping watch mode.
+
+## Deployment
+
+### Initial Deployment
+
+Deploy all three applications (Core, API, Admin) at once:
+
+```bash
+yarn webiny deploy
+```
+
+This deploys to the `dev` environment by default. First deployment takes 5-15 minutes.
+
+### Deploying Individual Applications
+
+```bash
+yarn webiny deploy core        # Infrastructure only
+yarn webiny deploy api         # Backend API only
+yarn webiny deploy admin       # Admin frontend only
+```
+
+### Deploy to a Specific Environment
+
+```bash
+yarn webiny deploy --env prod
+yarn webiny deploy api --env staging
+```
+
+### Get Deployment Info
+
+```bash
+yarn webiny info              # Shows all URLs (Admin, API, CloudFront)
+yarn webiny info --env prod   # Info for a specific environment
+```
+
+## Local Development
+
+Before developing locally, you must deploy Core and API first:
+
+```bash
+yarn webiny deploy core api
+```
+
+### Admin Development
+
+```bash
+yarn webiny watch admin
+```
+
+- Starts a local dev server at `http://localhost:3001`
+- Hot module replacement for instant feedback
+- Standard React development experience
+- Use for: custom Admin UI extensions, white-label branding, custom views
+
+### API Development (Local Lambda Development)
+
+```bash
+yarn webiny watch api
+```
+
+How it works:
+1. **Lambda stubs deployed** -- real Lambda functions are replaced with stubs that forward events
+2. **Events forwarded** -- requests to AWS get forwarded to your local machine
+3. **Local execution** -- your code runs locally with full AWS Lambda environment
+4. **Response routing** -- responses sent back through the Lambda stub
+
+Benefits:
+- See backend code changes instantly (no redeployment)
+- Debug locally with standard Node.js tools
+- Console logs appear directly in your terminal
+
+**IMPORTANT: Redeploy After Watch**
+
+When you stop `yarn webiny watch api`, your Lambda functions still contain stub code. You **must** redeploy:
+
+```bash
+yarn webiny deploy api
+```
+
+The watch command prints a reminder when you stop it.
+
+### Running Both
+
+You can run both watch commands simultaneously in separate terminals:
+
+```bash
+# Terminal 1
+yarn webiny watch api
+
+# Terminal 2
+yarn webiny watch admin
+```
+
+## Environments
+
+### Long-Lived Environments
+
+Persistent environments maintained over time:
+- **dev** -- daily development
+- **staging** -- pre-production testing
+- **prod** -- production
+
+Best practice: manage via CI/CD pipelines.
+
+### Short-Lived Environments
+
+Temporary environments for specific purposes:
+- Feature branch testing
+- PR previews
+- Experimentation
+
+```bash
+# Create a short-lived environment
+yarn webiny deploy --env feature-123
+
+# Destroy when done
+yarn webiny destroy --env feature-123
+```
+
+### Deployment Modes
+
+Webiny has two deployment templates:
+- **dev** -- smaller, cheaper infrastructure for development
+- **prod** -- production-grade infrastructure with HA, backups, auto-scaling
+
+The mode is determined by whether the environment name is in the `ProductionEnvironments` list:
+
+```tsx
+// webiny.config.tsx
+<Infra.ProductionEnvironments environments={["prod", "staging"]} />
+```
+
+## State Files
+
+State files are JSON files that track the current state of your deployment:
+- Store infrastructure resource info, configurations, and metadata
+- Essential for managing environments and tracking changes
+- Stored in S3 by default
+
+## Build Parameters
+
+Pass custom config values from `webiny.config.tsx` to your extensions:
+
+```tsx
+// webiny.config.tsx
+<Api.BuildParam paramName="MY_PARAM" value="customValue" />
+<Api.BuildParam paramName="MY_CONFIG" value={{ myKey: 2, nested: { foo: "bar" } }} />
+<Admin.BuildParam paramName="ADMIN_PARAM" value="adminValue" />
+```
+
+Access in API extensions:
+
+```typescript
+import { BuildParams } from "webiny/api/build-params";
+
+class MyExtension implements SomeFactory.Interface {
+    constructor(private buildParams: BuildParams.Interface) {}
+
+    execute() {
+        const value = this.buildParams.get<string>("MY_PARAM");
+        const config = this.buildParams.get<{ myKey: number }>("MY_CONFIG");
+    }
+}
+```
+
+## Debugging
+
+### API Errors
+
+During `yarn webiny watch api`:
+- **Console logs** appear directly in the terminal
+- Use `console.log()` for quick debugging
+- Use `Logger` (DI-injected) for production logging to CloudWatch
+
+```typescript
+import { Logger } from "webiny/api/logger";
+
+// In your extension class
+this.logger.info("Processing request...");
+this.logger.warn("Something unexpected");
+this.logger.error("Something failed");
+```
+
+### Admin Errors
+
+Use browser DevTools:
+- **Console** -- view logs and errors
+- **Network tab** -- inspect GraphQL requests/responses
+- **React Developer Tools** -- debug component state/props
+- **GraphQL Network Inspector** -- inspect GraphQL operations
+
+### Infrastructure Errors
+
+Deployment errors from Pulumi typically relate to:
+- IAM permission issues
+- AWS service quotas
+- Resource configuration problems
+
+Check the deployment output for specific error messages.
+
+## CLI Commands Reference
+
+| Command | Purpose |
+|---|---|
+| `yarn webiny deploy` | Deploy all applications |
+| `yarn webiny deploy [core\|api\|admin]` | Deploy specific application |
+| `yarn webiny deploy --env <name>` | Deploy to specific environment |
+| `yarn webiny destroy --env <name>` | Destroy an environment |
+| `yarn webiny watch api` | Start local API development |
+| `yarn webiny watch admin` | Start local Admin development |
+| `yarn webiny info` | Show deployment info and URLs |
+| `yarn webiny info --env <name>` | Show info for specific environment |
+| `yarn webiny extension <name>` | Install a pre-built extension |
+
+## Quick Reference
+
+```
+First deploy:     yarn webiny deploy
+Dev API:          yarn webiny watch api
+Dev Admin:        yarn webiny watch admin
+Get URLs:         yarn webiny info
+Deploy env:       yarn webiny deploy --env staging
+After watch:      yarn webiny deploy api  (MUST redeploy!)
+```
+
+## Related Skills
+
+- `project-structure` -- Project layout and `webiny.config.tsx`
+- `infrastructure-extensions` -- Customizing AWS infrastructure and environments

package/skills/project-structure/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: webiny-project-structure
+context: webiny-extensions
+description: >
+  Webiny project layout, webiny.config.tsx anatomy, and extension registration.
+  Use this skill when the developer asks about folder structure, where custom code goes,
+  how to register extensions, what webiny.config.tsx does, or how the project is organized.
+  Also use when they need to understand the relationship between extensions/, webiny.config.tsx,
+  and the different extension types (Api, Admin, Infra, CLI).
+---
+
+# Webiny Project Structure
+
+## TL;DR
+
+A Webiny project has a flat structure centered around `webiny.config.tsx` -- the single configuration file where all extensions are registered. Custom code lives in the `extensions/` folder. Extensions are registered as React components (`<Api.Extension>`, `<Admin.Extension>`, `<Infra.*>`, `<Cli.Command>`) and can be conditionally loaded per environment.
+
+## Project Layout
+
+```
+my-webiny-project/
+├── extensions/          # All custom code -- API, Admin, Infra, CLI extensions
+│   └── README.md
+├── public/              # Static assets for the Admin app
+│   ├── favicon.ico
+│   ├── global.css
+│   ├── index.html
+│   └── robots.txt
+├── eslint.config.js     # ESLint configuration
+├── package.json         # Single package.json for the whole project
+├── tsconfig.json        # Single TypeScript config
+├── webiny.config.tsx    # Main configuration -- all extensions registered here
+├── webiny-env.d.ts      # TypeScript environment types
+└── yarn.lock
+```
+
+Key points:
+- **Single `package.json`** -- no monorepo, no workspaces needed.
+- **Single `tsconfig.json`** -- straightforward TypeScript setup.
+- **`webiny.config.tsx`** -- the entry point for everything. All extensions, infrastructure options, and project settings are declared here.
+- **`extensions/`** -- where all your custom code lives. Organize with subfolders as needed (e.g., `extensions/contactSubmission/`, `extensions/AdminBranding/`).
+
+## The `webiny.config.tsx` File
+
+This file exports a single React component called `Extensions`. It uses JSX to declaratively register all configuration:
+
+```tsx
+// webiny.config.tsx
+import React from "react";
+import { Admin, Api, Cli, Infra, Project, Security } from "webiny/extensions";
+import { Cognito } from "@webiny/cognito";
+
+export const Extensions = () => {
+    return (
+        <>
+            {/* Infrastructure configuration */}
+            <Infra.Aws.DefaultRegion name={"us-east-1"} />
+            <Infra.OpenSearch enabled={true} />
+            <Infra.Aws.Tags tags={{ OWNER: "me", PROJECT: "my-project" }} />
+
+            {/* Identity provider */}
+            <Cognito />
+
+            {/* API extensions (backend) */}
+            <Api.Extension src={"/extensions/ProductCategoryModel.ts"} />
+            <Api.Extension src={"/extensions/ProductModel.ts"} />
+            <Api.Extension src={"/extensions/contactSubmission/ContactSubmissionHook.ts"} />
+
+            {/* Security hooks */}
+            <Api.Extension src={"/extensions/MyApiKey.ts"} />
+            <Security.ApiKey.AfterUpdate src={"/extensions/MyApiKeyAfterUpdate.ts"} />
+
+            {/* Admin extensions (frontend) */}
+            <Admin.Extension src={"/extensions/AdminTheme/AdminTheme.tsx"} />
+            <Admin.Extension src={"/extensions/AdminTitleLogo/AdminTitleLogo.tsx"} />
+            <Admin.Extension src={"/extensions/contactSubmission/EmailEntryListColumn.tsx"} />
+
+            {/* Infrastructure / Pulumi extensions */}
+            <Infra.Core.Pulumi src={"/extensions/MyCorePulumiHandler.ts"} />
+
+            {/* CLI extensions */}
+            <Cli.Command src={"/extensions/MyCustomCommand.ts"} />
+
+            {/* Project settings */}
+            <Project.Telemetry enabled={false} />
+        </>
+    );
+};
+```
+
+## Extension Types
+
+| JSX Element | What It Does | File Type |
+|---|---|---|
+| `<Api.Extension src="..." />` | Registers a backend extension (GraphQL schemas, content models, lifecycle hooks) | `.ts` |
+| `<Admin.Extension src="..." />` | Registers a frontend Admin UI extension (themes, branding, custom columns, custom forms) | `.tsx` |
+| `<Infra.Core.Pulumi src="..." />` | Registers a Pulumi infrastructure handler | `.ts` |
+| `<Cli.Command src="..." />` | Registers a custom CLI command | `.ts` |
+| `<Security.ApiKey.AfterUpdate src="..." />` | Registers a security lifecycle hook | `.ts` |
+
+## Infrastructure Components
+
+Declarative components for configuring AWS infrastructure:
+
+| Component | Purpose |
+|---|---|
+| `<Infra.Aws.DefaultRegion name="us-east-1" />` | Set the AWS region |
+| `<Infra.Aws.Tags tags={{ KEY: "value" }} />` | Apply tags to all AWS resources |
+| `<Infra.OpenSearch enabled={true} />` | Enable/disable OpenSearch |
+| `<Infra.Vpc enabled={true} />` | Enable/disable VPC deployment |
+| `<Infra.PulumiResourceNamePrefix prefix="myproj-" />` | Prefix all Pulumi resource names |
+| `<Infra.ProductionEnvironments environments={["prod", "staging"]} />` | Define which envs use production infra |
+| `<Project.Telemetry enabled={false} />` | Enable/disable telemetry |
+
+## Environment-Conditional Configuration
+
+Use `<Infra.Env.Is>` to load extensions or config only in specific environments:
+
+```tsx
+<Infra.Env.Is env="prod">
+    <Infra.Aws.Tags tags={{ ENV: "production" }} />
+    <Infra.OpenSearch enabled={true} />
+</Infra.Env.Is>
+
+<Infra.Env.Is env={["dev", "staging"]}>
+    <Infra.Aws.Tags tags={{ ENV: "non-production" }} />
+    <Infra.OpenSearch enabled={false} />
+</Infra.Env.Is>
+```
+
+## Build Parameters
+
+Pass custom values from config to extensions at build time:
+
+```tsx
+<Api.BuildParam paramName="MY_CUSTOM_PARAM" value="customValue" />
+<Api.BuildParam paramName="MY_CONFIG" value={{ myKey: 2, nested: { foo: "bar" } }} />
+<Admin.BuildParam paramName="ADMIN_CUSTOM_PARAM" value="adminValue" />
+```
+
+These are accessed in extensions via the `BuildParams` feature (see dependency-injection skill).
+
+## Installing Pre-Built Extensions
+
+Webiny provides official extensions you can install with:
+
+```bash
+yarn webiny extension <extension-name>
+```
+
+This downloads the extension code into `extensions/`, updates `webiny.config.tsx` to register it, and gives you full access to modify the code.
+
+## Related Skills
+
+- `dependency-injection` -- How extensions use DI to access services
+- `local-development` -- How to deploy and develop locally

package/skills/webiny-sdk/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: webiny-sdk
+context: webiny-extensions
+description: >
+  Using @webiny/sdk to read and write CMS data from external applications.
+  Use this skill when the developer is building a Next.js, Vue, Node.js, or any external app
+  that needs to fetch or write content to Webiny, set up the SDK, use the Result pattern,
+  list/get/create/update/publish entries, filter and sort queries, use TypeScript generics
+  for type safety, work with the File Manager, or create API keys programmatically. Also
+  covers the three API types (Read, Manage, Preview) and CmsEntryData typing.
+---
+
+# Webiny SDK
+
+## TL;DR
+
+The `@webiny/sdk` package provides a TypeScript interface for external apps (Next.js, Vue, Node.js) to interact with Webiny's Headless CMS and File Manager. Every method returns a `Result` object (checked with `isOk()`). Supports listing, getting, creating, updating, publishing, and unpublishing entries with filtering, sorting, pagination, and TypeScript generics for type safety.
+
+## Installation & Setup
+
+```bash
+npm install @webiny/sdk
+```
+
+Initialize once and reuse:
+
+```typescript
+// lib/webiny.ts
+import { Sdk } from "@webiny/sdk";
+
+export const sdk = new Sdk({
+    token: process.env.WEBINY_API_TOKEN!,
+    endpoint: process.env.WEBINY_API_ENDPOINT!,
+    tenant: process.env.WEBINY_API_TENANT || "root"
+});
+```
+
+- `token` -- API key token generated in Webiny Admin (Settings > API Keys)
+- `endpoint` -- The base CloudFront URL (e.g., `https://xxx.cloudfront.net`). Run `yarn webiny info` to find it.
+- `tenant` -- Tenant ID, defaults to `"root"`
+
+## The Three API Types
+
+Webiny provides three separate GraphQL APIs:
+
+| API | URL Path | Returns | Can Write | Use For |
+|---|---|---|---|---|
+| **Read** | `/cms/read` | Published entries only | No | Public-facing apps, SSG |
+| **Manage** | `/cms/manage` | All revisions (drafts + published) | Yes | Admin tools, content creation |
+| **Preview** | `/cms/preview` | Latest revisions (drafts + published) | No | Content preview |
+
+The SDK automatically routes to the correct API based on the method:
+- `listEntries`, `getEntry` -> Read API
+- `createEntry`, `updateEntry`, `publishEntry`, `unpublishEntry` -> Manage API
+
+## The Result Pattern
+
+Every SDK method returns a `Result` object -- it never throws:
+
+```typescript
+const result = await sdk.cms.listEntries({ modelId: "product", fields: ["id"] });
+
+if (result.isOk()) {
+    console.log(result.value.data);    // success -- typed data
+} else {
+    console.error(result.error.message); // failure -- error info
+}
+```
+
+## TypeScript Generics
+
+Pass a type parameter for full type safety on `values`:
+
+```typescript
+import type { CmsEntryData } from "@webiny/sdk";
+
+interface Product {
+    name: string;
+    price: number;
+    sku: string;
+    description: string;
+    category?: CmsEntryData<ProductCategory>;
+}
+
+interface ProductCategory {
+    name: string;
+    slug: string;
+}
+
+const result = await sdk.cms.listEntries<Product>({
+    modelId: "product"
+});
+
+if (result.isOk()) {
+    // result.value.data is CmsEntryData<Product>[]
+    const products = result.value.data;
+    // products[0].values.name -- fully typed
+}
+```
+
+Reference fields like `category` are typed as `CmsEntryData<T>`, which wraps referenced entries with `id`, `entryId`, and `values`.
+
+## Reading Data
+
+### List Entries
+
+```typescript
+const result = await sdk.cms.listEntries<Product>({
+    modelId: "product",
+    sort: ["values.name_ASC"],
+    limit: 10
+});
+```
+
+### List with Filters
+
+```typescript
+const result = await sdk.cms.listEntries<Product>({
+    modelId: "product",
+    where: {
+        "values.price_gte": 100,
+        "values.name_contains": "Pro"
+    },
+    sort: ["values.price_DESC"]
+});
+```
+
+### Filter Operators
+
+| Operator | Description | Example |
+|---|---|---|
+| `_eq` | Equals (default) | `"values.status": "active"` |
+| `_not` | Not equals | `"values.status_not": "archived"` |
+| `_contains` | Contains substring | `"values.name_contains": "Pro"` |
+| `_startsWith` | Starts with | `"values.name_startsWith": "Web"` |
+| `_gt` / `_gte` | Greater than / >= | `"values.price_gte": 100` |
+| `_lt` / `_lte` | Less than / <= | `"values.price_lt": 500` |
+| `_in` | In array | `"values.status_in": ["active", "featured"]` |
+
+### Sort Format
+
+Sort strings follow the pattern `values.<fieldId>_ASC` or `values.<fieldId>_DESC`:
+
+```typescript
+sort: ["values.name_ASC"]          // alphabetical
+sort: ["values.price_DESC"]         // highest price first
+sort: ["values.createdOn_DESC"]     // newest first
+```
+
+### Get Single Entry
+
+```typescript
+const result = await sdk.cms.getEntry<Product>({
+    modelId: "product",
+    id: "abc123#0001"
+});
+```
+
+### The `fields` Parameter
+
+Control which fields are returned:
+
+```typescript
+const result = await sdk.cms.listEntries<Product>({
+    modelId: "product",
+    fields: ["id", "values.name", "values.price"]
+});
+```
+
+When omitted, all fields are returned. The `depth` parameter (default: `1`) controls how deeply reference fields are resolved.
+
+## Writing Data
+
+### Create an Entry
+
+```typescript
+const result = await sdk.cms.createEntry({
+    modelId: "contactSubmission",
+    data: {
+        name: "John Doe",
+        email: "john@example.com",
+        message: "Hello from the contact form!"
+    }
+});
+```
+
+### Update an Entry
+
+```typescript
+const result = await sdk.cms.updateEntry({
+    modelId: "product",
+    id: "abc123#0001",
+    data: {
+        price: 29.99
+    }
+});
+```
+
+### Publish / Unpublish
+
+```typescript
+await sdk.cms.publishEntry({ modelId: "product", id: "abc123#0001" });
+await sdk.cms.unpublishEntry({ modelId: "product", id: "abc123#0001" });
+```
+
+## File Manager
+
+```typescript
+// List files
+const files = await sdk.fileManager.listFiles({ limit: 20 });
+
+// Upload a file
+const uploaded = await sdk.fileManager.uploadFile({ file: myFile });
+```
+
+## Creating API Keys via Code
+
+For programmatic access, create API keys as an extension:
+
+```typescript
+// extensions/MyApiKey.ts
+import { ApiKeyFactory } from "webiny/api/security";
+
+class MyApiKeyImpl implements ApiKeyFactory.Interface {
+    execute(): ApiKeyFactory.Return {
+        return [
+            {
+                name: "Universal API Key",
+                slug: "universal-key",
+                token: "wat_12345678",
+                permissions: [{ name: "*" }]
+            }
+        ];
+    }
+}
+
+export default ApiKeyFactory.createImplementation({
+    implementation: MyApiKeyImpl,
+    dependencies: []
+});
+```
+
+Register:
+
+```tsx
+<Api.Extension src={"/extensions/MyApiKey.ts"} />
+```
+
+## SDK Modules Reference
+
+| Module | Webiny App | What You Can Do |
+|---|---|---|
+| `sdk.cms` | Headless CMS | List, get, create, update, publish, unpublish entries |
+| `sdk.fileManager` | File Manager | List, upload, and manage files and folders |
+| `sdk.websiteBuilder` | Website Builder | List and retrieve website builder content |
+
+## Quick Reference
+
+```
+Install:        npm install @webiny/sdk
+Import:         import { Sdk } from "@webiny/sdk";
+Type import:    import type { CmsEntryData } from "@webiny/sdk";
+Initialize:     new Sdk({ token, endpoint, tenant })
+Result check:   result.isOk() -> result.value.data / result.error.message
+API endpoint:   yarn webiny info (in your Webiny project)
+```
+
+## Related Skills
+
+- `content-models` -- Define the models you query with the SDK
+- `website-builder` -- Use the SDK inside Website Builder components to fetch CMS data