@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -0,0 +1,292 @@
+# Example: Weather API (Beginner)
+
+> Skills used: setup-project, create-tool, create-resource, setup-testing, deploy-to-node
+
+A complete beginner MCP server that exposes a weather lookup tool and a static resource listing supported cities. Demonstrates server setup, Zod input/output schemas, `this.fetch()` for HTTP calls, `this.fail()` for error handling, and both unit and E2E tests.
+
+---
+
+## Project Setup
+
+```jsonc
+// package.json
+{
+  "name": "weather-api",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "frontmcp build",
+    "start": "frontmcp start",
+    "test": "jest --coverage",
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+    "zod": "^3.23.0",
+  },
+  "devDependencies": {
+    "@frontmcp/testing": "^1.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0",
+  },
+}
+```
+
+---
+
+## Server Entry Point
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { WeatherApp } from './weather.app';
+
+@FrontMcp({
+  info: { name: 'weather-api', version: '1.0.0' },
+  apps: [WeatherApp],
+})
+export default class WeatherServer {}
+```
+
+---
+
+## App Registration
+
+```typescript
+// src/weather.app.ts
+import { App } from '@frontmcp/sdk';
+import { GetWeatherTool } from './tools/get-weather.tool';
+import { CitiesResource } from './resources/cities.resource';
+
+@App({
+  name: 'Weather',
+  description: 'Weather lookup tools and city data',
+  tools: [GetWeatherTool],
+  resources: [CitiesResource],
+})
+export class WeatherApp {}
+```
+
+---
+
+## Tool: Get Weather
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().min(1).describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+  },
+  outputSchema: {
+    temperature: z.number(),
+    condition: z.string(),
+    humidity: z.number(),
+    city: z.string(),
+  },
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
+
+    let response: Response;
+    try {
+      response = await this.fetch(url);
+    } catch (err) {
+      this.fail(new Error(`Weather API unreachable: ${String(err)}`));
+    }
+
+    if (!response.ok) {
+      this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
+    }
+
+    const data = await response.json();
+
+    return {
+      temperature: data.temp,
+      condition: data.condition,
+      humidity: data.humidity,
+      city: input.city,
+    };
+  }
+}
+```
+
+---
+
+## Resource: Supported Cities
+
+```typescript
+// src/resources/cities.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Berlin', 'Toronto', 'Mumbai'];
+
+@Resource({
+  uri: 'weather://cities',
+  name: 'Supported Cities',
+  description: 'List of cities with available weather data',
+  mimeType: 'application/json',
+})
+export class CitiesResource extends ResourceContext {
+  async read() {
+    return JSON.stringify(SUPPORTED_CITIES);
+  }
+}
+```
+
+---
+
+## Unit Test: GetWeatherTool
+
+```typescript
+// test/get-weather.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { GetWeatherTool } from '../src/tools/get-weather.tool';
+
+describe('GetWeatherTool', () => {
+  let tool: GetWeatherTool;
+
+  beforeEach(() => {
+    tool = new GetWeatherTool();
+  });
+
+  it('should return weather data for a valid city', async () => {
+    const mockResponse = {
+      ok: true,
+      json: async () => ({
+        temp: 22,
+        condition: 'Sunny',
+        humidity: 45,
+      }),
+    } as unknown as Response;
+
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    const result = await tool.execute({ city: 'London', units: 'celsius' });
+
+    expect(result).toEqual({
+      temperature: 22,
+      condition: 'Sunny',
+      humidity: 45,
+      city: 'London',
+    });
+    expect(ctx.fetch).toHaveBeenCalledWith(expect.stringContaining('city=London'));
+  });
+
+  it('should fail when city is empty (Zod validation)', () => {
+    const { z } = require('zod');
+    const schema = z.object({
+      city: z.string().min(1),
+      units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+    });
+
+    expect(() => schema.parse({ city: '' })).toThrow();
+  });
+
+  it('should fail when the weather API returns an error', async () => {
+    const mockResponse = {
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    } as unknown as Response;
+
+    const failFn = jest.fn((err: Error) => {
+      throw err;
+    });
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: failFn,
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    await expect(tool.execute({ city: 'Atlantis', units: 'celsius' })).rejects.toThrow(
+      'Weather API error: 404 Not Found',
+    );
+
+    expect(failFn).toHaveBeenCalled();
+  });
+});
+```
+
+---
+
+## E2E Test: Weather Server
+
+```typescript
+// test/weather.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Weather Server E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list tools including get_weather', async () => {
+    const { tools } = await client.listTools();
+
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContainTool('get_weather');
+  });
+
+  it('should call get_weather with a valid city', async () => {
+    const result = await client.callTool('get_weather', {
+      city: 'London',
+      units: 'celsius',
+    });
+
+    expect(result).toBeSuccessful();
+    expect(result.content[0].text).toBeDefined();
+
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed).toHaveProperty('temperature');
+    expect(parsed).toHaveProperty('condition');
+    expect(parsed).toHaveProperty('humidity');
+    expect(parsed).toHaveProperty('city', 'London');
+  });
+
+  it('should read the cities resource', async () => {
+    const { resources } = await client.listResources();
+    const citiesResource = resources.find((r) => r.uri === 'weather://cities');
+    expect(citiesResource).toBeDefined();
+
+    const result = await client.readResource('weather://cities');
+    const cities = JSON.parse(result.contents[0].text);
+
+    expect(Array.isArray(cities)).toBe(true);
+    expect(cities).toContain('London');
+    expect(cities).toContain('Tokyo');
+  });
+});
+```

package/catalog/frontmcp-production-readiness/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: frontmcp-production-readiness
+description: 'Pre-production audit and checklist for FrontMCP servers. Use before go-live to verify security hardening, performance checks, observability, monitoring, and health checks. Triggers: production ready, security audit, performance check, production checklist, hardening, go live.'
+tags: [production, security, performance, reliability, observability, audit, best-practices]
+category: production
+targets: [all]
+bundle: [recommended, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/production/overview
+---
+
+# FrontMCP Production Readiness Audit
+
+Comprehensive audit skill for preparing FrontMCP servers for production deployment. Reviews security, performance, reliability, observability, and deployment configuration.
+
+## When to Use This Skill
+
+### Must Use
+
+- Before deploying a FrontMCP server to production for the first time
+- After major feature additions or architectural changes
+- During security reviews or compliance audits
+- When troubleshooting production issues (performance, crashes, security incidents)
+
+### Recommended
+
+- As part of PR reviews for infrastructure-touching changes
+- Quarterly health checks on production deployments
+- When onboarding new team members to understand production requirements
+
+### Skip When
+
+- Building a prototype or proof-of-concept (focus on functionality first)
+- Running in development/local mode only
+- The server has no external exposure (purely internal MCP client)
+
+> **Decision:** Use this skill when preparing for or auditing a production deployment. Reference `security-checklist` or `performance-checklist` for deep dives into specific areas.
+
+## Scenario Routing Table
+
+| Scenario                             | Section / Reference         | Description                                                      |
+| ------------------------------------ | --------------------------- | ---------------------------------------------------------------- |
+| Full production audit before go-live | All sections below          | Walk through every checklist                                     |
+| Security-focused audit               | `security-checklist`        | Auth, CORS, input validation, secrets, rate limiting             |
+| Performance optimization             | `performance-checklist`     | Caching, connection pooling, response optimization, memory leaks |
+| Reliability and error handling       | Reliability section below   | Error handling, graceful shutdown, health checks, retries        |
+| Observability setup                  | Observability section below | Structured logging, metrics, error tracking                      |
+| Deployment configuration review      | Deployment section below    | Docker, env vars, CI/CD, scaling                                 |
+
+## Security Checklist
+
+### Authentication & Authorization
+
+- [ ] JWT_SECRET is set to a strong random value (not the default)
+- [ ] Authentication is enabled (`auth` config in `@FrontMcp` or `@frontmcp/auth`)
+- [ ] API keys/tokens are loaded from environment variables, never hardcoded
+- [ ] Session storage uses Redis (not in-memory) for multi-instance deployments
+- [ ] Session TTL is configured appropriately (not infinite)
+- [ ] Tool-level authorization is enforced where needed (ApprovalPlugin or custom)
+- [ ] OAuth redirect URIs are restricted to known domains
+
+### CORS Configuration
+
+- [ ] CORS is NOT permissive (don't allow all origins in production)
+- [ ] Specific allowed origins are listed: `cors: { origin: ['https://your-app.com'] }`
+- [ ] Credentials mode is only enabled if cookies/sessions are needed
+- [ ] Preflight cache (`maxAge`) is set to reduce OPTIONS requests
+
+### Input Validation
+
+- [ ] All tool inputs use Zod schemas (never trust raw input)
+- [ ] All tool outputs use `outputSchema` to prevent data leaks
+- [ ] Path parameters and query params are validated
+- [ ] File paths are sanitized to prevent directory traversal
+- [ ] SQL queries use parameterized statements (never string interpolation)
+
+### Secrets Management
+
+- [ ] No secrets in source code or git history
+- [ ] `.env` files are in `.gitignore`
+- [ ] Production secrets are managed via secret manager (AWS SSM, Vault, etc.)
+- [ ] API keys have minimum required permissions
+- [ ] Secrets are rotated on a schedule
+
+### Rate Limiting & Abuse Prevention
+
+- [ ] Rate limiting is configured for public-facing endpoints
+- [ ] Per-client/per-IP limits are set
+- [ ] Throttle configuration uses `@FrontMcp({ throttle: {...} })`
+- [ ] Large payload limits are set to prevent memory exhaustion
+
+### Dependency Security
+
+- [ ] `npm audit` or `yarn audit` shows no high/critical vulnerabilities
+- [ ] Dependencies are pinned or use tilde ranges (not `*` or `latest`)
+- [ ] No unused dependencies in package.json
+
+## Performance Checklist
+
+### Caching
+
+- [ ] CachePlugin is configured for read-heavy tools
+- [ ] Cache TTL is tuned per tool (not one-size-fits-all)
+- [ ] Cache uses Redis in production (not in-memory)
+- [ ] Cache bypass header is configured for debugging
+- [ ] Stale cache invalidation strategy is defined
+
+### Connection Management
+
+- [ ] Redis connection pooling is configured (not one connection per request)
+- [ ] Database connections use connection pools
+- [ ] HTTP client connections use keep-alive
+- [ ] Connection timeouts are set (don't hang indefinitely)
+
+### Response Optimization
+
+- [ ] Large responses are paginated or streamed
+- [ ] Tools return only necessary data (no over-fetching)
+- [ ] OpenAPI adapter responses are not unnecessarily large
+- [ ] Binary data uses proper encoding (base64 only when necessary)
+
+### Memory Management
+
+- [ ] No memory leaks from event listeners or unclosed connections
+- [ ] Large data processing uses streams instead of buffering
+- [ ] Provider lifecycle `dispose()` is implemented for cleanup
+- [ ] Session storage has TTL to prevent unbounded growth
+
+### Startup Performance
+
+- [ ] Server startup time is acceptable (< 5s for most apps)
+- [ ] Lazy-load expensive dependencies (ML models, large configs)
+- [ ] OpenAPI spec fetching uses caching and doesn't block startup
+
+## Reliability Checklist
+
+### Error Handling
+
+- [ ] All tools use `this.fail()` with specific MCP error classes
+- [ ] Unknown errors are caught and wrapped (never expose stack traces)
+- [ ] Error responses include MCP error codes for client handling
+- [ ] Async errors are properly caught (no unhandled promise rejections)
+
+### Graceful Shutdown
+
+- [ ] SIGTERM handler is configured for clean shutdown
+- [ ] In-flight requests complete before process exit
+- [ ] Redis/database connections are closed on shutdown
+- [ ] Health check returns unhealthy during shutdown drain
+
+### Health Checks
+
+- [ ] `/health` endpoint is implemented and monitored
+- [ ] Health check verifies downstream dependencies (Redis, databases)
+- [ ] Readiness probe is separate from liveness probe (K8s)
+- [ ] Health check doesn't perform expensive operations
+
+### Retry & Circuit Breaking
+
+- [ ] External API calls have retry logic with exponential backoff
+- [ ] Circuit breaker pattern for unreliable downstream services
+- [ ] Timeouts are set for all external calls
+- [ ] Job retries have maximum attempt limits
+
+## Observability Checklist
+
+### Structured Logging
+
+- [ ] Logs use structured format (JSON in production)
+- [ ] Log levels are appropriate (info for normal, error for failures)
+- [ ] Sensitive data is redacted from logs (tokens, passwords, PII)
+- [ ] Request/response logging includes correlation IDs
+- [ ] Log volume is manageable (not logging every request body)
+
+### Metrics
+
+- [ ] Request count and latency metrics are exposed
+- [ ] Error rate metrics are tracked
+- [ ] Tool execution duration is measured
+- [ ] Resource utilization (memory, CPU) is monitored
+
+### Error Tracking
+
+- [ ] Unhandled errors are captured and reported
+- [ ] Error tracking service is integrated (Sentry, Datadog, etc.)
+- [ ] Error alerts are configured for critical failures
+- [ ] Error context includes tool name, input summary, and user context
+
+## Deployment Checklist
+
+### Docker & Containers
+
+- [ ] Dockerfile uses multi-stage build (separate build and runtime stages)
+- [ ] Base image is minimal (node:slim, not full node image)
+- [ ] Non-root user is configured in the container
+- [ ] `.dockerignore` excludes dev files, node_modules, .git
+- [ ] Container health check is defined
+- [ ] Resource limits (memory, CPU) are set in deployment config
+
+### Environment Configuration
+
+- [ ] `NODE_ENV=production` is set
+- [ ] All required env vars are documented in `.env.example`
+- [ ] Env vars are validated at startup (fail fast on missing config)
+- [ ] Port binding uses `process.env.PORT` for platform compatibility
+- [ ] No dev dependencies are installed in production (`npm install --production`)
+
+### CI/CD Pipeline
+
+- [ ] Tests run on every PR (unit + E2E)
+- [ ] Build step produces optimized output (`frontmcp build`)
+- [ ] Docker image is built and pushed automatically
+- [ ] Deployment is automated with rollback capability
+- [ ] Database migrations run as separate step (not in server startup)
+
+### Scaling
+
+- [ ] Server is stateless (session state in Redis, not memory)
+- [ ] Multiple instances can run behind a load balancer
+- [ ] WebSocket/SSE connections are handled by sticky sessions or Redis pub/sub
+- [ ] Auto-scaling is configured based on CPU/memory/request metrics
+
+## Common Anti-Patterns
+
+| Anti-Pattern              | Why It's Bad                                 | Fix                                         |
+| ------------------------- | -------------------------------------------- | ------------------------------------------- |
+| Default JWT_SECRET        | Anyone can forge tokens                      | Set a strong random secret                  |
+| In-memory session store   | Lost on restart, not shared across instances | Use Redis                                   |
+| `cors: { origin: '*' }`   | Any website can call your server             | Restrict to known origins                   |
+| No output schema on tools | May leak internal data                       | Always define `outputSchema`                |
+| Synchronous file I/O      | Blocks event loop                            | Use async operations from `@frontmcp/utils` |
+| Hardcoded secrets         | Committed to git, visible in source          | Use environment variables                   |
+| No health check           | Can't detect unhealthy instances             | Implement `/health` endpoint                |
+| Unbounded caching         | Memory grows forever                         | Set TTL on all caches                       |
+
+## Verification Checklist
+
+After completing this audit:
+
+1. Run `frontmcp doctor` to check project configuration
+2. Run `frontmcp test` to ensure all tests pass
+3. Run `frontmcp build` to verify production build succeeds
+4. Deploy to staging and run E2E tests against it
+5. Review logs for any warnings or errors during startup
+6. Load test with expected production traffic patterns
+
+## Reference
+
+- [FrontMCP Production Guide](https://docs.agentfront.dev/frontmcp/production)
+- Related skills: `frontmcp-config`, `frontmcp-deployment`, `frontmcp-testing`

package/catalog/frontmcp-setup/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: frontmcp-setup
+description: "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'."
+tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
+category: setup
+targets: [all]
+bundle: [recommended, minimal, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/getting-started/quickstart
+---
+
+# FrontMCP Setup Router
+
+Entry point for project setup and scaffolding. This skill helps you find the right setup guide based on your project needs — from initial scaffolding to storage backends, project structure, and multi-app composition.
+
+## When to Use This Skill
+
+### Must Use
+
+- Starting a new FrontMCP project from scratch and need to choose between standalone vs Nx monorepo
+- Setting up storage backends (Redis, SQLite) for session or state management
+- Organizing an existing project and need canonical directory layout guidance
+
+### Recommended
+
+- Onboarding to the FrontMCP project structure and naming conventions
+- Setting up multi-app composition within a single server
+- Understanding the skills system and how to browse, install, and manage skills
+
+### Skip When
+
+- You need to build specific components like tools or resources (see `frontmcp-development`)
+- You need to configure transport, auth, or throttling (see `frontmcp-config`)
+- You need to deploy or build for a target platform (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill when you need to CREATE or ORGANIZE a project. Use other routers when you need to build, configure, deploy, or test.
+
+## Prerequisites
+
+- Node.js 24+ and npm/yarn installed
+- `frontmcp` CLI available globally (`npm install -g frontmcp`)
+
+## Steps
+
+1. Use the Scenario Routing Table below to find the right setup guide for your task
+2. Scaffold your project with `frontmcp create` (standalone) or `frontmcp create --nx` (monorepo)
+3. Configure storage and project structure per the relevant reference files
+4. Follow the Recommended Reading Order for a complete setup walkthrough
+
+## Scenario Routing Table
+
+| Scenario                                      | Reference                                    | Description                                                            |
+| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder, manual setup, deployment-specific config               |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules            |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                     |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers          |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands       |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                              |
+
+## Recommended Reading Order
+
+1. **`references/setup-project.md`** — Start here for any new project
+2. **`references/project-structure-standalone.md`** or **`references/project-structure-nx.md`** — Choose your layout
+3. **`references/setup-redis.md`** or **`references/setup-sqlite.md`** — Add storage if needed
+4. **`references/multi-app-composition.md`** — Scale to multiple apps (when needed)
+5. **`references/nx-workflow.md`** — Nx-specific build and CI commands (if using Nx)
+6. **`references/frontmcp-skills-usage.md`** — Learn the skills system
+
+## Cross-Cutting Patterns
+
+| Pattern        | Rule                                                                             |
+| -------------- | -------------------------------------------------------------------------------- |
+| Project type   | Standalone for single-app projects; Nx for multi-app or team projects            |
+| File naming    | `<name>.<type>.ts` (e.g., `fetch-weather.tool.ts`) everywhere                    |
+| Test naming    | `.spec.ts` extension (not `.test.ts`)                                            |
+| Entry point    | `main.ts` must `export default` the `@FrontMcp` class                            |
+| Storage choice | Redis for production/serverless; SQLite for local dev/CLI; memory for tests only |
+| App boundaries | Each `@App` is a self-contained module; shared logic goes in providers           |
+
+## Common Patterns
+
+| Pattern               | Correct                                         | Incorrect                                    | Why                                                               |
+| --------------------- | ----------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| Project scaffolding   | `frontmcp create` or `frontmcp create --nx`     | Manual setup from scratch                    | CLI sets up correct structure, dependencies, and config files     |
+| Entry point           | `export default class MyServer` in `main.ts`    | Named export or no default export            | FrontMCP loads the default export at startup                      |
+| Storage in production | Redis or platform-native (Vercel KV, DynamoDB)  | Memory store or SQLite                       | Memory is lost on restart; SQLite doesn't work on serverless      |
+| Multi-app composition | Separate `@App` classes composed in `@FrontMcp` | One giant `@App` with all components         | Separate apps enable independent testing and modular architecture |
+| File organization     | Feature folders for 10+ components              | Flat `tools/` directory with dozens of files | Feature folders make domain boundaries visible                    |
+
+## Verification Checklist
+
+### Project Structure
+
+- [ ] `main.ts` exists with `export default` of `@FrontMcp` class
+- [ ] At least one `@App` class registered in the server
+- [ ] Files follow `<name>.<type>.ts` naming convention
+- [ ] Test files use `.spec.ts` extension
+
+### Storage
+
+- [ ] Storage backend chosen and configured (Redis/SQLite/memory)
+- [ ] Connection string in environment variables, not hardcoded
+- [ ] Storage accessible from the server process
+
+### Build and Dev
+
+- [ ] `frontmcp dev` starts successfully with file watching
+- [ ] `frontmcp build --target <target>` completes without errors
+- [ ] Tests pass with `frontmcp test` or `nx test`
+
+## Troubleshooting
+
+| Problem                  | Cause                            | Solution                                                              |
+| ------------------------ | -------------------------------- | --------------------------------------------------------------------- |
+| `frontmcp create` fails  | Missing Node.js 24+ or npm/yarn  | Install Node.js 24+ and ensure npm/yarn is available                  |
+| Server fails to start    | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts`                       |
+| Redis connection refused | Redis not running or wrong URL   | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var    |
+| Nx generator not found   | `@frontmcp/nx` not installed     | Run `npm install -D @frontmcp/nx`                                     |
+| Skills not loading       | Skills placed in wrong directory | Catalog skills go in top-level `skills/`, app skills in `src/skills/` |
+
+## Reference
+
+- [Getting Started](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
+- Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`, `frontmcp-guides`