@frontmcp/skills 1.2.0 → 1.3.0

package/catalog/frontmcp-observability/examples/metrics-endpoint/enable-metrics-endpoint.md

@@ -0,0 +1,77 @@
+---
+name: enable-metrics-endpoint
+reference: metrics-endpoint
+level: basic
+description: 'Turn on the /metrics endpoint with defaults and scrape it with curl.'
+tags: [observability, metrics, prometheus]
+features:
+  - 'Setting `metrics: { enabled: true }` on `@FrontMcp` to register `GET /metrics`'
+  - 'Verifying the Prometheus text-exposition response with `curl`'
+  - 'Reading process metrics + framework counters from a single scrape'
+---
+
+# Enable the /metrics endpoint
+
+Turn on the /metrics endpoint with defaults and scrape it with curl.
+
+## Code
+
+```typescript
+// src/main.ts
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo the input back',
+  inputSchema: { message: z.string() },
+  outputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext {
+  async execute(input: { message: string }): Promise<{ message: string }> {
+    return { message: input.message };
+  }
+}
+
+@App({ name: 'main', tools: [EchoTool] })
+class MainApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MainApp],
+  // Off by default — turn it on explicitly.
+  metrics: { enabled: true },
+})
+export default class Server {}
+```
+
+```bash
+# In a terminal:
+$ frontmcp dev
+[dev] listening on port 3000
+
+# In a second terminal:
+$ curl -s http://localhost:3000/metrics | head -20
+# HELP frontmcp_process_resident_memory_bytes Resident memory size in bytes
+# TYPE frontmcp_process_resident_memory_bytes gauge
+frontmcp_process_resident_memory_bytes 50331648
+# HELP frontmcp_process_uptime_seconds Time since process start in seconds
+# TYPE frontmcp_process_uptime_seconds gauge
+frontmcp_process_uptime_seconds 14
+# HELP frontmcp_process_cpu_seconds_total CPU time consumed since collector start, by mode (seconds)
+# TYPE frontmcp_process_cpu_seconds_total counter
+frontmcp_process_cpu_seconds_total{mode="user"} 0.123
+frontmcp_process_cpu_seconds_total{mode="system"} 0.045
+
+$ curl -sI http://localhost:3000/metrics | grep -i content-type
+content-type: text/plain; version=0.0.4; charset=utf-8
+```
+
+## What This Demonstrates
+
+- Setting `metrics: { enabled: true }` on `@FrontMcp` to register `GET /metrics`
+- Verifying the Prometheus text-exposition response with `curl`
+- Reading process metrics + framework counters from a single scrape
+
+## Related
+
+- See `metrics-endpoint` for full configuration (auth, format, include filter, custom counters via `createCounter()`)

package/catalog/frontmcp-observability/references/metrics-endpoint.md

@@ -0,0 +1,161 @@
+---
+name: metrics-endpoint
+description: Configure the off-by-default /metrics endpoint that exposes process metrics and framework counters in Prometheus text format
+---
+
+# /metrics Endpoint (issue #397)
+
+Expose process metrics (CPU, RSS, heap, event-loop lag) and every framework counter (`frontmcp_skills_*_total`, plus any counter emitted via `createCounter()`) as a Prometheus scrape endpoint on the same HTTP listener as `/healthz`. The endpoint is **OFF by default** — turn it on with `metrics: { enabled: true }`.
+
+## When to use
+
+- Cluster operators want a `/metrics` URL for Prometheus / Grafana Agent / OpenTelemetry Collector to scrape.
+- Kubernetes HPA / Vercel autoscaling needs a pull endpoint instead of an OTel push pipeline.
+- On-call engineers need `curl :PORT/metrics | grep event_loop` without installing cluster-side tooling first.
+- The host wants both push (via OTel `MeterProvider`) and pull (this endpoint) — they read from the same in-memory counter store, so values stay consistent.
+
+## Enable with defaults
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  metrics: { enabled: true },
+})
+class Server {}
+```
+
+Then scrape: `curl http://localhost:3001/metrics` — Content-Type is the canonical Prometheus `text/plain; version=0.0.4; charset=utf-8`.
+
+## Configuration
+
+```typescript
+@FrontMcp({
+  metrics: {
+    enabled: true,                       // default: false
+    path: '/metrics',                    // default: '/metrics'
+    format: 'prometheus',                // 'prometheus' | 'json'
+    auth: 'public',                      // 'public' | 'token' | { token: string }
+    tokenEnv: 'FRONTMCP_METRICS_TOKEN',  // env var read at startup when auth: 'token'
+    include: ['process', 'skills'],      // optional category filter
+    process: {
+      eventLoopLag: true,                // mean + p99 event-loop lag gauge
+      fdCount: true,                     // Linux /proc/self/fd count
+      activeHandles: true,               // libuv handle / request counts
+    },
+  },
+})
+```
+
+## What gets emitted
+
+| Category           | Examples                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Process gauges     | `frontmcp_process_resident_memory_bytes`, `frontmcp_process_heap_bytes`, `frontmcp_process_uptime_seconds`, `frontmcp_process_cpu_seconds_total{mode}`          |
+| Node.js gauges     | `frontmcp_nodejs_eventloop_lag_seconds{quantile}`, `frontmcp_nodejs_active_handles`, `frontmcp_nodejs_active_requests`, `frontmcp_nodejs_open_fds` (Linux only) |
+| Framework counters | `frontmcp_skills_bundle_pulls_total`, `frontmcp_skills_signature_*_total`, `frontmcp_skills_replay_*_total`, `frontmcp_skills_audit_*_total`                    |
+| Custom counters    | Anything emitted via `createCounter('my_total').inc()` from `@frontmcp/observability`                                                                           |
+
+## Token auth
+
+```typescript
+metrics: {
+  enabled: true,
+  auth: 'token',
+  tokenEnv: 'FRONTMCP_METRICS_TOKEN',
+}
+```
+
+Fails fast at startup with `MetricsTokenNotConfiguredError` when the env var is unset — a token-gated endpoint never silently downgrades to public.
+
+| Request                           | Status |
+| --------------------------------- | ------ |
+| no `Authorization` header         | 401    |
+| `Authorization: Bearer <wrong>`   | 403    |
+| `Authorization: Bearer <correct>` | 200    |
+
+## Off-by-default rationale
+
+Process metrics, framework counter names, and tool vocabularies can hint at deployment scale and feature usage (e.g. `frontmcp_skills_signature_failures_total` reveals a signing infra exists). Recommendations:
+
+- **Internet-exposed deployments**: use `auth: 'token'` or terminate at a sidecar/ingress with a network ACL.
+- **Cluster-local deployments**: `auth: 'public'` matches the Prometheus / Kubernetes convention.
+
+## Add custom counters
+
+```typescript
+import { createCounter } from '@frontmcp/observability';
+
+const cacheHits = createCounter('my_cache_hits_total', 'Cache hits by tier');
+
+// In a tool / provider:
+cacheHits.inc(1, { tier: 'l1' });
+```
+
+The next scrape will include:
+
+```text
+# TYPE my_cache_hits_total counter
+my_cache_hits_total{tier="l1"} 1
+```
+
+Keep label values bounded (status codes, enum members, tool names) — unbounded values blow up the timeseries count.
+
+## Path conflict guard
+
+`metrics.path` MUST NOT collide with MCP transport paths (`/mcp`, `/sse`, `/messages`). The service constructor throws `MetricsPathConflictError` at startup if it detects an overlap.
+
+## Common Patterns
+
+| Pattern           | Correct                                                                         | Incorrect                                                     | Why                                                                                                           |
+| ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Enable endpoint   | `metrics: { enabled: true }`                                                    | Omit `metrics:` and hope it's on                              | The endpoint is opt-in; default is OFF for security                                                           |
+| Internet exposure | `metrics: { enabled: true, auth: 'token', tokenEnv: 'FRONTMCP_METRICS_TOKEN' }` | `metrics: { enabled: true, auth: 'public' }` on a public host | `auth: 'public'` is for cluster-local convention only                                                         |
+| Custom counters   | `createCounter('foo_total').inc(1, { status: 'ok' })`                           | `prom-client` `new Counter({...})`                            | The framework reads from `@frontmcp/observability`'s in-memory store; only `createCounter()` flows through it |
+| Label cardinality | `{ status: 'ok' \| 'error' }`                                                   | `{ user_id: '<jwt-sub>' }`                                    | Unbounded label values blow up the timeseries count                                                           |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `metrics: { enabled: true }` is set in `@FrontMcp({ ... })`
+- [ ] For internet-exposed deployments, `auth: 'token'` + `tokenEnv` are set AND the env var is exported in the deployment
+- [ ] `metrics.path` does NOT start with `/mcp`, `/sse`, or `/messages`
+- [ ] If using `include[]`, every category name is from the enum (`process` | `tools` | `resources` | `http` | `storage` | `skills` | `auth` | `sessions`)
+
+### Runtime
+
+- [ ] `curl http://<host>:<port>/metrics` returns 200 with Content-Type `text/plain; version=0.0.4; charset=utf-8`
+- [ ] Output contains at least one `frontmcp_process_*` gauge (proves the process-stats collector ran)
+- [ ] Output contains every `frontmcp_skills_*_total` counter incremented since startup
+- [ ] When `auth: 'token'`, requests without `Authorization: Bearer …` return 401 and wrong tokens return 403
+- [ ] Default `@FrontMcp({})` (no `metrics:` key) → `GET /metrics` returns 404 (route was never registered)
+
+## Troubleshooting
+
+| Problem                                                 | Cause                                                                                                          | Solution                                                                                             |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `GET /metrics` returns 404                              | `metrics.enabled` is `false` (default)                                                                         | Set `metrics: { enabled: true }`                                                                     |
+| Server throws `MetricsTokenNotConfiguredError` at boot  | `auth: 'token'` set but the env var is empty                                                                   | Export the env var, or switch `auth` to `'public'` / `{ token: '...' }`                              |
+| Server throws `MetricsPathConflictError` at boot        | `metrics.path` starts with `/mcp`, `/sse`, or `/messages`                                                      | Pick a non-MCP path like `/metrics` or `/internal/metrics`                                           |
+| Custom `createCounter()` values missing from the scrape | Counter was created on a different `@frontmcp/observability` module instance (e.g. duplicated in node_modules) | Ensure single `@frontmcp/observability` install via `yarn dedupe` / `npm ls @frontmcp/observability` |
+| OTel push pipeline and `/metrics` show different values | Counters created outside `createCounter()` (e.g. raw `prom-client`) bypass the in-memory store                 | Use `createCounter()` from `@frontmcp/observability` for everything; both paths read the same store  |
+
+## Examples
+
+| Example                                                                              | Level | Description                                                          |
+| ------------------------------------------------------------------------------------ | ----- | -------------------------------------------------------------------- |
+| [`enable-metrics-endpoint`](../examples/metrics-endpoint/enable-metrics-endpoint.md) | Basic | Turn on the /metrics endpoint with defaults and scrape it with curl. |
+
+## Accessing This Skill
+
+This skill is available over MCP under `skill://frontmcp-observability/SKILL.md` per SEP-2640. This reference page is served at `skill://frontmcp-observability/references/metrics-endpoint.md`.
+
+## Reference
+
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/metrics
+- Issue tracker: https://github.com/agentfront/frontmcp/issues/397
+- SDK exports: `MetricsService`, `registerMetricsRoutes`, `MetricsPathConflictError`, `MetricsTokenNotConfiguredError`
+- Observability exports: `renderPrometheusExposition`, `renderJsonExposition`, `ProcessStatsCollector`, `PROMETHEUS_CONTENT_TYPE`

package/catalog/frontmcp-setup/SKILL.md

@@ -52,17 +52,17 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Scenario Routing Table
 
-| Scenario                                      | Reference                                    | Description                                                                                   |
-| --------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`)  |
-| 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 distributed subscriptions (single-server uses in-memory) |
-| 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                                                     |
-| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                               |
+| Scenario                                      | Reference                                    | Description                                                                                    |
+| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`)   |
+| 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 distributed subscriptions (single-server uses in-memory)  |
+| 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 (search, list, install, read, export, publish), bundles, categories, bulk install |
+| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                                |
 
 ## Recommended Reading Order
 

package/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md

@@ -3,11 +3,13 @@ name: install-and-search-skills
 reference: frontmcp-skills-usage
 level: basic
 description: 'Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.'
-tags: [setup, cli, anthropic, skills, usage, install]
+tags: [setup, cli, anthropic, skills, usage, install, bulk, export]
 features:
   - '`frontmcp skills list` and `search` for discovering available skills'
   - '`frontmcp skills read` for viewing skill content and references on demand'
   - '`frontmcp skills install --provider claude` for static installation to `.claude/skills/`'
+  - '`frontmcp skills install --all` / `--category` / `--tag` for bulk install in one command'
+  - '`frontmcp skills export` to ship a skill to Cursor / Windsurf / Copilot rule files'
   - 'Installed skills are auto-loaded by Claude Code in its system prompt context'
 ---
 
@@ -52,6 +54,20 @@ frontmcp skills install frontmcp-development --provider codex
 
 # Install to a custom directory
 frontmcp skills install frontmcp-guides --dir ./my-skills
+
+# Bulk install — every skill in a category in one command
+frontmcp skills install --category development --provider claude
+
+# Bulk install — every skill in the catalog
+frontmcp skills install --all --provider claude
+
+# Bulk install by tag
+frontmcp skills install --tag middleware --provider codex
+
+# Export a skill as a Cursor / Windsurf / Copilot rule file (for skills-unaware IDEs)
+frontmcp skills export --name frontmcp-development --target cursor
+frontmcp skills export --all --target windsurf
+frontmcp skills export --all --target copilot --out ./.github
 ```
 
 After installation, the directory structure:
@@ -76,6 +92,8 @@ my-project/
 - `frontmcp skills list` and `search` for discovering available skills
 - `frontmcp skills read` for viewing skill content and references on demand
 - `frontmcp skills install --provider claude` for static installation to `.claude/skills/`
+- `frontmcp skills install --all` / `--category` / `--tag` for bulk install in one command
+- `frontmcp skills export` to ship a skill to Cursor / Windsurf / Copilot rule files
 - Installed skills are auto-loaded by Claude Code in its system prompt context
 
 ## Related