@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/auth/configure-session/SKILL.md

@@ -1,201 +0,0 @@
----
-name: configure-session
-description: Configure session storage with Redis, Vercel KV, or in-memory backends. Use when setting up sessions, choosing a storage provider, or configuring TTL and key prefixes.
-tags:
-  - session
-  - storage
-  - redis
-  - memory
-bundle:
-  - recommended
-  - full
-visibility: both
-priority: 5
-parameters:
-  - name: provider
-    description: Session storage provider
-    type: string
-    required: false
-    default: memory
-  - name: ttl
-    description: Default session TTL in milliseconds
-    type: number
-    required: false
-    default: 3600000
-  - name: key-prefix
-    description: Redis/KV key prefix for session keys
-    type: string
-    required: false
-    default: 'mcp:session:'
-examples:
-  - scenario: Configure Redis session store for production
-    parameters:
-      provider: redis
-    expected-outcome: Sessions are persisted in Redis with automatic TTL expiration and key prefixing
-  - scenario: Configure Vercel KV for serverless deployment
-    parameters:
-      provider: vercel-kv
-    expected-outcome: Sessions use Vercel KV with environment-based credentials
-  - scenario: Use memory store for local development
-    parameters:
-      provider: memory
-    expected-outcome: Sessions are stored in-process memory, suitable for development only
-license: Apache-2.0
-compatibility: Requires Node.js 18+. Redis provider requires ioredis. Vercel KV provider requires @vercel/kv.
-metadata:
-  category: auth
-  difficulty: beginner
-  docs: https://docs.agentfront.dev/frontmcp/deployment/redis-setup
----
-
-# Configure Session Management
-
-This skill covers setting up session storage in FrontMCP. Sessions track authenticated user state, token storage, and request context across MCP interactions.
-
-## Storage Providers
-
-| Provider    | Use Case            | Persistence | Package Required |
-| ----------- | ------------------- | ----------- | ---------------- |
-| `memory`    | Development/testing | None        | None (default)   |
-| `redis`     | Node.js production  | Yes         | `ioredis`        |
-| `vercel-kv` | Vercel deployments  | Yes         | `@vercel/kv`     |
-
-Never use the memory store in production. Sessions are lost on process restart, which breaks authentication for all connected clients.
-
-## Redis (Production)
-
-Configure Redis session storage via the `@FrontMcp` decorator:
-
-```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
-
-@App()
-class MyApp {}
-
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  redis: {
-    provider: 'redis',
-    host: process.env['REDIS_HOST'] ?? 'localhost',
-    port: Number(process.env['REDIS_PORT'] ?? 6379),
-    password: process.env['REDIS_PASSWORD'],
-  },
-})
-class MyServer {}
-```
-
-The SDK internally calls `createSessionStore()` to create a `RedisSessionStore`. The factory lazy-loads `ioredis` so it is not bundled when you use a different provider.
-
-## Vercel KV
-
-For Vercel deployments, use the `vercel-kv` provider. Credentials are read from environment variables set automatically by the Vercel platform:
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  redis: { provider: 'vercel-kv' },
-})
-class MyServer {}
-```
-
-Required environment variables (auto-injected when a KV store is linked to your Vercel project):
-
-| Variable            | Description                    |
-| ------------------- | ------------------------------ |
-| `KV_REST_API_URL`   | Vercel KV REST endpoint        |
-| `KV_REST_API_TOKEN` | Vercel KV authentication token |
-
-## Memory (Development Default)
-
-When no Redis or KV configuration is provided, the SDK falls back to an in-memory store. This is suitable only for development:
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  // No redis config -- defaults to memory
-})
-class MyServer {}
-```
-
-## Key Prefix
-
-All persistent stores support a `keyPrefix` option that namespaces session keys. This is important when multiple FrontMCP servers share the same Redis instance:
-
-```typescript
-@FrontMcp({
-  info: { name: 'billing-server', version: '1.0.0' },
-  apps: [MyApp],
-  redis: {
-    provider: 'redis',
-    host: 'shared-redis.internal',
-    port: 6379,
-    keyPrefix: 'billing-mcp:session:',
-  },
-})
-class BillingServer {}
-```
-
-Use a unique prefix per server to prevent session key collisions.
-
-## TTL Configuration
-
-The `defaultTtlMs` option controls how long sessions live before expiring:
-
-| Scenario                     | Recommended TTL         |
-| ---------------------------- | ----------------------- |
-| Interactive user sessions    | `3_600_000` (1 hour)    |
-| Long-running agent workflows | `86_400_000` (24 hours) |
-| Short-lived CI/CD operations | `600_000` (10 minutes)  |
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  redis: {
-    provider: 'redis',
-    host: 'localhost',
-    port: 6379,
-    defaultTtlMs: 86_400_000, // 24 hours for agent workflows
-  },
-})
-class MyServer {}
-```
-
-## Pub/Sub for Resource Subscriptions
-
-If your server uses resource subscriptions (clients subscribe to resource change notifications), you need a pub/sub channel. Vercel KV does not support pub/sub, so you must use Redis for the pub/sub channel even when using Vercel KV for sessions:
-
-```typescript
-import { createSessionStore, createPubsubStore } from '@frontmcp/sdk/auth/session';
-
-// Sessions in Vercel KV
-const sessionStore = await createSessionStore({
-  provider: 'vercel-kv',
-  url: process.env['KV_REST_API_URL'],
-  token: process.env['KV_REST_API_TOKEN'],
-});
-
-// Pub/sub requires Redis
-const pubsubStore = createPubsubStore({
-  provider: 'redis',
-  host: process.env['REDIS_HOST'] ?? 'localhost',
-  port: 6379,
-});
-```
-
-## Common Mistakes
-
-- **Constructing stores directly** -- always use factory functions (`createSessionStore`). Direct construction bypasses lazy-loading and key prefix normalization.
-- **Using memory store in production** -- sessions vanish on restart. Clients must re-authenticate and in-flight workflows are lost.
-- **Missing `await` for Vercel KV** -- the `createSessionStore` factory is async when the provider is `vercel-kv`. Forgetting to await causes the store to be used before its connection is ready.
-- **Sharing key prefixes** -- if two servers share a Redis instance with the same prefix, their sessions collide. Always use a unique prefix per server.
-
-## Reference
-
-- Session docs: [docs.agentfront.dev/frontmcp/deployment/redis-setup](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
-- Session store factory: `createSessionStore()` — import from `@frontmcp/sdk`
-- Redis session store: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/session)
-- Vercel KV session store: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/session)

package/catalog/config/configure-elicitation/SKILL.md

@@ -1,136 +0,0 @@
----
-name: configure-elicitation
-description: Enable interactive user input requests from tools during execution. Use when tools need to ask the user for confirmation, choices, or additional data mid-execution.
-tags: [elicitation, user-input, interactive, confirmation, form]
-examples:
-  - scenario: Tool asks user for confirmation before destructive action
-    expected-outcome: Execution pauses, user confirms, tool proceeds
-  - scenario: Tool presents a form for user to fill in
-    expected-outcome: User fills form fields, tool receives structured input
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/elicitation
----
-
-# Configuring Elicitation
-
-Elicitation allows tools to request interactive input from users mid-execution — confirmations, choices, or structured form data.
-
-## When to Use
-
-Enable elicitation when:
-
-- Tools need user confirmation before destructive actions (delete, deploy, overwrite)
-- Tools need additional input during execution (file selection, parameter choice)
-- Building multi-step workflows that require user decisions at each stage
-
-## Enable Elicitation
-
-### Basic (In-Memory)
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  elicitation: {
-    enabled: true,
-  },
-})
-class Server {}
-```
-
-### With Redis (Distributed/Production)
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  elicitation: {
-    enabled: true,
-    redis: { provider: 'redis', host: 'localhost', port: 6379 },
-  },
-})
-class Server {}
-```
-
-## ElicitationOptionsInput
-
-```typescript
-interface ElicitationOptionsInput {
-  enabled?: boolean; // default: false
-  redis?: RedisOptionsInput; // storage for elicitation state
-}
-```
-
-## Using Elicitation in Tools
-
-When elicitation is enabled, tools can request user input via the MCP elicitation protocol:
-
-```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
-
-@Tool({
-  name: 'delete_records',
-  description: 'Delete records from the database',
-  inputSchema: {
-    table: z.string(),
-    filter: z.string(),
-  },
-  outputSchema: { deleted: z.number() },
-})
-class DeleteRecordsTool extends ToolContext {
-  async execute(input: { table: string; filter: string }) {
-    // Count records that would be deleted
-    const db = this.get(DB_TOKEN);
-    const count = await db.count(input.table, input.filter);
-
-    // Request confirmation from user before proceeding
-    const confirmation = await this.elicit({
-      message: `This will delete ${count} records from ${input.table}. Are you sure?`,
-      requestedSchema: {
-        type: 'object',
-        properties: {
-          confirmed: { type: 'boolean', description: 'Confirm deletion' },
-        },
-        required: ['confirmed'],
-      },
-    });
-
-    if (!confirmation || !confirmation.confirmed) {
-      return { deleted: 0 };
-    }
-
-    const deleted = await db.delete(input.table, input.filter);
-    return { deleted };
-  }
-}
-```
-
-## How It Works
-
-1. Tool calls `this.elicit()` with a message and requested schema
-2. Server sends an `elicitation/request` to the client
-3. Client displays the request to the user (UI varies by client)
-4. User responds with structured data matching the schema
-5. `this.elicit()` returns the user's response
-6. Tool continues execution with the response
-
-## Notes
-
-- When `enabled: false` (default), `this.elicit()` is not available — keeps resource overhead low
-- When enabled, tool output schemas are automatically extended with elicitation fallback type
-- Use Redis storage for production/multi-instance deployments
-- Not all MCP clients support elicitation — handle gracefully when `this.elicit()` returns `undefined`
-
-## Verification
-
-```bash
-# Enable elicitation and start
-frontmcp dev
-
-# Test with an MCP client that supports elicitation
-# The tool should pause and request user input
-```

package/catalog/config/configure-http/SKILL.md

@@ -1,167 +0,0 @@
----
-name: configure-http
-description: Configure HTTP server options including port, CORS, unix sockets, and entry path. Use when customizing the HTTP listener, enabling CORS, or binding to a unix socket.
-tags: [http, cors, port, socket, server, configuration]
-parameters:
-  - name: port
-    description: HTTP server port
-    type: number
-    default: 3001
-examples:
-  - scenario: Configure CORS for a specific frontend origin
-    expected-outcome: Server accepts requests only from the allowed origin
-  - scenario: Bind to a unix socket for local-only access
-    expected-outcome: Server listens on unix socket instead of TCP port
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/local-dev-server
----
-
-# Configuring HTTP Options
-
-Configure the HTTP server — port, CORS policy, unix sockets, and entry path prefix.
-
-## When to Use
-
-Configure HTTP options when:
-
-- Changing the default port (3001)
-- Enabling CORS for a frontend application
-- Mounting the MCP server under a URL prefix
-- Binding to a unix socket for local daemon mode
-
-## HttpOptionsInput
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  http: {
-    port: 3001, // default: 3001
-    entryPath: '', // default: '' (root)
-    socketPath: undefined, // unix socket path (overrides port)
-    cors: {
-      // default: permissive (all origins)
-      origin: ['https://myapp.com'],
-      credentials: true,
-      maxAge: 86400,
-    },
-  },
-})
-class Server {}
-```
-
-## Port Configuration
-
-```typescript
-// Default: port 3001
-http: {
-  port: 3001;
-}
-
-// Use environment variable
-http: {
-  port: Number(process.env.PORT) || 3001;
-}
-
-// Random port (useful for testing)
-http: {
-  port: 0;
-}
-```
-
-## CORS Configuration
-
-### Permissive (Default)
-
-When `cors` is not specified, the server allows all origins without credentials:
-
-```typescript
-// All origins allowed (default behavior)
-http: {
-}
-```
-
-### Restrict to Specific Origins
-
-```typescript
-http: {
-  cors: {
-    origin: ['https://myapp.com', 'https://staging.myapp.com'],
-    credentials: true,
-    maxAge: 86400,  // Cache preflight for 24 hours
-  },
-}
-```
-
-### Disable CORS Entirely
-
-```typescript
-http: {
-  cors: false,  // No CORS headers at all
-}
-```
-
-### Dynamic Origin
-
-```typescript
-http: {
-  cors: {
-    origin: (origin: string) => {
-      // Allow any *.myapp.com subdomain
-      return origin.endsWith('.myapp.com');
-    },
-    credentials: true,
-  },
-}
-```
-
-### CORS Fields
-
-| Field         | Type                                        | Default      | Description                        |
-| ------------- | ------------------------------------------- | ------------ | ---------------------------------- |
-| `origin`      | `boolean \| string \| string[] \| function` | `true` (all) | Allowed origins                    |
-| `credentials` | `boolean`                                   | `false`      | Allow cookies/auth headers         |
-| `maxAge`      | `number`                                    | —            | Preflight cache duration (seconds) |
-
-## Entry Path Prefix
-
-Mount the MCP server under a URL prefix:
-
-```typescript
-http: {
-  entryPath: '/api/mcp',
-}
-// Server endpoints become: /api/mcp/sse, /api/mcp/, etc.
-```
-
-Useful when running behind a reverse proxy or alongside other services.
-
-## Unix Socket Mode
-
-Bind to a unix socket instead of a TCP port for local-only access:
-
-```typescript
-http: {
-  socketPath: '/tmp/my-mcp-server.sock',
-}
-```
-
-- Mutually exclusive with `port` — if `socketPath` is set, `port` is ignored
-- Use for local daemons, CLI tools, and process manager integrations
-- Combine with `sqlite` for fully local deployments
-
-## Verification
-
-```bash
-# Start with custom port
-PORT=8080 frontmcp dev
-
-# Test CORS
-curl -v -H "Origin: https://myapp.com" http://localhost:8080/
-
-# Test unix socket
-curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
-```

package/catalog/config/configure-throttle/SKILL.md

@@ -1,189 +0,0 @@
----
-name: configure-throttle
-description: Set up rate limiting, concurrency control, timeouts, and IP filtering at server and per-tool level. Use when protecting against abuse, limiting request rates, or configuring IP allow/deny lists.
-tags: [throttle, rate-limit, concurrency, timeout, security, guard, ip-filter]
-parameters:
-  - name: maxRequests
-    description: Maximum requests per window
-    type: number
-    default: 100
-examples:
-  - scenario: Rate limit all tools to 100 requests per minute
-    expected-outcome: Requests beyond limit receive 429 response
-  - scenario: Limit concurrent executions of expensive tool to 5
-    expected-outcome: 6th concurrent call queues or fails
-  - scenario: Block requests from specific IP ranges
-    expected-outcome: Blocked IPs receive 403 response
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/guard
----
-
-# Configuring Throttle, Rate Limits, and IP Filtering
-
-Protect your FrontMCP server with rate limiting, concurrency control, execution timeouts, and IP filtering — at both server and per-tool levels.
-
-## When to Use
-
-Configure throttle when:
-
-- Protecting against abuse or DDoS
-- Limiting expensive tool executions
-- Enforcing per-session or per-IP request quotas
-- Blocking or allowing specific IP ranges
-- Setting execution timeouts for long-running tools
-
-## Server-Level Throttle (GuardConfig)
-
-```typescript
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  throttle: {
-    enabled: true,
-
-    // Global rate limit (all requests combined)
-    global: {
-      maxRequests: 1000,
-      windowMs: 60000, // 1 minute window
-      partitionBy: 'global', // shared across all clients
-    },
-
-    // Global concurrency limit
-    globalConcurrency: {
-      maxConcurrent: 50,
-      partitionBy: 'global',
-    },
-
-    // Default limits for individual tools (applied unless tool overrides)
-    defaultRateLimit: {
-      maxRequests: 100,
-      windowMs: 60000,
-    },
-    defaultConcurrency: {
-      maxConcurrent: 10,
-    },
-    defaultTimeout: {
-      executeMs: 30000, // 30 second timeout
-    },
-
-    // IP filtering
-    ipFilter: {
-      allowList: ['10.0.0.0/8', '172.16.0.0/12'], // CIDR ranges
-      denyList: ['192.168.1.100'],
-      defaultAction: 'allow', // 'allow' | 'deny'
-      trustProxy: true, // trust X-Forwarded-For
-      trustedProxyDepth: 1, // proxy depth to trust
-    },
-  },
-})
-class Server {}
-```
-
-## Per-Tool Rate Limiting
-
-Override server defaults on individual tools:
-
-```typescript
-@Tool({
-  name: 'expensive_query',
-  description: 'Run an expensive database query',
-  inputSchema: {
-    query: z.string(),
-  },
-  outputSchema: { rows: z.array(z.record(z.unknown())) },
-
-  // Per-tool limits
-  rateLimit: {
-    maxRequests: 10,
-    windowMs: 60000,
-    partitionBy: 'session', // per-session rate limit
-  },
-  concurrency: {
-    maxConcurrent: 3,
-    queueTimeoutMs: 5000, // wait up to 5s for a slot
-    partitionBy: 'session',
-  },
-  timeout: {
-    executeMs: 60000, // 60 second timeout for this tool
-  },
-})
-class ExpensiveQueryTool extends ToolContext {
-  async execute(input: { query: string }) {
-    const db = this.get(DB_TOKEN);
-    return { rows: await db.query(input.query) };
-  }
-}
-```
-
-## Configuration Types
-
-### RateLimitConfig
-
-| Field         | Type                            | Default    | Description               |
-| ------------- | ------------------------------- | ---------- | ------------------------- |
-| `maxRequests` | `number`                        | —          | Max requests per window   |
-| `windowMs`    | `number`                        | `60000`    | Window duration in ms     |
-| `partitionBy` | `'global' \| 'ip' \| 'session'` | `'global'` | How to partition counters |
-
-### ConcurrencyConfig
-
-| Field            | Type                            | Default    | Description                                        |
-| ---------------- | ------------------------------- | ---------- | -------------------------------------------------- |
-| `maxConcurrent`  | `number`                        | —          | Max simultaneous executions                        |
-| `queueTimeoutMs` | `number`                        | `0`        | How long to wait for a slot (0 = fail immediately) |
-| `partitionBy`    | `'global' \| 'ip' \| 'session'` | `'global'` | How to partition counters                          |
-
-### TimeoutConfig
-
-| Field       | Type     | Default | Description              |
-| ----------- | -------- | ------- | ------------------------ |
-| `executeMs` | `number` | —       | Max execution time in ms |
-
-### IpFilterConfig
-
-| Field               | Type                | Default   | Description                         |
-| ------------------- | ------------------- | --------- | ----------------------------------- |
-| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges          |
-| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges          |
-| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list |
-| `trustProxy`        | `boolean`           | `false`   | Trust X-Forwarded-For header        |
-| `trustedProxyDepth` | `number`            | `1`       | How many proxy hops to trust        |
-
-## Partition Strategies
-
-- **`'global'`** — Single shared counter for all clients. Use for global capacity limits.
-- **`'ip'`** — Separate counter per client IP. Use for per-client rate limiting.
-- **`'session'`** — Separate counter per MCP session. Use for per-session fairness.
-
-## Distributed Rate Limiting
-
-For multi-instance deployments, configure Redis storage in the guard:
-
-```typescript
-throttle: {
-  enabled: true,
-  storage: {
-    type: 'redis',
-    redis: { provider: 'redis', host: 'redis.internal' },
-  },
-  global: { maxRequests: 1000, windowMs: 60000 },
-}
-```
-
-## Verification
-
-```bash
-# Start server
-frontmcp dev
-
-# Test rate limiting (send 101 requests rapidly)
-for i in $(seq 1 101); do
-  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3001/ \
-    -H 'Content-Type: application/json' \
-    -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-done
-# Should see 429 responses after limit is exceeded
-```