@frontmcp/nx 0.12.2 → 1.0.0-beta.10

package/generators/ui-shared/add-ui-entry.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addUiEntry = addUiEntry;
+const devkit_1 = require("@nx/devkit");
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Adds an entry point to an existing UI package:
+ * 1. Updates project.json `additionalEntryPoints` in both build-cjs and build-esm
+ * 2. Updates tsconfig.base.json path aliases (wildcard already covers it, but explicit is fine)
+ * 3. Adds re-export to the barrel index.ts
+ */
+function addUiEntry(tree, options) {
+    const { packageRoot, entryName, importPath } = options;
+    const entryPath = `${packageRoot}/src/${entryName}/index.ts`;
+    // 1. Update project.json — add to additionalEntryPoints in build-cjs and build-esm
+    const projectJsonPath = `${packageRoot}/project.json`;
+    if (tree.exists(projectJsonPath)) {
+        (0, devkit_1.updateJson)(tree, projectJsonPath, (json) => {
+            for (const target of ['build-cjs', 'build-esm']) {
+                const opts = json.targets?.[target]?.options;
+                if (opts) {
+                    opts.additionalEntryPoints = opts.additionalEntryPoints ?? [];
+                    if (!opts.additionalEntryPoints.includes(entryPath)) {
+                        opts.additionalEntryPoints.push(entryPath);
+                    }
+                }
+            }
+            return json;
+        });
+    }
+    // 2. Update tsconfig.base.json — add explicit path alias
+    //    The wildcard alias already covers resolution, but adding an explicit
+    //    entry improves IDE completion and Nx dep graph accuracy.
+    if (tree.exists('tsconfig.base.json')) {
+        (0, devkit_1.updateJson)(tree, 'tsconfig.base.json', (json) => {
+            const paths = json.compilerOptions?.paths ?? {};
+            const aliasKey = `${importPath}/${entryName}`;
+            if (!paths[aliasKey]) {
+                paths[aliasKey] = [`${packageRoot}/src/${entryName}/index.ts`];
+            }
+            json.compilerOptions = json.compilerOptions ?? {};
+            json.compilerOptions.paths = paths;
+            return json;
+        });
+    }
+    // 3. Add re-export to barrel index.ts
+    const barrelPath = `${packageRoot}/src/index.ts`;
+    if (tree.exists(barrelPath)) {
+        const existing = tree.read(barrelPath, 'utf-8') ?? '';
+        const exportLine = `export * from './${entryName}';\n`;
+        const duplicatePattern = new RegExp(`^export \\* from '\\./${escapeRegExp(entryName)}';?$`, 'm');
+        if (!duplicatePattern.test(existing)) {
+            const normalized = existing.endsWith('\n') || existing === '' ? existing : existing + '\n';
+            tree.write(barrelPath, normalized + exportLine);
+        }
+    }
+}
+//# sourceMappingURL=add-ui-entry.js.map

package/generators/ui-shared/add-ui-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-ui-entry.js","sourceRoot":"","sources":["../../../../src/generators/ui-shared/add-ui-entry.ts"],"names":[],"mappings":";;AAqBA,gCAgDC;AArED,uCAAmD;AAEnD,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAWD;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,IAAU,EAAE,OAA0B;IAC/D,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACvD,MAAM,SAAS,GAAG,GAAG,WAAW,QAAQ,SAAS,WAAW,CAAC;IAE7D,mFAAmF;IACnF,MAAM,eAAe,GAAG,GAAG,WAAW,eAAe,CAAC;IACtD,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,IAAA,mBAAU,EAAC,IAAI,EAAE,eAAe,EAAE,CAAC,IAAI,EAAE,EAAE;YACzC,KAAK,MAAM,MAAM,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;gBAC7C,IAAI,IAAI,EAAE,CAAC;oBACT,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC,qBAAqB,IAAI,EAAE,CAAC;oBAC9D,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;wBACpD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yDAAyD;IACzD,0EAA0E;IAC1E,8DAA8D;IAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACtC,IAAA,mBAAU,EAAC,IAAI,EAAE,oBAAoB,EAAE,CAAC,IAAI,EAAE,EAAE;YAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,EAAE,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,QAAQ,GAAG,GAAG,UAAU,IAAI,SAAS,EAAE,CAAC;YAC9C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACrB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,WAAW,QAAQ,SAAS,WAAW,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC;YAClD,IAAI,CAAC,eAAe,CAAC,KAAK,GAAG,KAAK,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,sCAAsC;IACtC,MAAM,UAAU,GAAG,GAAG,WAAW,eAAe,CAAC;IACjD,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACtD,MAAM,UAAU,GAAG,oBAAoB,SAAS,MAAM,CAAC;QACvD,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,yBAAyB,YAAY,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC;YAC3F,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { type Tree, updateJson } from '@nx/devkit';\n\nfunction escapeRegExp(str: string): string {\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nexport interface AddUiEntryOptions {\n  /** The UI package root, e.g. 'ui/components' */\n  packageRoot: string;\n  /** The entry name, e.g. 'LoginForm' or 'admin-dashboard' */\n  entryName: string;\n  /** The npm scope name, e.g. '@frontmcp/ui-components' */\n  importPath: string;\n}\n\n/**\n * Adds an entry point to an existing UI package:\n * 1. Updates project.json `additionalEntryPoints` in both build-cjs and build-esm\n * 2. Updates tsconfig.base.json path aliases (wildcard already covers it, but explicit is fine)\n * 3. Adds re-export to the barrel index.ts\n */\nexport function addUiEntry(tree: Tree, options: AddUiEntryOptions): void {\n  const { packageRoot, entryName, importPath } = options;\n  const entryPath = `${packageRoot}/src/${entryName}/index.ts`;\n\n  // 1. Update project.json — add to additionalEntryPoints in build-cjs and build-esm\n  const projectJsonPath = `${packageRoot}/project.json`;\n  if (tree.exists(projectJsonPath)) {\n    updateJson(tree, projectJsonPath, (json) => {\n      for (const target of ['build-cjs', 'build-esm']) {\n        const opts = json.targets?.[target]?.options;\n        if (opts) {\n          opts.additionalEntryPoints = opts.additionalEntryPoints ?? [];\n          if (!opts.additionalEntryPoints.includes(entryPath)) {\n            opts.additionalEntryPoints.push(entryPath);\n          }\n        }\n      }\n      return json;\n    });\n  }\n\n  // 2. Update tsconfig.base.json — add explicit path alias\n  //    The wildcard alias already covers resolution, but adding an explicit\n  //    entry improves IDE completion and Nx dep graph accuracy.\n  if (tree.exists('tsconfig.base.json')) {\n    updateJson(tree, 'tsconfig.base.json', (json) => {\n      const paths = json.compilerOptions?.paths ?? {};\n      const aliasKey = `${importPath}/${entryName}`;\n      if (!paths[aliasKey]) {\n        paths[aliasKey] = [`${packageRoot}/src/${entryName}/index.ts`];\n      }\n      json.compilerOptions = json.compilerOptions ?? {};\n      json.compilerOptions.paths = paths;\n      return json;\n    });\n  }\n\n  // 3. Add re-export to barrel index.ts\n  const barrelPath = `${packageRoot}/src/index.ts`;\n  if (tree.exists(barrelPath)) {\n    const existing = tree.read(barrelPath, 'utf-8') ?? '';\n    const exportLine = `export * from './${entryName}';\\n`;\n    const duplicatePattern = new RegExp(`^export \\\\* from '\\\\./${escapeRegExp(entryName)}';?$`, 'm');\n    if (!duplicatePattern.test(existing)) {\n      const normalized = existing.endsWith('\\n') || existing === '' ? existing : existing + '\\n';\n      tree.write(barrelPath, normalized + exportLine);\n    }\n  }\n}\n"]}

package/generators/ui-shell/files/__fileName__/__fileName__.shell.spec.ts__tmpl__

@@ -0,0 +1,16 @@
+import { build<%= className %>Shell } from './<%= fileName %>.shell';
+
+describe('build<%= className %>Shell', () => {
+  it('should be defined', () => {
+    expect(build<%= className %>Shell).toBeDefined();
+  });
+
+  it('should be a function', () => {
+    expect(typeof build<%= className %>Shell).toBe('function');
+  });
+
+  it('should return an HTML string', () => {
+    const result = build<%= className %>Shell({ toolName: 'test' });
+    expect(typeof result).toBe('string');
+  });
+});

package/generators/ui-shell/files/__fileName__/__fileName__.shell.ts__tmpl__

@@ -0,0 +1,20 @@
+import { buildShell } from '@frontmcp/uipack';
+
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+export interface <%= className %>ShellOptions {
+  toolName: string;
+  input?: unknown;
+  output?: unknown;
+}
+
+export function build<%= className %>Shell(options: <%= className %>ShellOptions) {
+  const content = `<div id="app">TODO: implement ${escapeHtml(options.toolName)} shell</div>`;
+  return buildShell(content, {
+    toolName: options.toolName,
+    input: options.input,
+    output: options.output,
+  });
+}

package/generators/ui-shell/files/__fileName__/index.ts__tmpl__

@@ -0,0 +1,2 @@
+export { build<%= className %>Shell } from './<%= fileName %>.shell';
+export type { <%= className %>ShellOptions } from './<%= fileName %>.shell';

package/generators/ui-shell/schema.d.ts

@@ -0,0 +1,5 @@
+export interface UiShellGeneratorSchema {
+    name: string;
+    description?: string;
+    skipFormat?: boolean;
+}

package/generators/ui-shell/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/generators/ui-shell/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../src/generators/ui-shell/schema.ts"],"names":[],"mappings":"","sourcesContent":["export interface UiShellGeneratorSchema {\n  name: string;\n  description?: string;\n  skipFormat?: boolean;\n}\n"]}

package/generators/ui-shell/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "FrontMcpUiShell",
+  "title": "FrontMCP UI Shell Generator",
+  "description": "Add a shell template entry to ui/shells",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Shell name (kebab-case, e.g. admin-dashboard)",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "What name would you like for the shell (kebab-case)?",
+      "x-priority": "important"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of the shell template",
+      "default": ""
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "default": false,
+      "x-priority": "internal"
+    }
+  },
+  "required": ["name"]
+}

package/generators/ui-shell/ui-shell.d.ts

@@ -0,0 +1,4 @@
+import { type Tree, type GeneratorCallback } from '@nx/devkit';
+import type { UiShellGeneratorSchema } from './schema.js';
+export declare function uiShellGenerator(tree: Tree, schema: UiShellGeneratorSchema): Promise<GeneratorCallback | void>;
+export default uiShellGenerator;

package/generators/ui-shell/ui-shell.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uiShellGenerator = uiShellGenerator;
+const devkit_1 = require("@nx/devkit");
+const path_1 = require("path");
+const add_ui_entry_js_1 = require("../ui-shared/add-ui-entry.js");
+const PACKAGE_ROOT = 'ui/shells';
+const IMPORT_PATH = '@frontmcp/ui-shells';
+async function uiShellGenerator(tree, schema) {
+    const { className, fileName } = (0, devkit_1.names)(schema.name);
+    // Generate shell files from templates (kebab-case naming)
+    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), `${PACKAGE_ROOT}/src`, {
+        className,
+        fileName,
+        name: schema.name,
+        description: schema.description ?? '',
+        tmpl: '',
+    });
+    // Add entry point to project.json, tsconfig.base.json, and barrel index.ts
+    (0, add_ui_entry_js_1.addUiEntry)(tree, {
+        packageRoot: PACKAGE_ROOT,
+        entryName: fileName,
+        importPath: IMPORT_PATH,
+    });
+    if (!schema.skipFormat) {
+        await (0, devkit_1.formatFiles)(tree);
+    }
+}
+exports.default = uiShellGenerator;
+//# sourceMappingURL=ui-shell.js.map

package/generators/ui-shell/ui-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-shell.js","sourceRoot":"","sources":["../../../../src/generators/ui-shell/ui-shell.ts"],"names":[],"mappings":";;AAQA,4CAsBC;AA9BD,uCAAkG;AAClG,+BAA4B;AAE5B,kEAA0D;AAE1D,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAEnC,KAAK,UAAU,gBAAgB,CAAC,IAAU,EAAE,MAA8B;IAC/E,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAA,cAAK,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAEnD,0DAA0D;IAC1D,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAA,WAAI,EAAC,SAAS,EAAE,OAAO,CAAC,EAAE,GAAG,YAAY,MAAM,EAAE;QACnE,SAAS;QACT,QAAQ;QACR,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;QACrC,IAAI,EAAE,EAAE;KACT,CAAC,CAAC;IAEH,2EAA2E;IAC3E,IAAA,4BAAU,EAAC,IAAI,EAAE;QACf,WAAW,EAAE,YAAY;QACzB,SAAS,EAAE,QAAQ;QACnB,UAAU,EAAE,WAAW;KACxB,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACvB,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,kBAAe,gBAAgB,CAAC","sourcesContent":["import { type Tree, formatFiles, generateFiles, names, type GeneratorCallback } from '@nx/devkit';\nimport { join } from 'path';\nimport type { UiShellGeneratorSchema } from './schema.js';\nimport { addUiEntry } from '../ui-shared/add-ui-entry.js';\n\nconst PACKAGE_ROOT = 'ui/shells';\nconst IMPORT_PATH = '@frontmcp/ui-shells';\n\nexport async function uiShellGenerator(tree: Tree, schema: UiShellGeneratorSchema): Promise<GeneratorCallback | void> {\n  const { className, fileName } = names(schema.name);\n\n  // Generate shell files from templates (kebab-case naming)\n  generateFiles(tree, join(__dirname, 'files'), `${PACKAGE_ROOT}/src`, {\n    className,\n    fileName,\n    name: schema.name,\n    description: schema.description ?? '',\n    tmpl: '',\n  });\n\n  // Add entry point to project.json, tsconfig.base.json, and barrel index.ts\n  addUiEntry(tree, {\n    packageRoot: PACKAGE_ROOT,\n    entryName: fileName,\n    importPath: IMPORT_PATH,\n  });\n\n  if (!schema.skipFormat) {\n    await formatFiles(tree);\n  }\n}\n\nexport default uiShellGenerator;\n"]}

package/generators/workspace/files/AGENTS.md__tmpl__

@@ -0,0 +1,52 @@
+# <%= name %> — Agent Guidelines
+
+## Project Type
+
+FrontMCP monorepo — TypeScript-first framework for building MCP (Model Context Protocol) servers.
+
+## Architecture
+
+- **Monorepo**: Nx-based with `apps/`, `libs/`, `servers/` workspaces
+- **Language**: TypeScript with strict mode enabled
+- **Build system**: Nx (`npx nx build/test/serve <project>`)
+- **Testing**: Jest with 95%+ coverage requirement
+- **Package manager**: <%= packageManager %>
+
+## Code Generation
+
+**Always use Nx generators** — never create files manually:
+
+```bash
+npx nx g @frontmcp/nx:tool <Name> --project <lib>
+npx nx g @frontmcp/nx:resource <Name> --project <lib>
+npx nx g @frontmcp/nx:prompt <Name> --project <lib>
+npx nx g @frontmcp/nx:provider <Name> --project <lib>
+npx nx g @frontmcp/nx:app <name>
+npx nx g @frontmcp/nx:lib <name>
+npx nx g @frontmcp/nx:server <name>
+```
+
+See `CLAUDE.md` for the full list of 19 generators.
+
+## Key Decorators & Context Classes
+
+| Decorator | Context Class | Purpose |
+|-----------|---------------|---------|
+| `@Tool` | `ToolContext` | MCP tool with Zod input/output |
+| `@Resource` / `@ResourceTemplate` | `ResourceContext` | MCP resource |
+| `@Prompt` | `PromptContext` | MCP prompt returning `GetPromptResult` |
+| `@Provider` | — | DI provider with Symbol token |
+| `@App` | — | Application grouping tools/resources/prompts |
+| `@FrontMcp` | — | Server entry point |
+
+## Constraints
+
+- No `any` types — use `unknown` for generic defaults
+- No raw `node:crypto` or `fs` — use `@frontmcp/utils`
+- No non-null assertions (`!`) — throw proper errors
+- Zod v4 for all schema validation
+- `@frontmcp/testing` for test harnesses
+
+## Documentation Access
+
+The `.mcp.json` file configures a `frontmcp-docs` MCP server. Use the `SearchAgentFront` tool to search FrontMCP documentation.

package/generators/workspace/files/CLAUDE.md__tmpl__

@@ -0,0 +1,216 @@
+# <%= name %> — FrontMCP Workspace
+
+This is a **FrontMCP** monorepo — a TypeScript-first framework for building production-grade MCP (Model Context Protocol) servers with decorators, dependency injection, and strict type safety.
+
+## Monorepo Structure
+
+```
+<%= name %>/
+  apps/          # MCP application definitions (@App decorator)
+  libs/          # Shared libraries (tools, resources, providers)
+  servers/       # Deployment shells (Express/Fastify adapters)
+```
+
+## Key Commands
+
+```bash
+# Build / test / serve a specific project
+npx nx build <project>
+npx nx test <project>
+npx nx serve <project>
+
+# Run across all projects
+npx nx run-many -t build
+npx nx run-many -t test
+
+# Start dev server with watch mode
+npx nx dev <server-project>
+```
+
+## Nx Generators
+
+Always use generators to scaffold new code — never create files manually.
+
+### Structural generators
+
+| Generator | Command | Description |
+|-----------|---------|-------------|
+| workspace | `npx nx g @frontmcp/nx:workspace <name>` | New FrontMCP monorepo |
+| app | `npx nx g @frontmcp/nx:app <name>` | MCP application |
+| lib | `npx nx g @frontmcp/nx:lib <name>` | Shared library |
+| server | `npx nx g @frontmcp/nx:server <name>` | Deployment shell |
+
+### Component generators (use `--project` to target a library)
+
+| Generator | Command | Description |
+|-----------|---------|-------------|
+| tool | `npx nx g @frontmcp/nx:tool <Name> --project <lib>` | MCP tool with Zod schemas |
+| resource | `npx nx g @frontmcp/nx:resource <Name> --project <lib>` | MCP resource |
+| prompt | `npx nx g @frontmcp/nx:prompt <Name> --project <lib>` | MCP prompt |
+| skill | `npx nx g @frontmcp/nx:skill <Name> --project <lib>` | Composite skill |
+| agent | `npx nx g @frontmcp/nx:agent <Name> --project <lib>` | Agent definition |
+| provider | `npx nx g @frontmcp/nx:provider <Name> --project <lib>` | DI provider |
+| plugin | `npx nx g @frontmcp/nx:plugin <Name> --project <lib>` | Plugin |
+| adapter | `npx nx g @frontmcp/nx:adapter <Name> --project <lib>` | Framework adapter |
+| auth-provider | `npx nx g @frontmcp/nx:auth-provider <Name> --project <lib>` | Auth provider |
+| flow | `npx nx g @frontmcp/nx:flow <Name> --project <lib>` | Flow definition |
+| job | `npx nx g @frontmcp/nx:job <Name> --project <lib>` | Background job |
+| workflow | `npx nx g @frontmcp/nx:workflow <Name> --project <lib>` | Multi-step workflow |
+
+### UI generators
+
+| Generator | Command | Description |
+|-----------|---------|-------------|
+| ui-component | `npx nx g @frontmcp/nx:ui-component <Name>` | React component (PascalCase) |
+| ui-page | `npx nx g @frontmcp/nx:ui-page <Name>` | Full-page React component |
+| ui-shell | `npx nx g @frontmcp/nx:ui-shell <name>` | Server-side HTML shell (kebab-case) |
+
+## Architecture Patterns
+
+### Server entry point (`main.ts`)
+
+```typescript
+import { FrontMcp, StdioTransport } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  name: 'my-server',
+  version: '1.0.0',
+  apps: [MyApp],
+})
+class MyServer {}
+
+new StdioTransport(MyServer).start();
+```
+
+### App definition
+
+```typescript
+import { App } from '@frontmcp/sdk';
+import { MyTool } from './tools/my-tool.tool';
+import { MyResource } from './resources/my-resource.resource';
+
+@App({
+  tools: [MyTool],
+  resources: [MyResource],
+  prompts: [],
+  providers: [],
+})
+export class MyApp {}
+```
+
+### Tool (most common pattern)
+
+```typescript
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const inputSchema = z.object({
+  query: z.string().describe('Search query'),
+});
+
+const outputSchema = z.object({
+  results: z.array(z.string()),
+});
+
+@Tool({
+  name: 'search',
+  description: 'Search for items',
+  inputSchema,
+  outputSchema,
+})
+export class SearchTool extends ToolContext<typeof inputSchema, typeof outputSchema> {
+  async execute(input: z.infer<typeof inputSchema>) {
+    const results = ['result1', 'result2'];
+    return { results };
+  }
+}
+```
+
+### Resource
+
+```typescript
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  uri: 'myapp://config',
+  name: 'App Configuration',
+  mimeType: 'application/json',
+})
+export class ConfigResource extends ResourceContext {
+  async read() {
+    return { uri: 'myapp://config', text: JSON.stringify({ key: 'value' }) };
+  }
+}
+```
+
+### Resource Template (dynamic URIs)
+
+```typescript
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+
+@ResourceTemplate({
+  uriTemplate: 'myapp://users/{userId}',
+  name: 'User Profile',
+  mimeType: 'application/json',
+})
+export class UserResource extends ResourceContext<{ userId: string }> {
+  async read(params: { userId: string }) {
+    return { uri: `myapp://users/${params.userId}`, text: JSON.stringify({ id: params.userId }) };
+  }
+}
+```
+
+### Prompt
+
+```typescript
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+
+@Prompt({
+  name: 'summarize',
+  description: 'Summarize content',
+})
+export class SummarizePrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    return {
+      messages: [
+        { role: 'user', content: { type: 'text', text: `Summarize: ${args['content']}` } },
+      ],
+    };
+  }
+}
+```
+
+### Provider (dependency injection)
+
+```typescript
+import { Provider } from '@frontmcp/sdk';
+
+export const DB_TOKEN = Symbol('DB');
+
+@Provider({ token: DB_TOKEN })
+export class DatabaseProvider {
+  provide() {
+    return new DatabaseClient({ url: process.env['DATABASE_URL'] });
+  }
+}
+
+// In a tool, access via this.get(DB_TOKEN):
+async execute(input) {
+  const db = this.get(DB_TOKEN);
+}
+```
+
+## Code Conventions
+
+- **TypeScript strict mode** — no `any` types without justification; prefer `unknown`
+- **Zod v4** for all input/output schema validation
+- **`@frontmcp/utils`** for crypto and file-system operations (never use `node:crypto` or `fs` directly)
+- **95%+ test coverage** required (statements, branches, functions, lines)
+- **`@frontmcp/testing`** for test harnesses (`createTestHarness`, `createToolTestHarness`)
+- **No non-null assertions** (`!`) — throw proper errors instead
+
+## Documentation
+
+This workspace includes a `.mcp.json` that configures the **frontmcp-docs** MCP server. AI coding agents can use the `SearchAgentFront` tool to search the full FrontMCP documentation at any time.

package/generators/workspace/files/README.md__tmpl__

@@ -0,0 +1,70 @@
+# <%= name %>
+
+A FrontMCP Nx monorepo — TypeScript-first framework for building production-grade MCP servers.
+
+## Quick Start
+
+```bash
+# Install dependencies
+<%= packageManager %> install
+
+# Start dev server (sample app)
+npx nx dev demo
+
+# Build all projects
+npx nx run-many -t build
+
+# Run all tests
+npx nx run-many -t test
+```
+
+## Project Structure
+
+```
+<%= name %>/
+  apps/     # MCP application definitions (@App decorator)
+  libs/     # Shared libraries (tools, resources, providers)
+  servers/  # Deployment shells (Express/Fastify adapters)
+```
+
+## Nx Generators
+
+Use generators to scaffold new code:
+
+| Generator | Command | Description |
+|-----------|---------|-------------|
+| app | `npx nx g @frontmcp/nx:app <name>` | MCP application |
+| lib | `npx nx g @frontmcp/nx:lib <name>` | Shared library |
+| server | `npx nx g @frontmcp/nx:server <name>` | Deployment shell |
+| tool | `npx nx g @frontmcp/nx:tool <Name> --project <lib>` | MCP tool with Zod schemas |
+| resource | `npx nx g @frontmcp/nx:resource <Name> --project <lib>` | MCP resource |
+| prompt | `npx nx g @frontmcp/nx:prompt <Name> --project <lib>` | MCP prompt |
+| provider | `npx nx g @frontmcp/nx:provider <Name> --project <lib>` | DI provider |
+
+See `CLAUDE.md` for the full list of generators and architecture patterns.
+
+## Development Commands
+
+```bash
+# Build a specific project
+npx nx build <project>
+
+# Test a specific project
+npx nx test <project>
+
+# Serve a project with watch
+npx nx dev <project>
+
+# Launch MCP Inspector
+npx nx inspector <project>
+
+# Run across all projects
+npx nx run-many -t build
+npx nx run-many -t test
+```
+
+## Learn More
+
+- [FrontMCP Documentation](https://docs.agentfront.dev)
+- [MCP Specification](https://modelcontextprotocol.io)
+- AI coding agents can use the `frontmcp-docs` MCP server configured in `.mcp.json`

package/generators/workspace/files/__dot__cursorrules__tmpl__

@@ -0,0 +1,3 @@
+Read CLAUDE.md for full project instructions, architecture patterns, and code conventions.
+Always use Nx generators (`npx nx g @frontmcp/nx:<generator>`) — never create files manually.
+Use the frontmcp-docs MCP server (configured in .mcp.json) to search FrontMCP documentation.

package/generators/workspace/files/__dot__gitignore__tmpl__

@@ -26,3 +26,6 @@ coverage/
 .env
 .env.local
 .env.*.local
+
+# Claude Code (user-specific settings)
+.claude/settings.local.json

package/generators/workspace/files/__dot__mcp.json__tmpl__

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "frontmcp-docs": {
+      "type": "url",
+      "url": "https://docs.agentfront.dev/mcp"
+    }
+  }
+}

package/generators/workspace/files/__dot__nvmrc__tmpl__

@@ -0,0 +1 @@
+24

package/generators/workspace/files/package.json__tmpl__

@@ -4,7 +4,7 @@
   "private": true,
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "workspaces": [
     "apps/*",

package/generators/workspace/workspace.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.workspaceGenerator = workspaceGenerator;
 const devkit_1 = require("@nx/devkit");
+const child_process_1 = require("child_process");
 const path_1 = require("path");
 const index_js_1 = require("./lib/index.js");
 const versions_js_1 = require("../../utils/versions.js");
@@ -35,13 +36,31 @@ async function workspaceGeneratorInternal(tree, schema) {
     }
     await (0, devkit_1.formatFiles)(tree);
     if (options.skipInstall) {
+        if (!options.skipGit) {
+            return () => {
+                initGitRepository(options.workspaceRoot);
+            };
+        }
         return () => {
             /* noop */
         };
     }
     return () => {
         (0, devkit_1.installPackagesTask)(tree);
+        if (!options.skipGit) {
+            initGitRepository(options.workspaceRoot);
+        }
     };
 }
+function initGitRepository(workspaceRoot) {
+    try {
+        (0, child_process_1.execSync)('git init', { cwd: workspaceRoot, stdio: 'ignore' });
+        (0, child_process_1.execSync)('git add -A', { cwd: workspaceRoot, stdio: 'ignore' });
+        (0, child_process_1.execSync)('git commit -m "Initial commit"', { cwd: workspaceRoot, stdio: 'ignore' });
+    }
+    catch {
+        // git may not be installed — silently skip
+    }
+}
 exports.default = workspaceGenerator;
 //# sourceMappingURL=workspace.js.map

package/generators/workspace/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../../src/generators/workspace/workspace.ts"],"names":[],"mappings":";;AAMA,gDAEC;AARD,uCAAgH;AAChH,+BAA4B;AAE5B,6CAAkD;AAClD,yDAA6D;AAEtD,KAAK,UAAU,kBAAkB,CAAC,IAAU,EAAE,MAAgC;IACnF,OAAO,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,0BAA0B,CAAC,IAAU,EAAE,MAAgC;IACpF,MAAM,OAAO,GAAG,IAAA,2BAAgB,EAAC,MAAM,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,IAAI,IAAA,gCAAkB,GAAE,EAAE,CAAC;IACnD,MAAM,SAAS,GAAG,QAAQ,CAAC;IAE3B,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAA,WAAI,EAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,EAAE;QACnE,GAAG,OAAO;QACV,eAAe;QACf,SAAS;QACT,IAAI,EAAE,EAAE;QACR,GAAG,EAAE,GAAG;KACT,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAEnE,0DAA0D;IAC1D,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QACvD,MAAM,YAAY,CAAC,IAAI,EAAE;YACvB,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC;YACtD,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;IAExB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,GAAG,EAAE;YACV,UAAU;QACZ,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,EAAE;QACV,IAAA,4BAAmB,EAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC;AAED,kBAAe,kBAAkB,CAAC","sourcesContent":["import { type Tree, formatFiles, generateFiles, installPackagesTask, type GeneratorCallback } from '@nx/devkit';\nimport { join } from 'path';\nimport type { WorkspaceGeneratorSchema } from './schema.js';\nimport { normalizeOptions } from './lib/index.js';\nimport { getFrontmcpVersion } from '../../utils/versions.js';\n\nexport async function workspaceGenerator(tree: Tree, schema: WorkspaceGeneratorSchema): Promise<GeneratorCallback> {\n  return workspaceGeneratorInternal(tree, schema);\n}\n\nasync function workspaceGeneratorInternal(tree: Tree, schema: WorkspaceGeneratorSchema): Promise<GeneratorCallback> {\n  const options = normalizeOptions(schema);\n  const frontmcpVersion = `~${getFrontmcpVersion()}`;\n  const nxVersion = '22.3.3';\n\n  generateFiles(tree, join(__dirname, 'files'), options.workspaceRoot, {\n    ...options,\n    frontmcpVersion,\n    nxVersion,\n    tmpl: '',\n    dot: '.',\n  });\n\n  // Create empty directories\n  tree.write(join(options.workspaceRoot, 'apps', '.gitkeep'), '');\n  tree.write(join(options.workspaceRoot, 'libs', '.gitkeep'), '');\n  tree.write(join(options.workspaceRoot, 'servers', '.gitkeep'), '');\n\n  // Compose with app generator when createSampleApp is true\n  if (options.createSampleApp) {\n    const { appGenerator } = await import('../app/app.js');\n    await appGenerator(tree, {\n      name: 'demo',\n      directory: join(options.workspaceRoot, 'apps', 'demo'),\n      tags: 'scope:apps',\n      skipFormat: true,\n    });\n  }\n\n  await formatFiles(tree);\n\n  if (options.skipInstall) {\n    return () => {\n      /* noop */\n    };\n  }\n\n  return () => {\n    installPackagesTask(tree);\n  };\n}\n\nexport default workspaceGenerator;\n"]}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../../src/generators/workspace/workspace.ts"],"names":[],"mappings":";;AAOA,gDAEC;AATD,uCAAgH;AAChH,iDAAyC;AACzC,+BAA4B;AAE5B,6CAAkD;AAClD,yDAA6D;AAEtD,KAAK,UAAU,kBAAkB,CAAC,IAAU,EAAE,MAAgC;IACnF,OAAO,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,0BAA0B,CAAC,IAAU,EAAE,MAAgC;IACpF,MAAM,OAAO,GAAG,IAAA,2BAAgB,EAAC,MAAM,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,IAAI,IAAA,gCAAkB,GAAE,EAAE,CAAC;IACnD,MAAM,SAAS,GAAG,QAAQ,CAAC;IAE3B,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAA,WAAI,EAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,EAAE;QACnE,GAAG,OAAO;QACV,eAAe;QACf,SAAS;QACT,IAAI,EAAE,EAAE;QACR,GAAG,EAAE,GAAG;KACT,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,CAAC,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;IAEnE,0DAA0D;IAC1D,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QACvD,MAAM,YAAY,CAAC,IAAI,EAAE;YACvB,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAA,WAAI,EAAC,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC;YACtD,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;IAExB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,OAAO,GAAG,EAAE;gBACV,iBAAiB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;YAC3C,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,EAAE;YACV,UAAU;QACZ,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,EAAE;QACV,IAAA,4BAAmB,EAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,iBAAiB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,aAAqB;IAC9C,IAAI,CAAC;QACH,IAAA,wBAAQ,EAAC,UAAU,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9D,IAAA,wBAAQ,EAAC,YAAY,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChE,IAAA,wBAAQ,EAAC,gCAAgC,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;AACH,CAAC;AAED,kBAAe,kBAAkB,CAAC","sourcesContent":["import { type Tree, formatFiles, generateFiles, installPackagesTask, type GeneratorCallback } from '@nx/devkit';\nimport { execSync } from 'child_process';\nimport { join } from 'path';\nimport type { WorkspaceGeneratorSchema } from './schema.js';\nimport { normalizeOptions } from './lib/index.js';\nimport { getFrontmcpVersion } from '../../utils/versions.js';\n\nexport async function workspaceGenerator(tree: Tree, schema: WorkspaceGeneratorSchema): Promise<GeneratorCallback> {\n  return workspaceGeneratorInternal(tree, schema);\n}\n\nasync function workspaceGeneratorInternal(tree: Tree, schema: WorkspaceGeneratorSchema): Promise<GeneratorCallback> {\n  const options = normalizeOptions(schema);\n  const frontmcpVersion = `~${getFrontmcpVersion()}`;\n  const nxVersion = '22.3.3';\n\n  generateFiles(tree, join(__dirname, 'files'), options.workspaceRoot, {\n    ...options,\n    frontmcpVersion,\n    nxVersion,\n    tmpl: '',\n    dot: '.',\n  });\n\n  // Create empty directories\n  tree.write(join(options.workspaceRoot, 'apps', '.gitkeep'), '');\n  tree.write(join(options.workspaceRoot, 'libs', '.gitkeep'), '');\n  tree.write(join(options.workspaceRoot, 'servers', '.gitkeep'), '');\n\n  // Compose with app generator when createSampleApp is true\n  if (options.createSampleApp) {\n    const { appGenerator } = await import('../app/app.js');\n    await appGenerator(tree, {\n      name: 'demo',\n      directory: join(options.workspaceRoot, 'apps', 'demo'),\n      tags: 'scope:apps',\n      skipFormat: true,\n    });\n  }\n\n  await formatFiles(tree);\n\n  if (options.skipInstall) {\n    if (!options.skipGit) {\n      return () => {\n        initGitRepository(options.workspaceRoot);\n      };\n    }\n    return () => {\n      /* noop */\n    };\n  }\n\n  return () => {\n    installPackagesTask(tree);\n    if (!options.skipGit) {\n      initGitRepository(options.workspaceRoot);\n    }\n  };\n}\n\nfunction initGitRepository(workspaceRoot: string): void {\n  try {\n    execSync('git init', { cwd: workspaceRoot, stdio: 'ignore' });\n    execSync('git add -A', { cwd: workspaceRoot, stdio: 'ignore' });\n    execSync('git commit -m \"Initial commit\"', { cwd: workspaceRoot, stdio: 'ignore' });\n  } catch {\n    // git may not be installed — silently skip\n  }\n}\n\nexport default workspaceGenerator;\n"]}