@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

@@ -0,0 +1,297 @@
+---
+name: example-weather-api
+description: Beginner MCP server with a weather lookup tool, static resource, Zod schemas, and E2E tests
+---
+
+# 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,98 @@
+---
+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
+
+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             |
+| 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
+
+- [FrontMCP Production Guide](https://docs.agentfront.dev/frontmcp/production)
+- Related skills: `frontmcp-config`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-setup`

package/catalog/frontmcp-production-readiness/references/common-checklist.md

@@ -0,0 +1,156 @@
+---
+name: common-checklist
+description: Security, performance, reliability, and observability checks for all deployment targets
+---
+
+# Common Production Readiness Checklist
+
+These checks apply to ALL deployment targets. Run them first, then proceed to your target-specific checklist.
+
+## Security
+
+### 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 or platform-native store (not in-memory) for multi-instance
+- [ ] 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
+
+- [ ] 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
+
+### Dependencies
+
+- [ ] `npm audit` shows no high/critical vulnerabilities
+- [ ] Dependencies are pinned or use tilde ranges (not `*` or `latest`)
+- [ ] No unused dependencies in package.json
+
+## Performance
+
+### Caching
+
+- [ ] CachePlugin is configured for read-heavy tools
+- [ ] Cache TTL is tuned per tool (not one-size-fits-all)
+- [ ] Stale cache invalidation strategy is defined
+
+### Response Optimization
+
+- [ ] Large responses are paginated or streamed
+- [ ] Tools return only necessary data (no over-fetching)
+- [ ] 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
+
+## Reliability
+
+### 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)
+
+### 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
+
+### 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
+
+### Monitoring
+
+- [ ] Request count and latency metrics are exposed
+- [ ] Error rate metrics are tracked
+- [ ] Tool execution duration is measured
+- [ ] Error tracking service is integrated (Sentry, Datadog, etc.)
+
+## Jobs & Workflows (if enabled)
+
+- [ ] Jobs Redis store is configured for production (`jobs: { enabled: true, store: { redis } }`)
+- [ ] Job retry config has reasonable `maxAttempts` and `maxBackoffMs`
+- [ ] Workflow timeout is set to prevent runaway workflows
+- [ ] Job execution times are monitored (long-running jobs need alerting)
+- [ ] Workflow step `continueOnError` is only used for non-critical steps
+
+## Skills HTTP Endpoints (if enabled)
+
+- [ ] Skills HTTP auth is configured (`skillsConfig.auth: 'api-key'` or `'bearer'`)
+- [ ] Skills caching is enabled for production (`skillsConfig.cache: { enabled: true }`)
+- [ ] Cache TTL is tuned for skill instruction freshness requirements
+- [ ] `/llm.txt` and `/skills` endpoints are tested for correct responses
+
+## ExtApps / Widgets (if enabled)
+
+- [ ] Host capabilities are reviewed — only enable what widgets need
+- [ ] `serverToolProxy` is disabled if widgets should not call MCP tools
+- [ ] Widget session validation is active (default with HTTP transport)
+- [ ] CSP headers are configured for hosted widget origins
+
+## SQLite (if used)
+
+- [ ] WAL mode is enabled for concurrent read/write performance
+- [ ] Database file path is writable and persistent (not ephemeral storage)
+- [ ] Backup strategy is defined (periodic file copy or WAL checkpoint)
+- [ ] Database size is monitored to prevent disk exhaustion
+
+## Documentation
+
+- [ ] README.md is up-to-date for the deployment target (see `frontmcp-setup` → `references/readme-guide.md`)
+- [ ] API documentation covers all tools and resources
+- [ ] Environment variables are documented in `.env.example`
+
+## Common Anti-Patterns
+
+| Anti-Pattern              | Fix                                         |
+| ------------------------- | ------------------------------------------- |
+| Default JWT_SECRET        | Set a strong random secret                  |
+| In-memory session store   | Use Redis or platform-native storage        |
+| `cors: { origin: '*' }`   | Restrict to known origins                   |
+| No output schema on tools | Always define `outputSchema`                |
+| Synchronous file I/O      | Use async operations from `@frontmcp/utils` |
+| Hardcoded secrets         | Use environment variables                   |
+| Unbounded caching         | Set TTL on all caches                       |

package/catalog/frontmcp-production-readiness/references/production-browser.md

@@ -0,0 +1,46 @@
+---
+name: production-browser
+description: Checklist for publishing FrontMCP as a browser-compatible SDK bundle
+---
+
+# Production Readiness: Browser SDK
+
+Target-specific checklist for publishing FrontMCP as a browser-compatible SDK.
+
+> Run the `common-checklist` first, then use this checklist for browser-specific items.
+
+## Build
+
+- [ ] `frontmcp build --target browser` produces a correct ESM/UMD bundle
+- [ ] Bundle size is acceptable (check with `npx bundlesize` or similar)
+- [ ] Tree-shaking works (no unnecessary code in final bundle)
+- [ ] Source maps are generated for debugging (but not shipped to production CDN)
+
+## Browser Compatibility
+
+- [ ] No Node.js-only APIs (`fs`, `path`, `child_process`, `net`, `crypto`)
+- [ ] All crypto uses `@frontmcp/utils` (wraps Web Crypto API)
+- [ ] All file operations removed or polyfilled
+- [ ] Fetch API used instead of Node http/https modules
+- [ ] Works in major browsers (Chrome, Firefox, Safari, Edge)
+
+## Security
+
+- [ ] No secrets bundled in the client-side code
+- [ ] API keys are NOT in the browser bundle (use server-side proxy)
+- [ ] CORS is configured on the server to accept browser origins
+- [ ] Content Security Policy (CSP) headers are compatible
+
+## Distribution
+
+- [ ] Package exports both ESM and CJS: `"module"` and `"main"` in package.json
+- [ ] `"browser"` field in package.json points to the browser build
+- [ ] TypeScript declarations (`.d.ts`) are included
+- [ ] CDN-friendly: works via `<script>` tag or `import` from CDN
+
+## Performance
+
+- [ ] Bundle is minified for production
+- [ ] Code splitting is used for large optional features
+- [ ] No synchronous operations that block the main thread
+- [ ] WebSocket/SSE connections handle reconnection gracefully

package/catalog/frontmcp-production-readiness/references/production-cli-binary.md

@@ -0,0 +1,62 @@
+---
+name: production-cli-binary
+description: Checklist for publishing FrontMCP as a one-shot CLI binary with stdin/stdout transport
+---
+
+# Production Readiness: CLI Binary (One-Shot Execution)
+
+Checklist for publishing FrontMCP as a one-shot CLI binary — runs a command, processes input, exits. Not a long-running server.
+
+> Run the `common-checklist` first, then use this checklist for binary-specific items.
+
+## Build
+
+- [ ] `frontmcp build --target cli` produces a working binary
+- [ ] Binary starts and responds to `--help` within 500ms
+- [ ] `package.json` has correct `bin` field pointing to the built output
+- [ ] Shebang line is correct: `#!/usr/bin/env node`
+- [ ] Binary file has execute permissions (`chmod +x`)
+
+## Startup Performance
+
+- [ ] Cold start time is under 1 second
+- [ ] No heavy initialization at module scope (lazy-load dependencies)
+- [ ] No network calls during startup (model downloads, API fetches)
+- [ ] No async initialization that blocks first output
+
+## stdin/stdout Transport
+
+- [ ] MCP stdio transport works: reads JSON-RPC from stdin, writes to stdout
+- [ ] stderr is used for logging (not stdout — that's the MCP channel)
+- [ ] Handles EOF on stdin gracefully (clean exit)
+- [ ] Handles broken pipe on stdout gracefully (no crash)
+
+## Exit Behavior
+
+- [ ] Exit code 0 on success
+- [ ] Exit code 1 on user error (bad input, missing args)
+- [ ] Exit code 2 on internal error
+- [ ] No hanging — process exits promptly after work is done
+- [ ] All async operations complete before exit (no dangling promises)
+
+## npm Distribution
+
+- [ ] Package name is available on npm
+- [ ] `package.json` has `name`, `version`, `description`, `keywords`, `license`
+- [ ] `files` field includes only: `dist/`, `README.md`, `LICENSE`
+- [ ] `.npmignore` or `files` excludes: `src/`, `e2e/`, `.env`, `coverage/`
+- [ ] `README.md` has: `npm install -g <name>` and usage examples
+
+## Error Messages
+
+- [ ] User errors show helpful messages (not stack traces)
+- [ ] `--version` flag works correctly
+- [ ] Unknown flags produce a helpful error
+- [ ] Missing required arguments show usage hint
+
+## Security
+
+- [ ] No secrets bundled in the binary
+- [ ] No secrets logged to stderr
+- [ ] No hardcoded paths (use `os.homedir()`, `os.tmpdir()`)
+- [ ] No writes to unexpected locations