@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/{setup/multi-app-composition/SKILL.md → frontmcp-setup/references/multi-app-composition.md}

@@ -1,34 +1,28 @@
----
-name: multi-app-composition
-description: Compose multiple apps in a single server with shared tools, scoped auth, and external app loading. Use when building multi-app servers, sharing tools between apps, loading ESM or remote apps, or configuring per-app auth.
-tags: [multi-app, composition, architecture, scope, shared-tools]
-priority: 9
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/features/multi-app-composition
----
-
 # Multi-App Composition
 
 Compose multiple `@App` classes into a single `@FrontMcp` server. Each app contributes its own tools, resources, prompts, skills, and plugins. Apps can be local classes, npm packages loaded at runtime, or remote MCP servers proxied through your gateway.
 
-## When to Use Multi-App
+## When to Use This Skill
 
-**Single app** is sufficient when your server has one logical domain (e.g., a calculator, a file manager). Define one `@App` class with all tools and resources:
+### Must Use
 
-```typescript
-@App({ name: 'Calculator', tools: [AddTool, SubtractTool] })
-class CalcApp {}
+- Composing multiple `@App` classes with separate domains into a single `@FrontMcp` server
+- Aggregating external MCP servers via `app.remote()` or npm packages via `app.esm()` into a unified gateway
+- Configuring per-app authentication modes (e.g., one app public, another requiring OAuth)
 
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [CalcApp],
-})
-export default class Server {}
-```
+### Recommended
 
-**Multi-app** is needed when you have multiple domains, separate auth requirements, external MCP servers to aggregate, or npm packages to compose at runtime. The `apps` array in `@FrontMcp` accepts any combination of local classes, ESM packages, and remote servers.
+- Setting up shared tools, resources, or plugins that span all apps in the server
+- Isolating apps with `standalone: true` or `standalone: 'includeInParent'` for scoped auth or session separation
+- Namespacing tools from multiple apps or remote servers to prevent naming collisions
+
+### Skip When
+
+- Your server has a single logical domain with one `@App` class (see `project-structure-standalone`)
+- You are scaffolding an Nx monorepo workspace and need generator commands (see `project-structure-nx`)
+- You need to create individual tools, resources, or prompts rather than compose apps (see `create-tool`)
+
+> **Decision:** Use this skill when you need to compose two or more apps -- local, ESM, or remote -- into a single FrontMCP server with shared or scoped capabilities.
 
 ## Local Apps
 
@@ -356,3 +350,51 @@ class AdminApp {}
 })
 export default class Server {}
 ```
+
+## Common Patterns
+
+| Pattern              | Correct                                                                         | Incorrect                                                                     | Why                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Shared tools         | `@FrontMcp({ tools: [HealthCheckTool] })` (server-level)                        | Duplicating the tool class in every `@App` `tools` array                      | Server-level tools are automatically shared across all apps without duplication                   |
+| App namespacing      | `@App({ id: 'billing', name: 'Billing', tools: [ChargeTool] })`                 | Omitting `id` when multiple apps have tools with the same name                | The `id` field controls the namespace prefix (`billing:charge_card`); without it collisions occur |
+| Remote auth          | `remoteAuth: { mode: 'static', credentials: { type: 'bearer', value: token } }` | Passing the token directly as a string to `remoteAuth`                        | `remoteAuth` expects a structured object with `mode` and `credentials` fields                     |
+| Standalone isolation | `standalone: true` for fully isolated apps                                      | `standalone: true` when you still want tools visible in the parent server     | Use `standalone: 'includeInParent'` to get scope isolation with parent visibility                 |
+| Per-app auth         | `auth: { mode: 'remote', idpProviderUrl: '...' }` on `@App`                     | Configuring auth only at the `@FrontMcp` level when apps need different modes | Apps without their own `auth` inherit server-level config; set per-app `auth` for mixed modes     |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@FrontMcp` `apps` array includes all local, ESM, and remote apps
+- [ ] Each `@App` has a unique `id` (or unique `name` if `id` is omitted)
+- [ ] `namespace` is set on ESM and remote apps to prevent tool name collisions
+- [ ] Server-level `tools`, `plugins`, and `providers` are declared for shared capabilities
+
+### Runtime
+
+- [ ] All app tools appear in `tools/list` with correct namespace prefixes
+- [ ] Shared tools appear without a namespace prefix
+- [ ] `standalone: true` apps are isolated and do not appear in parent tool listing
+- [ ] `standalone: 'includeInParent'` apps have isolated scope but visible tools
+- [ ] Per-app auth modes are enforced independently per app
+
+### Remote Apps
+
+- [ ] `app.remote()` URL is reachable and returns valid MCP capabilities
+- [ ] `remoteAuth` credentials are correct and not expired
+- [ ] `fallbackToSSE` is enabled if the remote server does not support Streamable HTTP
+
+## Troubleshooting
+
+| Problem                                  | Cause                                                       | Solution                                                                                                 |
+| ---------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Tool name collision between apps         | Multiple apps register tools with the same name and no `id` | Set unique `id` on each `@App` or use `namespace` on ESM/remote apps                                     |
+| Remote app tools not appearing           | Remote server is unreachable or returns empty capabilities  | Verify the URL, check `transportOptions.timeout`, and ensure `remoteAuth` is correct                     |
+| Shared plugin not applied to an app      | Plugin declared on `@App` instead of `@FrontMcp`            | Move the plugin to the `@FrontMcp` `plugins` array for server-wide application                           |
+| `standalone: true` app tools not visible | Standalone apps are fully isolated by design                | Use `standalone: 'includeInParent'` to expose tools in the parent server while keeping scope isolation   |
+| Per-app auth not working                 | App does not declare its own `auth` field                   | Add `auth` configuration directly on the `@App` decorator; omitted `auth` inherits server-level defaults |
+
+## Reference
+
+- [Multi-App Composition Documentation](https://docs.agentfront.dev/frontmcp/features/multi-app-composition)
+- Related skills: `project-structure-standalone`, `project-structure-nx`, `configure-auth`, `create-tool`

package/catalog/{setup/nx-workflow/SKILL.md → frontmcp-setup/references/nx-workflow.md}

@@ -1,21 +1,28 @@
----
-name: nx-workflow
-description: Complete Nx monorepo workflow for FrontMCP with all generators, build, test, and deployment commands. Use when working in an Nx workspace, running generators, or managing monorepo builds.
-tags: [nx, monorepo, generators, workflow, scaffold]
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/nx-plugin/overview
----
-
 # Nx Monorepo Workflow for FrontMCP
 
 Use the `@frontmcp/nx` plugin to scaffold, build, test, and deploy FrontMCP projects in an Nx monorepo. The plugin provides generators for every FrontMCP primitive (tools, resources, prompts, skills, agents, plugins, adapters, providers, flows, jobs, workflows) and deployment shells for multiple targets.
 
-## When to Use Nx
+## When to Use This Skill
+
+### Must Use
+
+- Your project contains multiple apps or shared libraries in a monorepo structure
+- You need fine-grained build caching and affected-only testing in CI
+- You are scaffolding a new FrontMCP workspace with multiple deployment targets
+
+### Recommended
+
+- You want generator-based scaffolding for every FrontMCP primitive (tools, resources, prompts, skills, etc.)
+- You need to visualize and manage complex dependency graphs across projects
+- Your team benefits from parallelized builds and consistent project structure
+
+### Skip When
 
-Use the Nx workflow when your project has multiple apps, shared libraries, or needs fine-grained build caching and affected-only testing. For simple single-server projects, the standalone `frontmcp create` approach is sufficient.
+- Your project is a single standalone MCP server with no shared libraries -- use `frontmcp create` instead
+- You are adding FrontMCP to an existing non-Nx build system (Turborepo, Lerna) -- use `setup-project` instead
+- You only need to configure storage or auth without workspace scaffolding -- use `setup-sqlite` or `setup-redis` instead
+
+> **Decision:** Use this skill when managing a multi-project FrontMCP monorepo; skip it for single-server projects.
 
 ## Step 1 -- Initialize the Workspace
 
@@ -43,13 +50,13 @@ nx g @frontmcp/nx:workspace my-workspace
 
 The workspace generator creates the directory structure (`apps/`, `libs/`, `servers/`) and base configuration. It accepts these options:
 
-| Option            | Type                                 | Default    | Description                      |
-| ----------------- | ------------------------------------ | ---------- | -------------------------------- |
-| `name`            | `string`                             | (required) | Workspace name                   |
-| `packageManager`  | `'npm' \| 'yarn' \| 'pnpm' \| 'bun'` | `'npm'`    | Package manager to use           |
-| `skipInstall`     | `boolean`                            | `false`    | Skip package installation        |
-| `skipGit`         | `boolean`                            | `false`    | Skip git initialization          |
-| `createSampleApp` | `boolean`                            | `true`     | Create a sample demo application |
+| Option            | Type                        | Default    | Description                      |
+| ----------------- | --------------------------- | ---------- | -------------------------------- |
+| `name`            | `string`                    | (required) | Workspace name                   |
+| `packageManager`  | `'npm' \| 'yarn' \| 'pnpm'` | `'npm'`    | Package manager to use           |
+| `skipInstall`     | `boolean`                   | `false`    | Skip package installation        |
+| `skipGit`         | `boolean`                   | `false`    | Skip git initialization          |
+| `createSampleApp` | `boolean`                   | `true`     | Create a sample demo application |
 
 ## Step 2 -- Generate Apps and Libraries
 
@@ -252,7 +259,7 @@ nx run-many -t build,test,lint
 
 After scaffolding, the workspace follows this directory layout:
 
-```
+```text
 my-project/
   apps/
     my-app/
@@ -355,3 +362,53 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 | `job`           | `nx g @frontmcp/nx:job <name> --project=<app>`           | Generate a @Job class                                                |
 | `workflow`      | `nx g @frontmcp/nx:workflow <name> --project=<app>`      | Generate a @Workflow class                                           |
 | `auth-provider` | `nx g @frontmcp/nx:auth-provider <name> --project=<app>` | Generate an @AuthProvider class                                      |
+
+## Common Patterns
+
+| Pattern                    | Correct                                                 | Incorrect                              | Why                                                                                       |
+| -------------------------- | ------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Primitive generator target | `nx g @frontmcp/nx:tool my-tool --project=my-app`       | `nx g @frontmcp/nx:tool my-tool`       | All primitive generators require `--project` to specify which app receives the file       |
+| Test file naming           | `my-tool.tool.spec.ts`                                  | `my-tool.tool.test.ts`                 | FrontMCP enforces `.spec.ts` extension; `.test.ts` files are not picked up by Jest config |
+| Affected-only CI testing   | `nx affected -t test`                                   | `nx run-many -t test`                  | `affected` only runs tests for changed projects, saving CI time and compute               |
+| Server composition         | `nx g @frontmcp/nx:server my-server --apps=app-a,app-b` | Manually importing apps in `main.ts`   | The server generator wires app composition and deployment config automatically            |
+| Build before deploy        | `nx build my-server` (builds server + all deps)         | Building each lib and app individually | Nx resolves the dependency graph and builds in the correct order with caching             |
+
+## Verification Checklist
+
+### Workspace Setup
+
+- [ ] `@frontmcp/nx` is listed in `devDependencies`
+- [ ] `nx.json` exists at workspace root with valid configuration
+- [ ] `apps/`, `libs/`, and `servers/` directories exist
+
+### Generation
+
+- [ ] Generated files are placed in the correct directory (`apps/<app>/src/<type>/`)
+- [ ] Barrel exports (`index.ts`) are updated after each generator run
+- [ ] `.spec.ts` test file is created alongside each generated class
+
+### Build and Test
+
+- [ ] `nx build <server>` completes without TypeScript errors or warnings
+- [ ] `nx test <app>` passes with 95%+ coverage
+- [ ] `nx affected -t test` correctly identifies changed projects
+
+### Development Workflow
+
+- [ ] `nx serve <server>` or `nx dev <server>` starts the server successfully
+- [ ] `nx graph` renders the project dependency graph in the browser
+
+## Troubleshooting
+
+| Problem                                        | Cause                                                       | Solution                                                                                             |
+| ---------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@frontmcp/nx'`            | Plugin not installed                                        | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                            |
+| Generator creates files in the wrong directory | Missing or incorrect `--project` flag                       | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`        |
+| `nx affected` runs nothing despite changes     | Base branch not configured or no dependency link            | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph |
+| Build fails with circular dependency error     | Library A imports from Library B and vice versa             | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
+| Cache not working (full rebuild every time)    | Missing or misconfigured `cacheableOperations` in `nx.json` | Ensure `build`, `test`, and `lint` are listed in `targetDefaults` with `cache: true`                 |
+
+## Reference
+
+- **Docs:** [Nx Plugin Overview](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
+- **Related skills:** `setup-project`, `setup-sqlite`, `setup-redis`

package/catalog/frontmcp-setup/references/project-structure-nx.md

@@ -0,0 +1,246 @@
+# Nx Monorepo Project Structure
+
+## When to Use This Skill
+
+### Must Use
+
+- Scaffolding a new FrontMCP project with `frontmcp create --nx` or adding FrontMCP to an existing Nx workspace
+- Organizing multiple `@App` modules, shared libraries, and `@FrontMcp` server entry points in a monorepo
+- Understanding the `apps/`, `libs/`, `servers/` directory hierarchy and Nx dependency rules
+
+### Recommended
+
+- Setting up Nx generators to scaffold tools, resources, providers, and other entities within apps
+- Configuring multiple servers that compose different combinations of apps (e.g., public gateway and internal admin)
+- Leveraging Nx caching, dependency graph, and `run-many` commands for efficient builds and tests
+
+### Skip When
+
+- You are building a single standalone project without Nx (see `project-structure-standalone`)
+- You need to compose multiple apps within a single server and already have the Nx structure (see `multi-app-composition`)
+- You are looking for a specific Nx build or CI workflow (see `nx-workflow`)
+
+> **Decision:** Use this skill when setting up or organizing a FrontMCP Nx monorepo and you need the canonical directory layout, generator commands, and dependency rules.
+
+When you scaffold with `frontmcp create --nx` or add FrontMCP to an existing Nx workspace, the recommended layout separates apps, shared libraries, and server entry points:
+
+```text
+my-workspace/
+├── apps/                     # @App classes (one app per directory)
+│   ├── billing/
+│   │   ├── src/
+│   │   │   ├── billing.app.ts
+│   │   │   ├── tools/
+│   │   │   ├── resources/
+│   │   │   └── providers/
+│   │   ├── project.json
+│   │   └── tsconfig.json
+│   └── crm/
+│       ├── src/
+│       │   ├── crm.app.ts
+│       │   ├── tools/
+│       │   └── resources/
+│       ├── project.json
+│       └── tsconfig.json
+├── libs/                     # Shared libraries
+│   └── shared-utils/
+│       ├── src/
+│       │   └── index.ts
+│       ├── project.json
+│       └── tsconfig.json
+├── servers/                  # @FrontMcp servers composing apps
+│   └── gateway/
+│       ├── src/
+│       │   └── main.ts       # @FrontMcp default export
+│       ├── project.json
+│       └── tsconfig.json
+├── nx.json
+├── tsconfig.base.json
+├── CLAUDE.md                 # AI config (auto-generated)
+├── AGENTS.md
+├── .mcp.json
+└── .cursorrules
+```
+
+## Directory Roles
+
+### apps/ -- Application Modules
+
+Each directory under `apps/` contains a single `@App` class with its tools, resources, prompts, providers, and plugins:
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+import { InvoiceResource } from './resources/invoice.resource';
+import { StripeProvider } from './providers/stripe.provider';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+  providers: [StripeProvider],
+})
+export class BillingApp {}
+```
+
+Apps are self-contained and independently testable. They do not import from other apps -- shared code goes in `libs/`.
+
+### libs/ -- Shared Libraries
+
+Shared providers, utilities, types, and common logic live under `libs/`:
+
+```typescript
+// libs/shared-utils/src/index.ts
+export { formatCurrency } from './format-currency';
+export { DatabaseProvider } from './database.provider';
+export type { AppConfig } from './app-config.interface';
+```
+
+Apps and servers import from libs using Nx path aliases configured in `tsconfig.base.json`:
+
+```typescript
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+```
+
+### servers/ -- FrontMcp Entry Points
+
+A server composes multiple apps into a single `@FrontMcp` entry point:
+
+```typescript
+// servers/gateway/src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+})
+class GatewayServer {}
+
+export default GatewayServer;
+```
+
+You can have multiple servers composing different combinations of apps (e.g., a public-facing server and an internal admin server).
+
+## Nx Generators
+
+The `@frontmcp/nx` package provides generators for common entity types:
+
+```bash
+# Generate a new app
+nx g @frontmcp/nx:app crm
+
+# Generate entities within an app
+nx g @frontmcp/nx:tool lookup-user --project=crm
+nx g @frontmcp/nx:resource user-profile --project=crm
+nx g @frontmcp/nx:prompt summarize --project=crm
+nx g @frontmcp/nx:provider database --project=crm
+nx g @frontmcp/nx:plugin logging --project=crm
+nx g @frontmcp/nx:agent research --project=crm
+nx g @frontmcp/nx:job cleanup --project=crm
+nx g @frontmcp/nx:skill my-skill --project=crm
+nx g @frontmcp/nx:skill-dir my-skill-dir --project=crm
+
+# Generate a new server
+nx g @frontmcp/nx:server gateway
+
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+```
+
+## Build and Test Commands
+
+```bash
+# Build a specific server
+nx build gateway
+
+# Test a specific app
+nx test billing
+
+# Run all tests
+nx run-many -t test
+
+# Build all projects
+nx run-many -t build
+
+# Lint everything
+nx run-many -t lint
+```
+
+Nx caches build and test results. Subsequent runs for unchanged projects are instant.
+
+## AI Configuration Files
+
+FrontMCP auto-generates AI configuration files at the workspace root:
+
+| File           | Purpose                                  |
+| -------------- | ---------------------------------------- |
+| `CLAUDE.md`    | Instructions for Claude Code / Claude AI |
+| `AGENTS.md`    | Instructions for agent-based AI tools    |
+| `.mcp.json`    | MCP server configuration for AI IDEs     |
+| `.cursorrules` | Rules for Cursor AI editor               |
+
+These files are regenerated when you run generators or modify your workspace structure. They help AI tools understand your project layout and coding conventions.
+
+## Dependency Graph
+
+Nx enforces a clear dependency hierarchy:
+
+```text
+servers/ --> apps/ --> libs/
+```
+
+- **servers** can import from **apps** and **libs**
+- **apps** can import from **libs** only (never from other apps or servers)
+- **libs** can import from other **libs** only
+
+Use `nx graph` to visualize the dependency graph and ensure no circular imports exist.
+
+## Common Patterns
+
+| Pattern            | Correct                                                          | Incorrect                                                         | Why                                                                            |
+| ------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| App isolation      | Apps import from `libs/` only, never from other apps             | `apps/billing` imports from `apps/crm` directly                   | Cross-app imports create circular dependencies; shared code belongs in `libs/` |
+| Server composition | `servers/gateway/src/main.ts` imports apps via Nx path aliases   | Server file inlines tool classes instead of importing from apps   | Servers compose `@App` classes; inlining defeats the monorepo separation       |
+| Path aliases       | `import { BillingApp } from '@my-workspace/billing'`             | `import { BillingApp } from '../../apps/billing/src/billing.app'` | Nx path aliases in `tsconfig.base.json` keep imports clean and refactorable    |
+| Generator usage    | `nx g @frontmcp/nx:tool lookup-user --project=crm`               | Manually creating tool files without updating barrel exports      | Generators handle file creation, spec scaffolding, and barrel export updates   |
+| AI config files    | Let FrontMCP auto-generate `CLAUDE.md`, `AGENTS.md`, `.mcp.json` | Hand-editing auto-generated AI config files                       | These files are regenerated by generators; manual edits will be overwritten    |
+
+## Verification Checklist
+
+### Workspace Structure
+
+- [ ] `nx.json` and `tsconfig.base.json` exist at the workspace root
+- [ ] Each app under `apps/` has its own `project.json` and `tsconfig.json`
+- [ ] Shared libraries under `libs/` have `project.json` and barrel `index.ts`
+- [ ] Server entry points under `servers/` default-export the `@FrontMcp` class
+
+### Build and Test
+
+- [ ] `nx build gateway` (or server name) succeeds without errors
+- [ ] `nx test billing` (or app name) passes all tests
+- [ ] `nx run-many -t test` runs all tests across the workspace
+- [ ] `nx graph` shows no circular dependencies between apps
+
+### Generators
+
+- [ ] `nx g @frontmcp/nx:app <name>` creates a valid app scaffold
+- [ ] `nx g @frontmcp/nx:tool <name> --project=<app>` creates tool with spec and barrel update
+- [ ] `nx g @frontmcp/nx:server <name>` creates a server entry point
+
+## Troubleshooting
+
+| Problem                                  | Cause                                                   | Solution                                                                   |
+| ---------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Import path not resolving                | Missing or incorrect path alias in `tsconfig.base.json` | Add the correct `@my-workspace/<lib>` path mapping to `tsconfig.base.json` |
+| `nx graph` shows circular dependency     | App imports from another app instead of a shared lib    | Move shared code to `libs/` and import from there in both apps             |
+| Generator fails with "project not found" | Incorrect `--project` name passed to the generator      | Use the project name from `project.json`, not the directory name           |
+| Nx cache returns stale results           | Source files changed but Nx hash did not detect it      | Run `nx reset` to clear the cache, then rebuild                            |
+| Server cannot find app export            | App barrel `index.ts` does not export the `@App` class  | Add the app class to the barrel export in `apps/<name>/src/index.ts`       |
+
+## Reference
+
+- [Nx Plugin Documentation](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
+- Related skills: `project-structure-standalone`, `multi-app-composition`, `nx-workflow`, `setup-project`