@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-observability/references/vendor-integrations.md

@@ -0,0 +1,164 @@
+---
+name: vendor-integrations
+description: 'Connect FrontMCP observability to Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend.'
+tags: [vendor, coralogix, datadog, logz, grafana, otlp, integration]
+---
+
+# Vendor Integrations
+
+Connect FrontMCP traces and logs to any monitoring platform. All major vendors accept OTLP — the standard OpenTelemetry protocol.
+
+## OTLP — Universal Standard
+
+The `otlp` sink type sends structured logs (with trace correlation) to any OTLP-compatible endpoint:
+
+```typescript
+@FrontMcp({
+  observability: {
+    tracing: true,
+    logging: {
+      sinks: [{
+        type: 'otlp',
+        endpoint: 'http://your-collector:4318',
+        headers: { Authorization: 'Bearer YOUR_TOKEN' },
+      }],
+    },
+  },
+})
+```
+
+## Vendor-Specific Configuration
+
+### Coralogix
+
+```typescript
+observability: {
+  tracing: true,
+  logging: {
+    sinks: [{
+      type: 'otlp',
+      endpoint: 'https://ingress.coralogix.com:443',    // EU: eu2.coralogix.com
+      headers: { Authorization: 'Bearer CX_PRIVATE_KEY' },
+      serviceName: 'my-mcp-server',
+    }],
+  },
+}
+```
+
+For traces, configure `setupOTel()` with the same endpoint:
+
+```typescript
+import { setupOTel } from '@frontmcp/observability';
+
+setupOTel({
+  serviceName: 'my-mcp-server',
+  exporter: 'otlp',
+  endpoint: 'https://ingress.coralogix.com:443',
+});
+```
+
+### Datadog
+
+```typescript
+observability: {
+  tracing: true,
+  logging: {
+    sinks: [{
+      type: 'otlp',
+      endpoint: 'https://http-intake.logs.datadoghq.com',  // EU: .datadoghq.eu
+      headers: { 'DD-API-KEY': 'YOUR_DATADOG_API_KEY' },
+    }],
+  },
+}
+```
+
+### Logz.io
+
+```typescript
+observability: {
+  tracing: true,
+  logging: {
+    sinks: [{
+      type: 'otlp',
+      endpoint: 'https://otlp-listener.logz.io:8071',
+      headers: { Authorization: 'Bearer YOUR_SHIPPING_TOKEN' },
+    }],
+  },
+}
+```
+
+### Grafana Cloud
+
+```typescript
+observability: {
+  tracing: true,
+  logging: {
+    sinks: [{
+      type: 'otlp',
+      endpoint: 'https://otlp-gateway-prod-us-east-0.grafana.net/otlp',
+      headers: {
+        Authorization: 'Basic ' + Buffer.from(`${instanceId}:${apiKey}`).toString('base64'),
+      },
+    }],
+  },
+}
+```
+
+### Local Collector (Development)
+
+```typescript
+observability: {
+  tracing: true,
+  logging: {
+    sinks: [{ type: 'otlp', endpoint: 'http://localhost:4318' }],
+  },
+}
+```
+
+## Environment Variable Configuration
+
+All vendors can be configured via environment variables — no code changes:
+
+```bash
+OTEL_SERVICE_NAME=my-mcp-server
+OTEL_EXPORTER_OTLP_ENDPOINT=https://ingress.coralogix.com:443
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer CX_KEY"
+```
+
+## Winston / Pino (Existing Logging)
+
+If you already have a winston or pino setup routing logs to a vendor:
+
+```typescript
+// Use your existing logger — it already sends to your vendor
+observability: {
+  logging: {
+    sinks: [{ type: 'winston', logger: existingWinstonLogger }],
+  },
+}
+```
+
+Structured log entries (with `trace_id`) are forwarded to your logger, which sends them to wherever it's configured.
+
+## OTLP Sink Options
+
+| Option            | Type                     | Default                                                  | Description                                 |
+| ----------------- | ------------------------ | -------------------------------------------------------- | ------------------------------------------- |
+| `endpoint`        | `string`                 | `OTEL_EXPORTER_OTLP_ENDPOINT` or `http://localhost:4318` | OTLP endpoint (path `/v1/logs` is appended) |
+| `headers`         | `Record<string, string>` | `{}`                                                     | Auth headers                                |
+| `batchSize`       | `number`                 | `100`                                                    | Max entries before auto-flush               |
+| `flushIntervalMs` | `number`                 | `5000`                                                   | Flush timer interval                        |
+| `serviceName`     | `string`                 | `OTEL_SERVICE_NAME` or `frontmcp-server`                 | Service name in resource attributes         |
+
+## Examples
+
+| Example                                                                 | Level        | Description                                                                                                               |
+| ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| [`coralogix-setup`](../examples/vendor-integrations/coralogix-setup.md) | Intermediate | Send both traces and structured logs to Coralogix. Logs include trace_id so Coralogix links them to traces automatically. |
+
+> See all examples in [`examples/vendor-integrations/`](../examples/vendor-integrations/)
+
+## Reference
+
+- [Observability Guide](https://docs.agentfront.dev/frontmcp/guides/observability)
+- Related skills: `frontmcp-deployment`, `frontmcp-production-readiness`

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

@@ -0,0 +1,99 @@
+---
+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/deployment/production-build
+---
+
+# FrontMCP Production Readiness Audit
+
+Router for production readiness checklists. Start with the common checklist (security, performance, reliability, observability), then follow the target-specific checklist for your deployment environment.
+
+## 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
+
+### Recommended
+
+- As part of PR reviews for infrastructure-touching changes
+- Quarterly health checks on production deployments
+- When switching deployment targets
+
+### Skip When
+
+- Building a prototype or proof-of-concept
+- Running in development/local mode only
+
+> **Decision:** Use this skill when preparing for production. Start with `common-checklist`, then pick your deployment target.
+
+## Step 1: Detect Deployment Target
+
+Check the project to determine the deployment target:
+
+1. Look at `package.json` scripts for `frontmcp build --target <target>`
+2. Check for target-specific files: `ci/Dockerfile` (node), `vercel.json` (vercel), `wrangler.toml` (cloudflare), `ci/template.yaml` (lambda)
+3. Check if the build target is `cli` or `browser` in the build config
+4. If unclear, ask the user which environment they're deploying to
+
+## Step 2: Run Common Checklist
+
+Always start with the common checklist — it covers security, performance, reliability, and observability that apply to every target.
+
+## Step 3: Run Target-Specific Checklist
+
+After the common checklist, run the checklist for your deployment target.
+
+## Scenario Routing Table
+
+| Scenario                                                 | Reference                                  | Description                                         |
+| -------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------- |
+| Common security, performance, reliability, observability | `references/common-checklist.md`           | Applies to ALL targets — run this first             |
+| Health & readiness endpoints (/healthz, /readyz)         | `references/health-readiness-endpoints.md` | Custom probes, Kubernetes, runtime-aware readiness  |
+| Standalone Node.js server with Docker                    | `references/production-node-server.md`     | Docker, health checks, Redis, scaling, CI/CD        |
+| Node.js SDK / direct client (npm package)                | `references/production-node-sdk.md`        | create()/connect() API, disposal, npm publishing    |
+| Vercel serverless / edge                                 | `references/production-vercel.md`          | Vercel config, edge runtime, cold starts, Vercel KV |
+| Cloudflare Workers                                       | `references/production-cloudflare.md`      | Wrangler, Workers runtime, KV, Durable Objects      |
+| AWS Lambda                                               | `references/production-lambda.md`          | SAM template, cold starts, DynamoDB, API Gateway    |
+| CLI daemon (local MCP server)                            | `references/production-cli-daemon.md`      | Process manager, socket files, service registration |
+| CLI binary (one-shot execution)                          | `references/production-cli-binary.md`      | Fast startup, stdio transport, exit codes, npm bin  |
+| Browser SDK                                              | `references/production-browser.md`         | Bundle size, browser APIs, CSP, CDN distribution    |
+
+## Quick Reference: Target Detection
+
+| File / Signal Found                                   | Target                                          |
+| ----------------------------------------------------- | ----------------------------------------------- |
+| `ci/Dockerfile` or `ci/docker-compose.yml`            | Standalone server → `production-node-server.md` |
+| `serve: false` or `create()` API usage                | SDK / direct client → `production-node-sdk.md`  |
+| `vercel.json`                                         | Vercel → `production-vercel.md`                 |
+| `wrangler.toml`                                       | Cloudflare → `production-cloudflare.md`         |
+| `ci/template.yaml`                                    | Lambda → `production-lambda.md`                 |
+| `frontmcp start` / `socket` / `service install` usage | CLI daemon → `production-cli-daemon.md`         |
+| `build --target cli` + `bin` in package.json          | CLI binary → `production-cli-binary.md`         |
+| `build --target browser` in scripts                   | Browser → `production-browser.md`               |
+
+## Verification Checklist
+
+After completing both common and target-specific checklists:
+
+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. Update README for the deployment target (see `frontmcp-setup` → `references/readme-guide.md`)
+
+## Reference
+
+- [Production Build](https://docs.agentfront.dev/frontmcp/deployment/production-build)
+- Related skills: `frontmcp-config`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-setup`, `frontmcp-observability`

package/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md

@@ -0,0 +1,102 @@
+---
+name: caching-and-performance
+reference: common-checklist
+level: advanced
+description: 'Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.'
+tags: [production, redis, cache, session, performance, checklist]
+features:
+  - 'Configuring per-tool cache TTL instead of a single global value'
+  - 'Using Redis-backed cache for multi-instance consistency'
+  - 'Setting session TTL to prevent unbounded storage growth'
+  - 'Implementing `onDestroy()` in providers for proper connection cleanup'
+  - 'Using connection pool limits and timeouts to prevent resource exhaustion'
+---
+
+# Caching and Performance Configuration
+
+Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { CachePlugin } from '@frontmcp/plugins';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'perf-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    new CachePlugin({
+      // Per-tool TTL tuning (not one-size-fits-all)
+      ttl: {
+        get_weather: 300_000, // 5 minutes — data changes slowly
+        list_tasks: 10_000, // 10 seconds — data changes frequently
+      },
+      defaultTtl: 60_000, // 1 minute default
+    }),
+  ],
+
+  // Redis for multi-instance cache consistency
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+
+  // Session TTL to prevent unbounded growth
+  session: {
+    ttl: 3600_000, // 1 hour
+  },
+})
+export default class PerfServer {}
+```
+
+```typescript
+// src/providers/db-connection.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const DB_POOL = Symbol('DbPool');
+
+@Provider({ token: DB_POOL, scope: ProviderScope.GLOBAL })
+export class DbConnectionProvider {
+  private pool!: { query: Function; end: Function };
+
+  async onInit(): Promise<void> {
+    // Connection pool with limits — prevents resource exhaustion
+    this.pool = await this.createPool({
+      host: process.env.DB_HOST,
+      max: 20, // Maximum connections
+      idleTimeoutMs: 30_000, // Close idle connections after 30s
+      connectionTimeoutMs: 5_000, // Don't hang on connection attempts
+    });
+  }
+
+  async query(sql: string, params: unknown[]): Promise<unknown> {
+    return this.pool.query(sql, params); // Parameterized — no SQL injection
+  }
+
+  async onDestroy(): Promise<void> {
+    // Clean up on shutdown — prevents connection leaks
+    await this.pool.end();
+  }
+
+  private async createPool(config: Record<string, unknown>): Promise<{ query: Function; end: Function }> {
+    // Replace with your database driver (e.g., pg, mysql2)
+    throw new Error('Implement with your database driver');
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring per-tool cache TTL instead of a single global value
+- Using Redis-backed cache for multi-instance consistency
+- Setting session TTL to prevent unbounded storage growth
+- Implementing `onDestroy()` in providers for proper connection cleanup
+- Using connection pool limits and timeouts to prevent resource exhaustion
+
+## Related
+
+- See `common-checklist` for the full performance and memory management checklist

package/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md

@@ -0,0 +1,104 @@
+---
+name: observability-setup
+reference: common-checklist
+level: intermediate
+description: 'Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.'
+tags: [production, observability, checklist, setup]
+features:
+  - 'Using `this.mark()` to annotate execution phases for tracing'
+  - 'Using `this.fail()` for business-logic errors without exposing internals'
+  - 'Setting timeouts on all external calls via `AbortSignal.timeout()`'
+  - 'Implementing health check providers that verify downstream dependencies'
+---
+
+# Observability and Error Handling Setup
+
+Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.
+
+## Code
+
+```typescript
+// src/tools/monitored-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'monitored_operation',
+  description: 'A tool with proper error handling and observability markers',
+  inputSchema: {
+    operationId: z.string().min(1).describe('Operation identifier'),
+  },
+  outputSchema: {
+    status: z.string(),
+    operationId: z.string(),
+  },
+})
+export class MonitoredOperationTool extends ToolContext {
+  async execute(input: { operationId: string }) {
+    // Mark execution phases for tracing and duration metrics
+    this.mark('validation');
+    // ... validate business rules ...
+
+    this.mark('processing');
+    const result = await this.processOperation(input.operationId);
+
+    if (!result) {
+      // Use this.fail() with specific errors — never expose stack traces
+      this.fail(new Error(`Operation not found: ${input.operationId}`));
+    }
+
+    // Report progress for long-running operations
+    await this.respondProgress(1, 1);
+
+    return { status: 'completed', operationId: input.operationId };
+  }
+
+  private async processOperation(id: string): Promise<boolean> {
+    // External call with timeout — always set timeouts for external services
+    const response = await this.fetch(`https://api.example.com/operations/${id}`, {
+      signal: AbortSignal.timeout(5000), // 5 second timeout
+    });
+    return response.ok;
+  }
+}
+```
+
+```typescript
+// src/providers/health-check.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const HEALTH_CHECK = Symbol('HealthCheck');
+
+@Provider({ token: HEALTH_CHECK, scope: ProviderScope.GLOBAL })
+export class HealthCheckProvider {
+  async checkRedis(): Promise<boolean> {
+    // Verify downstream dependency is reachable
+    try {
+      // ... ping Redis ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async checkDatabase(): Promise<boolean> {
+    try {
+      // ... run a lightweight query ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.mark()` to annotate execution phases for tracing
+- Using `this.fail()` for business-logic errors without exposing internals
+- Setting timeouts on all external calls via `AbortSignal.timeout()`
+- Implementing health check providers that verify downstream dependencies
+
+## Related
+
+- See `common-checklist` for the full observability and monitoring checklist

package/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md

@@ -0,0 +1,95 @@
+---
+name: security-hardening
+reference: common-checklist
+level: basic
+description: 'Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.'
+tags: [production, redis, session, security, throttle, checklist]
+features:
+  - "Restricting CORS origins to known domains instead of using `'*'`"
+  - 'Configuring rate limiting via the `throttle` option'
+  - 'Using Redis for session storage in multi-instance deployments'
+  - 'Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks'
+---
+
+# Security Hardening Configuration
+
+Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'secure-server', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Authentication: use remote OAuth provider
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env.AUTH_CLIENT_ID!,
+  },
+
+  // CORS: restrict to known origins (never use '*' in production)
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    maxAge: 86400, // Cache preflight for 24 hours
+  },
+
+  // Rate limiting: prevent abuse
+  throttle: {
+    windowMs: 60_000, // 1 minute window
+    max: 100, // 100 requests per window per client
+  },
+
+  // Session storage: use Redis (not in-memory) for multi-instance
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+})
+export default class SecureServer {}
+```
+
+```typescript
+// src/tools/safe-query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'safe_query',
+  description: 'Query data with validated and sanitized input',
+  inputSchema: {
+    query: z.string().min(1).max(500).describe('Search query'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(z.object({ id: z.string(), title: z.string() })),
+    total: z.number(),
+  },
+})
+export class SafeQueryTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    // Zod already validated input — safe to use
+    // outputSchema prevents accidental data leaks
+    return { results: [], total: 0 };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Restricting CORS origins to known domains instead of using `'*'`
+- Configuring rate limiting via the `throttle` option
+- Using Redis for session storage in multi-instance deployments
+- Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks
+
+## Related
+
+- See `common-checklist` for the full security, performance, and reliability checklist

package/catalog/frontmcp-production-readiness/examples/health-readiness-endpoints/basic-health-setup.md

@@ -0,0 +1,81 @@
+---
+name: basic-health-setup
+reference: health-readiness-endpoints
+level: basic
+description: 'Default health endpoints with Redis session store, showing /healthz and /readyz responses.'
+tags: [production, health, readiness, redis, kubernetes, docker]
+features:
+  - 'Zero-config /healthz and /readyz endpoints enabled by default'
+  - 'Auto-discovered session-store probe via Redis persistence'
+  - 'Catalog hash for config drift detection across instances'
+  - 'Docker HEALTHCHECK directive using /healthz'
+---
+
+# Basic Health Setup
+
+Default health endpoints with Redis session store, showing /healthz and /readyz responses.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './apps/my-app';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  http: { port: 3001 },
+  redis: { host: 'localhost', port: 6379 },
+  transport: {
+    persistence: {}, // auto-uses global redis
+  },
+  // health endpoints are enabled by default:
+  // GET /healthz  -> { status: 'ok', server: {...}, runtime: {...}, uptime: ... }
+  // GET /readyz   -> { status: 'ready', catalog: {...}, probes: { 'session-store': {...} } }
+  // GET /health   -> legacy alias for /healthz
+})
+export default class Server {}
+```
+
+```dockerfile
+# ci/Dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY dist/ ./dist/
+COPY package.json ./
+RUN npm ci --production
+EXPOSE 3001
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3001/healthz || exit 1
+
+CMD ["node", "dist/main.js"]
+```
+
+Test the endpoints:
+
+```bash
+# Liveness probe
+curl http://localhost:3001/healthz
+# {"status":"ok","server":{"name":"my-server","version":"1.0.0"},"runtime":{"platform":"linux","runtime":"node","deployment":"standalone","env":"production"},"uptime":42.5}
+
+# Readiness probe (includes auto-discovered session-store probe)
+curl http://localhost:3001/readyz
+# {"status":"ready","totalLatencyMs":15,"catalog":{"toolsHash":"a1b2c3...","toolCount":5,"resourceCount":2,"promptCount":1,"skillCount":0,"agentCount":0},"probes":{"session-store":{"status":"healthy","latencyMs":3}}}
+
+# Legacy endpoint (alias for /healthz)
+curl http://localhost:3001/health
+# same as /healthz
+```
+
+## What This Demonstrates
+
+- Zero-config /healthz and /readyz endpoints enabled by default
+- Auto-discovered session-store probe via Redis persistence
+- Catalog hash for config drift detection across instances
+- Docker HEALTHCHECK directive using /healthz
+
+## Related
+
+- See `health-readiness-endpoints` for custom probes and configuration options