@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/frontmcp-config/references/configure-http.md

@@ -1,11 +1,11 @@
 ---
 name: configure-http
-description: Configure HTTP server port, CORS policy, unix sockets, and entry path prefix
+description: Configure HTTP server port, CORS policy, unix sockets, entry path prefix, request body limits, and custom HTTP routes
 ---
 
 # Configuring HTTP Options
 
-Configure the HTTP server — port, CORS policy, unix sockets, and entry path prefix.
+Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix, request body limits, and first-class custom HTTP routes.
 
 ## When to Use This Skill
 
@@ -14,12 +14,18 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
 - Changing the default HTTP port or binding to a specific network interface
 - Enabling or restricting CORS for a frontend application that calls the MCP server
 - Binding to a unix socket for local daemon or process-manager integrations
+- Raising or tightening the request body limit (default `'4mb'`) for tools that
+  accept base64-encoded blobs (PDFs, DOCXes, large HTML payloads)
+- Adding a custom HTTP route (download endpoint, webhook, health-beyond-`/health`)
+  on the same listener as the MCP endpoint via `http.routes`
 
 ### Recommended
 
 - Mounting the MCP server under a URL prefix behind a reverse proxy
 - Setting a dynamic port from an environment variable for container deployments
 - Fine-tuning CORS preflight caching for performance-sensitive frontends
+- Tightening `bodyLimit` on public-facing deployments to bound per-request
+  memory
 
 ### Skip When
 
@@ -45,6 +51,18 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
       credentials: true,
       maxAge: 86400,
     },
+    bodyLimit: '4mb', // default: '4mb' — body-parser-compatible string or bytes (number)
+    urlencodedLimit: undefined, // default: falls back to bodyLimit
+    routes: [
+      // First-class custom HTTP routes (see "Custom HTTP Routes" below)
+      {
+        method: 'GET',
+        path: '/download/:id',
+        handler: (req, res) => {
+          /* ... */
+        },
+      },
+    ],
   },
 })
 class Server {}
@@ -127,6 +145,164 @@ http: {
 | `credentials` | `boolean`                                   | `false`      | Allow cookies/auth headers         |
 | `maxAge`      | `number`                                    | —            | Preflight cache duration (seconds) |
 
+## Request Body Limits
+
+FrontMCP's Express host applies a default body limit of `'4mb'` to both
+`express.json()` and `express.urlencoded()`. This lifts body-parser's silent
+100KB default, which previously rejected base64-encoded blobs (PDFs, DOCXes,
+large HTML inputs) with HTTP 413 before they reached MCP tool handlers
+(issue #410).
+
+```typescript
+http: {
+  bodyLimit: '500kb',       // tighten for public-facing deployments
+  urlencodedLimit: '100kb', // optional — falls back to bodyLimit when omitted
+}
+```
+
+| Option            | Type               | Default                   | Notes                                                                  |
+| ----------------- | ------------------ | ------------------------- | ---------------------------------------------------------------------- |
+| `bodyLimit`       | `number \| string` | `'4mb'`                   | Bytes (number) or body-parser string (`'4mb'`, `'500kb'`, `'2gb'`, …). |
+| `urlencodedLimit` | `number \| string` | falls back to `bodyLimit` | Independent override for `application/x-www-form-urlencoded` bodies.   |
+
+Requests exceeding the configured limit receive a structured JSON-RPC 413
+response — never an Express HTML error page:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": null,
+  "error": {
+    "code": -32600,
+    "message": "Payload Too Large",
+    "data": { "limit": 102400, "length": 204800 }
+  }
+}
+```
+
+> **Security trade-off.** Body-parser buffers the full request body in memory
+> before parsing, so raising `bodyLimit` scales per-request memory with
+> concurrency. Deployments exposed to untrusted networks should set an
+> explicit lower bound sized for the largest legitimate payload. The
+> 100KB → 4MB default change is a liberalization (every request that
+> succeeded before still succeeds), but the implicit DoS guard is gone
+> unless you set the option yourself.
+
+Custom `hostFactory` users build their own Express app and are **not
+affected** by `bodyLimit`/`urlencodedLimit` — those options are consumed only
+by the built-in `ExpressHostAdapter`. Custom-host deployments must configure
+their own body limits.
+
+## Custom HTTP Routes
+
+`http.routes` mounts first-class custom HTTP handlers on the **same listener**
+as the MCP JSON-RPC endpoint. Use them for byte delivery (file/stream/binary
+downloads), webhooks, health probes beyond `/health`, or any non-JSON-RPC
+surface — the MCP channel cannot serve those.
+
+```typescript
+import type { ServerRequest, ServerResponse } from '@frontmcp/sdk';
+
+http: {
+  routes: [
+    // Public route (default) — no auth.
+    {
+      method: 'GET',
+      path: '/download/:id',
+      handler: (req: ServerRequest, res: ServerResponse) => {
+        res.setHeader('Content-Type', 'application/pdf'); // see Content-Type note
+        res.status(200).send(loadPdfBytes(req.params.id));
+      },
+    },
+    // Auth-gated route — runs the MCP `session:verify` flow first.
+    {
+      method: 'POST',
+      path: '/webhooks/billing',
+      auth: true,
+      handler: (req: ServerRequest, res: ServerResponse) => {
+        // req.authSession is populated when auth: true and verification passed
+        res.status(202).json({ accepted: true, user: req.authSession?.user?.sub });
+      },
+    },
+  ],
+}
+```
+
+| Field     | Type                   | Default          | Description                                                              |
+| --------- | ---------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `method`  | `HttpMethod`           | —                | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'OPTIONS' \| 'HEAD'` |
+| `path`    | `string`               | —                | Express-style path (`/files/:id`); must not collide with reserved paths  |
+| `handler` | `ServerRequestHandler` | —                | `(req, res, next) => void \| Promise<void>`                              |
+| `auth`    | `boolean`              | `false` (public) | When `true`, gate behind the MCP `session:verify` flow                   |
+
+### Handler signature
+
+The handler uses the framework-agnostic `(req, res, next)` signature. Respond
+with `res.status(...).json(...)` / `res.send(...)`, or call `next()` to fall
+through. `req` and `res` are exported as `ServerRequest` / `ServerResponse`
+from `@frontmcp/sdk`, and `ServerRequestHandler` types the handler directly.
+
+Routes share the configured **CORS policy, body limits, and security
+middleware** with the MCP endpoint — they ride the same Express app.
+
+### `auth` opt-in
+
+Routes are **public by default**. Set `auth: true` to run the request through
+the exact same `session:verify` flow the MCP endpoint uses:
+
+- **Unauthorized** → short-circuits with `401` + a `WWW-Authenticate` header.
+- **Forbidden** (valid token, insufficient scope) → `403` + `WWW-Authenticate`.
+- **Authorized** → the verified authorization is attached to `req.authSession`
+  before your handler runs.
+
+In **public auth mode** (or transparent with `allowAnonymous`), `auth: true`
+routes receive an anonymous session and the handler still runs. Under auth
+modes with no anonymous fallback (e.g. `local` with `allowDefaultPublic: false`),
+unauthenticated requests get the `401`.
+
+### Reserved-path guard
+
+Custom paths that collide with FrontMCP's own surfaces are **rejected at
+startup** (fail-fast) — they would otherwise shadow or be shadowed by the MCP
+endpoint. Reserved:
+
+- the resolved MCP entry path (and its `/sse` + `/message` siblings) — split-by-app
+  scope bases are included (e.g. `/mcp/billing`),
+- anything under `/oauth/*` and `/.well-known/*`,
+- `/health` and `/metrics`.
+
+```typescript
+// ❌ Throws at startup: collides with the MCP entry path when entryPath: '/mcp'
+http: { entryPath: '/mcp', routes: [{ method: 'POST', path: '/mcp', handler }] }
+```
+
+### Content-Type gotcha
+
+The built-in `ExpressHostAdapter` defaults **every** response to
+`application/json; charset=utf-8`. HTML, binary, and streaming handlers MUST
+set their own content type **before** sending the body:
+
+```typescript
+{
+  method: 'GET',
+  path: '/report',
+  handler: (req, res) => {
+    res.setHeader('Content-Type', 'text/html; charset=utf-8'); // or res.type('html')
+    res.status(200).send('<!doctype html><h1>Report</h1>');
+  },
+}
+```
+
+### Large payloads: prefer a custom route over `@Resource`
+
+> **Decision:** When a tool needs to hand the client a **large** payload, return
+> a [`resource_link`](https://docs.agentfront.dev/frontmcp/servers/resources)
+> that points at a custom `http.routes` **GET** handler, and serve the bytes
+> from that handler (it supports stream/binary delivery). A `@Resource` rides
+> the MCP JSON-RPC channel and is **not** out-of-band — large reads block the
+> protocol stream and inflate token usage. The custom route delivers bytes on a
+> separate HTTP request the client fetches directly.
+
 ## Entry Path Prefix
 
 Mount the MCP server under a URL prefix:
@@ -192,29 +368,42 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 - [ ] `maxAge` is set to a reasonable value for production (e.g., `86400` for 24 hours)
 - [ ] Dynamic origin function handles `undefined` origin (non-browser requests)
 
+### Custom Routes
+
+- [ ] No custom `path` collides with the MCP entry path, `/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, or `/metrics`
+- [ ] HTML/binary/stream handlers call `res.setHeader('Content-Type', ...)` (or `res.type(...)`) before `res.send(...)`
+- [ ] `auth: true` is set on any route that must require a verified session
+- [ ] Large payloads are served via a custom GET route + `resource_link`, not a `@Resource`
+
 ### Runtime
 
 - [ ] Server starts and binds to the expected port or socket path
 - [ ] `curl -v -H "Origin: <your-origin>" <url>` returns correct `Access-Control-Allow-Origin`
 - [ ] Preflight `OPTIONS` requests return `204` with expected CORS headers
+- [ ] Custom routes respond as expected (`curl <url>/<your-route>`)
 
 ## Troubleshooting
 
-| Problem                                          | Cause                                                                                      | Solution                                                                                                |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `EADDRINUSE` on startup                          | Another process is already using the configured port                                       | Change the port, stop the other process, or use `port: 0` for a random available port                   |
-| CORS errors in the browser console               | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin  | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible |
-| Unix socket file not created                     | Missing write permissions on the target directory or stale socket file from a previous run | Check directory permissions and remove the stale `.sock` file before restarting                         |
-| Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                |
-| Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
+| Problem                                               | Cause                                                                                                                | Solution                                                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `EADDRINUSE` on startup                               | Another process is already using the configured port                                                                 | Change the port, stop the other process, or use `port: 0` for a random available port                    |
+| CORS errors in the browser console                    | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin                            | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible  |
+| Unix socket file not created                          | Missing write permissions on the target directory or stale socket file from a previous run                           | Check directory permissions and remove the stale `.sock` file before restarting                          |
+| Routes return 404 after setting `entryPath`           | Client is still requesting the root path without the prefix                                                          | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                 |
+| Server binds but external clients cannot connect      | Server bound to `localhost` or `127.0.0.1` inside a container                                                        | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                            |
+| `413 Payload Too Large` with JSON-RPC envelope        | Request body exceeded `bodyLimit` (default `'4mb'`)                                                                  | Raise `http.bodyLimit` to fit the payload, or move large blobs to a separate upload endpoint             |
+| Server throws at startup mentioning a "reserved" path | A custom `http.routes` path collides with the MCP entry path, `/oauth/*`, `/.well-known/*`, `/health`, or `/metrics` | Rename the custom route to a non-reserved path                                                           |
+| Custom route returns JSON when HTML/bytes expected    | The Express adapter defaults responses to `application/json`                                                         | Set `res.setHeader('Content-Type', ...)` (or `res.type(...)`) in the handler before sending the body     |
+| Custom `auth: true` route always returns `401`        | Auth mode has no anonymous fallback and the request carries no valid bearer token                                    | Send a valid `Authorization: Bearer <jwt>`, or use `auth` mode `public`/transparent-anon for open routes |
 
 ## Examples
 
-| Example                                                                              | Level        | Description                                                                          |
-| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
-| [`cors-restricted-origins`](../examples/configure-http/cors-restricted-origins.md)   | Basic        | Configure CORS to allow only specific frontend origins with credentials.             |
-| [`entry-path-reverse-proxy`](../examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.   |
-| [`unix-socket-local`](../examples/configure-http/unix-socket-local.md)               | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication. |
+| Example                                                                              | Level        | Description                                                                                                                      |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| [`cors-restricted-origins`](../examples/configure-http/cors-restricted-origins.md)   | Basic        | Configure CORS to allow only specific frontend origins with credentials.                                                         |
+| [`custom-http-routes`](../examples/configure-http/custom-http-routes.md)             | Intermediate | Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes. |
+| [`entry-path-reverse-proxy`](../examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.                                               |
+| [`unix-socket-local`](../examples/configure-http/unix-socket-local.md)               | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication.                                             |
 
 > See all examples in [`examples/configure-http/`](../examples/configure-http/)
 

package/catalog/frontmcp-config/references/configure-session.md

@@ -1,6 +1,6 @@
 ---
 name: configure-session
-description: Set up session storage with Redis or Vercel KV for persistent user state across requests
+description: Set up session storage with Redis, Vercel KV, or SQLite for persistent user state across requests
 ---
 
 # Configure Session Management
@@ -11,7 +11,7 @@ This skill covers setting up session storage in FrontMCP. Sessions track authent
 
 ### Must Use
 
-- Deploying to production where sessions must survive process restarts (Redis or Vercel KV required)
+- Deploying to production where sessions must survive process restarts (Redis, Vercel KV, or SQLite required)
 - Running multiple server instances behind a load balancer that need shared session state
 - Using Streamable HTTP transport where sessions must persist across reconnects
 
@@ -31,14 +31,21 @@ This skill covers setting up session storage in FrontMCP. Sessions track authent
 
 ## 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`     |
+| 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`                                  |
+| `sqlite`    | Single-node persistent (CLI / Docker / VM) | Yes         | `@frontmcp/storage-sqlite` + `better-sqlite3` |
 
 Never use the memory store in production. Sessions are lost on process restart, which breaks authentication for all connected clients.
 
+SQLite is set via the top-level `sqlite` block (not via `redis: { provider: ... }`).
+See the [`setup-sqlite`](../../frontmcp-setup/references/setup-sqlite.md) skill
+for the full walkthrough. The same top-level `sqlite` block is auto-threaded
+into the task store and elicitation store unless they are individually
+configured to use a different backend (issue #401).
+
 ## Redis (Production)
 
 Configure Redis session storage via the `@FrontMcp` decorator:

package/catalog/frontmcp-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-deployment
-description: 'Use when you need to deploy, build for production, containerize, or ship a FrontMCP server. Covers Vercel, Lambda, Cloudflare, Docker, edge runtime, serverless, bundle for CLI, and Node targets. Triggers: deploy, build for production, dockerize, serverless, go live.'
+description: 'Use when deploying, building for production, packaging, or shipping a FrontMCP server. Covers build targets (node, cli SEA binary, browser, embeddable SDK, mcpb archive for Claude Desktop, serverless) and deploying to Vercel (with Vercel KV), AWS Lambda (API Gateway, SAM, CDK), Cloudflare Workers (KV, D1, Durable Objects, v1.3 skills-only), and Node (multi-stage Docker, docker-compose, PM2, nginx). Also the frontmcp.deploy.yaml manifest plus GitHub Action push-resync, and MCP client integration / .mcp.json for Claude Desktop, Claude Code, Cursor, and VS Code over stdio or HTTP. Triggers: deploy, build for production, dockerize, containerize, serverless, edge runtime, go live, ship it.'
 tags: [router, deployment, node, vercel, lambda, cloudflare, cli, browser, sdk, guide]
 category: deployment
 targets: [all]
@@ -36,7 +36,7 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 - You need to configure server settings, not deploy (see `frontmcp-config`)
 - You need to build components, not ship them (see `frontmcp-development`)
 
-> **Decision:** Use this skill when you need to figure out WHERE to deploy. Use the specific skill when you already know.
+> **Decision:** Use this skill when you need to figure out WHERE to deploy. Open the matching reference under `references/` directly when you already know.
 
 ## Prerequisites
 
@@ -48,23 +48,25 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 
 1. Review the Scenario Routing Table and Target Comparison below to choose a deployment target
 2. Run `frontmcp build --target <target>` to produce the build output
-3. Follow the specific deployment skill (e.g., `deploy-to-node`, `deploy-to-vercel`) for platform instructions
+3. Follow the specific deployment reference (e.g., `references/deploy-to-node.md`, `references/deploy-to-vercel.md`) for platform instructions
 4. Verify with the Post-Deployment checklist at the end of this skill
 
 ## Scenario Routing Table
 
-| Scenario                                          | Skill                       | Description                                                             |
-| ------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
-| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`            | Node.js with stdio or HTTP transport, PM2/Docker for process management |
-| Serverless with zero config and Vercel KV         | `deploy-to-vercel`          | Vercel Functions with Streamable HTTP, Vercel KV for storage            |
-| AWS serverless with API Gateway                   | `deploy-to-lambda`          | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache      |
-| Edge computing with global distribution           | `deploy-to-cloudflare`      | Cloudflare Workers with KV or Durable Objects for storage               |
-| Standalone executable binary for distribution     | `build-for-cli`             | Single-binary CLI with stdio transport, embedded storage                |
-| Run MCP in a web browser                          | `build-for-browser`         | Browser-compatible bundle with in-memory transport                      |
-| Embed MCP into an existing Node.js application    | `build-for-sdk`             | Library build for programmatic usage without standalone server          |
-| Write a Dockerfile for Node.js deployment         | `deploy-to-node-dockerfile` | Dockerfile configuration for Node.js deployment                         |
-| Configure Vercel-specific settings (vercel.json)  | `deploy-to-vercel-config`   | Vercel-specific configuration (vercel.json)                             |
-| Connect MCP clients (Claude, Cursor, VS Code)     | `mcp-client-integration`    | Configure .mcp.json for stdio, HTTP, or Unix socket transport           |
+| Scenario                                          | Reference                          | Description                                                                                                                                      |
+| ------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`                   | Node.js with stdio or HTTP transport, PM2/Docker for process management                                                                          |
+| Serverless with zero config and Vercel KV         | `deploy-to-vercel`                 | Vercel Functions with Streamable HTTP, Vercel KV for storage                                                                                     |
+| AWS serverless with API Gateway                   | `deploy-to-lambda`                 | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache                                                                               |
+| Edge computing with global distribution           | `deploy-to-cloudflare`             | Cloudflare Workers with KV or Durable Objects for storage                                                                                        |
+| Hosted FrontMCP (v1.3 skills-only model)          | `deploy-to-cloudflare-skills-only` | Cloudflare Worker as the MCP control plane; OpenAPI is capability inventory; agent uses 4 meta-tools + AgentScript; hot-reload via GitHub Action |
+| Author `frontmcp.deploy.yaml`                     | `deploy-manifest-yaml`             | v1 schema reference: runtime, server, specs, skills, tags, classification, bindings, signing, auth, secrets, environments                        |
+| Standalone executable binary for distribution     | `build-for-cli`                    | Single-binary CLI with stdio transport, embedded storage                                                                                         |
+| Run MCP in a web browser                          | `build-for-browser`                | Browser-compatible bundle with in-memory transport                                                                                               |
+| Embed MCP into an existing Node.js application    | `build-for-sdk`                    | Library build for programmatic usage without standalone server                                                                                   |
+| Write a Dockerfile for Node.js deployment         | `deploy-to-node-dockerfile`        | Dockerfile configuration for Node.js deployment                                                                                                  |
+| Configure Vercel-specific settings (vercel.json)  | `deploy-to-vercel-config`          | Vercel-specific configuration (vercel.json)                                                                                                      |
+| Connect MCP clients (Claude, Cursor, VS Code)     | `mcp-client-integration`           | Configure .mcp.json for stdio, HTTP, or Unix socket transport                                                                                    |
 
 ### CLI Commands for Deployment and Operations
 

package/catalog/frontmcp-deployment/references/build-for-mcpb.md

@@ -93,7 +93,7 @@ dist/mcpb/
 | `author`                                        | deployment.author → parsed `package.json.author` string (`"Name <email> (url)"`)    |
 | `license`, `homepage`, `repository`, `keywords` | deployment override → package.json fallback                                         |
 | `icon`                                          | deployment.icon → package.json.icon → `icon.png` / `assets/icon.png` in cwd         |
-| `tools`                                         | Schema extraction (system tools like `execute-job` filtered out)                    |
+| `tools`                                         | Schema extraction (system tools like `execute_job` filtered out)                    |
 | `prompts`                                       | Schema extraction; emitted with `prompts_generated: true`                           |
 | `user_config`                                   | Translated from `setup.steps` + deployment.userConfig overrides                     |
 | `compatibility.runtimes.node`                   | deployment.compatibility.runtimes.node → frontmcp.config.nodeVersion → `">=22.0.0"` |