@frontmcp/skills 0.0.1

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

@@ -0,0 +1,167 @@
+---
+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

@@ -0,0 +1,189 @@
+---
+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
+```

package/catalog/config/configure-throttle/references/guard-config.md

@@ -0,0 +1,68 @@
+# GuardConfig Full Reference
+
+## Complete Configuration
+
+```typescript
+interface GuardConfig {
+  enabled: boolean;
+
+  // Storage for distributed rate limiting
+  storage?: {
+    type: 'memory' | 'redis';
+    redis?: RedisOptionsInput;
+  };
+
+  keyPrefix?: string; // default: 'mcp:guard:'
+
+  // Server-wide limits
+  global?: RateLimitConfig;
+  globalConcurrency?: ConcurrencyConfig;
+
+  // Default per-tool limits (overridden by tool-level config)
+  defaultRateLimit?: RateLimitConfig;
+  defaultConcurrency?: ConcurrencyConfig;
+  defaultTimeout?: TimeoutConfig;
+
+  // IP-based access control
+  ipFilter?: IpFilterConfig;
+}
+
+interface RateLimitConfig {
+  maxRequests: number;
+  windowMs?: number; // default: 60000 (1 minute)
+  partitionBy?: 'global' | 'ip' | 'session'; // default: 'global'
+}
+
+interface ConcurrencyConfig {
+  maxConcurrent: number;
+  queueTimeoutMs?: number; // default: 0 (fail immediately)
+  partitionBy?: 'global' | 'ip' | 'session';
+}
+
+interface TimeoutConfig {
+  executeMs: number;
+}
+
+interface IpFilterConfig {
+  allowList?: string[]; // IP addresses or CIDR ranges
+  denyList?: string[];
+  defaultAction?: 'allow' | 'deny'; // default: 'allow'
+  trustProxy?: boolean; // default: false
+  trustedProxyDepth?: number; // default: 1
+}
+```
+
+## Partition Strategies
+
+- **`'global'`**: Single counter shared by all clients. Protects total server capacity.
+- **`'ip'`**: Separate counter per client IP. Fair per-client limiting.
+- **`'session'`**: Separate counter per MCP session. Fair per-session limiting.
+
+## Priority Order
+
+1. IP filter (allow/deny) — checked first
+2. Global rate limit — checked second
+3. Global concurrency — checked third
+4. Per-tool rate limit — checked per tool
+5. Per-tool concurrency — checked per tool
+6. Per-tool timeout — enforced during execution

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

@@ -0,0 +1,151 @@
+---
+name: configure-transport
+description: Choose and configure transport protocols — SSE, Streamable HTTP, stateless API, or legacy. Use when deciding between transport modes, enabling distributed sessions, or configuring event stores.
+tags: [transport, sse, streamable-http, stateless, protocol, session]
+parameters:
+  - name: preset
+    description: Protocol preset (legacy, modern, stateless-api, full)
+    type: string
+    default: legacy
+examples:
+  - scenario: Use modern SSE + Streamable HTTP for production
+    expected-outcome: Server accepts both SSE and streamable HTTP connections
+  - scenario: Configure stateless API for serverless
+    expected-outcome: No session state, pure request/response
+priority: 8
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/deployment/runtime-modes
+---
+
+# Configuring Transport
+
+Configure how clients connect to your FrontMCP server — SSE, Streamable HTTP, stateless API, or a combination.
+
+## When to Use
+
+Configure transport when:
+
+- Choosing between SSE and Streamable HTTP protocols
+- Deploying to serverless (needs stateless mode)
+- Running multiple server instances (needs distributed sessions)
+- Enabling SSE event resumability
+
+## TransportOptionsInput
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    sessionMode: 'stateful', // 'stateful' | 'stateless'
+    protocol: 'legacy', // preset or custom ProtocolConfig
+    persistence: {
+      // false to disable
+      redis: { provider: 'redis', host: 'localhost', port: 6379 },
+      defaultTtlMs: 3600000,
+    },
+    distributedMode: 'auto', // boolean | 'auto'
+    eventStore: {
+      enabled: true,
+      provider: 'redis', // 'memory' | 'redis'
+      maxEvents: 10000,
+      ttlMs: 300000,
+    },
+  },
+})
+class Server {}
+```
+
+## Protocol Presets
+
+Choose a preset that matches your deployment:
+
+| Preset               | SSE | Streamable HTTP | JSON | Stateless | Legacy SSE | Strict Session |
+| -------------------- | --- | --------------- | ---- | --------- | ---------- | -------------- |
+| `'legacy'` (default) | Yes | Yes             | No   | No        | Yes        | Yes            |
+| `'modern'`           | Yes | Yes             | No   | No        | No         | Yes            |
+| `'stateless-api'`    | No  | No              | No   | Yes       | No         | No             |
+| `'full'`             | Yes | Yes             | Yes  | Yes       | Yes        | No             |
+
+### When to Use Each
+
+- **`'legacy'`** — Default. Maximum compatibility with all MCP clients (Claude Desktop, etc.). Best for Node.js deployments.
+- **`'modern'`** — Drop legacy SSE support. Use when all clients support modern MCP protocol.
+- **`'stateless-api'`** — No sessions, pure request/response. Use for **Vercel**, **Lambda**, and other serverless targets.
+- **`'full'`** — All protocols enabled. Use for development or when you need every transport option.
+
+### Custom Protocol Config
+
+Override individual protocol flags:
+
+```typescript
+transport: {
+  protocol: {
+    sse: true,              // SSE listener endpoint
+    streamable: true,       // Streamable HTTP POST
+    json: false,            // JSON-only responses (no streaming)
+    stateless: false,       // Stateless HTTP (no sessions)
+    legacy: false,          // Legacy SSE transport
+    strictSession: true,    // Require session ID for streamable HTTP
+  },
+}
+```
+
+## Distributed Sessions
+
+For multi-instance deployments (load balanced), enable persistence with Redis:
+
+```typescript
+transport: {
+  distributedMode: true,
+  persistence: {
+    redis: { provider: 'redis', host: 'redis.internal', port: 6379 },
+    defaultTtlMs: 3600000,  // 1 hour session TTL
+  },
+}
+```
+
+- `distributedMode: 'auto'` — auto-detect based on whether Redis is configured
+- `distributedMode: true` — force distributed mode (requires Redis)
+- `distributedMode: false` — single-instance mode (in-memory sessions)
+
+## Event Store (SSE Resumability)
+
+Enable event store so clients can resume SSE connections after disconnects:
+
+```typescript
+transport: {
+  eventStore: {
+    enabled: true,
+    provider: 'redis',       // 'memory' for single instance, 'redis' for distributed
+    maxEvents: 10000,        // max events to store
+    ttlMs: 300000,           // 5 minute TTL
+    redis: { provider: 'redis', host: 'localhost' },
+  },
+}
+```
+
+## Target-Specific Recommendations
+
+| Target                   | Recommended Preset | Persistence | Event Store |
+| ------------------------ | ------------------ | ----------- | ----------- |
+| Node.js (single)         | `'legacy'`         | `false`     | Memory      |
+| Node.js (multi-instance) | `'modern'`         | Redis       | Redis       |
+| Vercel                   | `'stateless-api'`  | `false`     | Disabled    |
+| Lambda                   | `'stateless-api'`  | `false`     | Disabled    |
+| Cloudflare               | `'stateless-api'`  | `false`     | Disabled    |
+
+## Verification
+
+```bash
+# Start server and test SSE
+frontmcp dev
+
+# Test SSE endpoint
+curl -N http://localhost:3001/sse
+
+# Test streamable HTTP
+curl -X POST http://localhost:3001/ -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```

package/catalog/config/configure-transport/references/protocol-presets.md

@@ -0,0 +1,57 @@
+# Transport Protocol Presets Reference
+
+## Preset Configurations
+
+### `'legacy'` (Default)
+
+Maximum compatibility with all MCP clients including older versions.
+
+```typescript
+{ sse: true, streamable: true, json: false, stateless: false, legacy: true, strictSession: true }
+```
+
+### `'modern'`
+
+Modern protocol only. Drops legacy SSE support.
+
+```typescript
+{ sse: true, streamable: true, json: false, stateless: false, legacy: false, strictSession: true }
+```
+
+### `'stateless-api'`
+
+No sessions. Pure request/response for serverless.
+
+```typescript
+{ sse: false, streamable: false, json: false, stateless: true, legacy: false, strictSession: false }
+```
+
+### `'full'`
+
+All protocols enabled. Maximum flexibility.
+
+```typescript
+{ sse: true, streamable: true, json: true, stateless: true, legacy: true, strictSession: false }
+```
+
+## Protocol Fields
+
+| Field           | Description          | Effect when `true`                                    |
+| --------------- | -------------------- | ----------------------------------------------------- |
+| `sse`           | SSE endpoint         | Enables `/sse` endpoint for server-sent events        |
+| `streamable`    | Streamable HTTP POST | Enables streaming responses via HTTP POST             |
+| `json`          | JSON-only responses  | Returns complete JSON without streaming               |
+| `stateless`     | Stateless HTTP       | No session management, each request standalone        |
+| `legacy`        | Legacy SSE transport | Backwards-compatible SSE for older clients            |
+| `strictSession` | Require session ID   | Streamable HTTP POST requires `mcp-session-id` header |
+
+## Deployment Recommendations
+
+| Deployment                | Preset                         | Why                                       |
+| ------------------------- | ------------------------------ | ----------------------------------------- |
+| Node.js (single instance) | `'legacy'`                     | Max compatibility, simple setup           |
+| Node.js (load balanced)   | `'modern'` + Redis persistence | Modern protocol with distributed sessions |
+| Vercel                    | `'stateless-api'`              | No persistent connections allowed         |
+| AWS Lambda                | `'stateless-api'`              | Stateless execution model                 |
+| Cloudflare Workers        | `'stateless-api'`              | Stateless edge runtime                    |
+| Development               | `'full'`                       | Test all protocols                        |