@frontmcp/skills 1.0.4 → 1.1.0

package/catalog/frontmcp-deployment/examples/mcp-client-integration/http-remote.md

@@ -0,0 +1,106 @@
+---
+name: http-remote
+reference: mcp-client-integration
+level: basic
+description: Connect an MCP client to a FrontMCP server running as an HTTP server, locally or remotely.
+tags: [deployment, http, mcp-client, remote, cloud, production]
+features:
+  - Connecting to a local FrontMCP dev server on a custom port
+  - Connecting to a remote production FrontMCP server with authentication
+  - Configuring HTTP transport in Claude Code and Claude Desktop
+  - Using a background daemon on a TCP port for persistent local access
+---
+
+# Connect to a FrontMCP HTTP Server
+
+Connect an MCP client to a FrontMCP server running as an HTTP server, locally or remotely.
+
+## Code
+
+### Local development
+
+```bash
+# Start the server on port 3005
+my-server serve -p 3005
+```
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "http",
+      "url": "http://localhost:3005/mcp"
+    }
+  }
+}
+```
+
+### Production (remote server with auth)
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "http",
+      "url": "https://my-server.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer your-token-here"
+      }
+    }
+  }
+}
+```
+
+### Background daemon on port
+
+```bash
+# Start as a background daemon on port 4000
+my-server daemon start -p 4000
+
+# Verify it's running
+my-server daemon status
+# → Running (PID: 12345, started: 2025-01-01T00:00:00.000Z, port: 4000)
+
+# View logs
+my-server daemon logs
+
+# Stop when done
+my-server daemon stop
+```
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "http",
+      "url": "http://localhost:4000/mcp"
+    }
+  }
+}
+```
+
+### Serverless (Vercel, AWS Lambda)
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "http",
+      "url": "https://my-server.vercel.app/mcp"
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Connecting to a local FrontMCP dev server on a custom port
+- Connecting to a remote production FrontMCP server with authentication
+- Configuring HTTP transport in Claude Code and Claude Desktop
+- Using a background daemon on a TCP port for persistent local access
+
+## Related
+
+- See `mcp-client-integration` for the full MCP client configuration reference
+- See `deploy-to-node` for production HTTP server deployment
+- See `deploy-to-vercel` for serverless deployment

package/catalog/frontmcp-deployment/examples/mcp-client-integration/stdio-binary-with-env.md

@@ -0,0 +1,107 @@
+---
+name: stdio-binary-with-env
+reference: mcp-client-integration
+level: intermediate
+description: Configure a local FrontMCP CLI binary with environment variables and custom arguments in MCP client configs.
+tags: [deployment, stdio, cli, binary, env, mcp-client, configuration]
+features:
+  - Pointing MCP clients at a locally installed FrontMCP binary
+  - Passing database URLs, API keys, and feature flags via environment variables
+  - Using absolute paths for reliable binary resolution
+  - Configuring different environments (dev, staging) via env vars
+---
+
+# Local Binary with Environment Variables
+
+Configure a local FrontMCP CLI binary with environment variables and custom arguments in MCP client configs.
+
+## Code
+
+### Install and build the binary
+
+```bash
+# Build the CLI binary
+frontmcp build --target cli
+
+# Install it (creates symlink in ~/.local/bin/)
+my-server install
+```
+
+### Development configuration
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server-dev": {
+      "command": "/Users/you/.local/bin/my-server",
+      "args": ["--stdio"],
+      "env": {
+        "DATABASE_URL": "postgresql://localhost:5432/mydb_dev",
+        "REDIS_URL": "redis://localhost:6379",
+        "API_KEY": "sk-dev-xxxxx",
+        "LOG_LEVEL": "debug",
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+### Staging configuration
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "my-server-staging": {
+      "command": "/Users/you/.local/bin/my-server",
+      "args": ["--stdio"],
+      "env": {
+        "DATABASE_URL": "postgresql://staging-db.example.com:5432/mydb",
+        "REDIS_URL": "redis://staging-redis.example.com:6379",
+        "API_KEY": "sk-staging-xxxxx",
+        "LOG_LEVEL": "warn",
+        "NODE_ENV": "staging"
+      }
+    }
+  }
+}
+```
+
+### Multiple servers in one config
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "backend-tools": {
+      "command": "/Users/you/.local/bin/backend-server",
+      "args": ["--stdio"],
+      "env": {
+        "DATABASE_URL": "postgresql://localhost:5432/backend"
+      }
+    },
+    "docs-tools": {
+      "command": "npx",
+      "args": ["-y", "docs-mcp-server", "--stdio"],
+      "env": {
+        "DOCS_PATH": "/Users/you/docs"
+      }
+    },
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/mcp"
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Pointing MCP clients at a locally installed FrontMCP binary
+- Passing database URLs, API keys, and feature flags via environment variables
+- Using absolute paths for reliable binary resolution
+- Configuring different environments (dev, staging) via env vars
+
+## Related
+
+- See `mcp-client-integration` for the full MCP client configuration reference
+- See `build-for-cli` for CLI build and installation options

package/catalog/frontmcp-deployment/examples/mcp-client-integration/stdio-npx.md

@@ -0,0 +1,89 @@
+---
+name: stdio-npx
+reference: mcp-client-integration
+level: basic
+description: Publish a FrontMCP server to npm and configure MCP clients to use it with npx --stdio.
+tags: [deployment, stdio, npx, npm, mcp-client, claude-code, claude-desktop]
+features:
+  - Building a FrontMCP server as a distributable CLI bundle
+  - Configuring package.json bin field for npx execution
+  - Setting up Claude Code, Claude Desktop, and Cursor to use the server via stdio
+  - Passing environment variables from MCP client config to the server
+---
+
+# Publish and Use via npx --stdio
+
+Publish a FrontMCP server to npm and configure MCP clients to use it with npx --stdio.
+
+## Code
+
+### 1. Build the CLI bundle
+
+```bash
+frontmcp build --target cli --js
+```
+
+### 2. Configure package.json
+
+```json
+{
+  "name": "my-weather-mcp",
+  "version": "1.0.0",
+  "description": "Weather data MCP server",
+  "bin": {
+    "my-weather-mcp": "./dist/my-weather-mcp-cli.bundle.js"
+  },
+  "files": ["dist/"],
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0"
+  }
+}
+```
+
+### 3. Publish to npm
+
+```bash
+npm publish
+```
+
+### 4. Configure MCP clients
+
+```json Claude Code (.mcp.json)
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "my-weather-mcp", "--stdio"],
+      "env": {
+        "WEATHER_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+```json Claude Desktop (claude_desktop_config.json)
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "my-weather-mcp", "--stdio"],
+      "env": {
+        "WEATHER_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Building a FrontMCP server as a distributable CLI bundle
+- Configuring package.json bin field for npx execution
+- Setting up Claude Code, Claude Desktop, and Cursor to use the server via stdio
+- Passing environment variables from MCP client config to the server
+
+## Related
+
+- See `mcp-client-integration` for the full MCP client configuration reference
+- See `build-for-cli` for CLI build options and SEA binary creation

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

@@ -0,0 +1,209 @@
+---
+name: build-for-mcpb
+description: Package a FrontMCP server as a .mcpb archive that Claude Desktop and other MCPB-aware clients install with one click
+---
+
+# Building an MCP Bundle (MCPB)
+
+Package your FrontMCP server as a `.mcpb` archive conforming to the
+[MCPB v0.3 spec](https://github.com/modelcontextprotocol/mcpb). Consumers
+double-click the file — the host client extracts it and runs the server over
+stdio. Metadata, tools, prompts, user-configurable inputs, and per-platform
+runtime overrides are all declared statically in `manifest.json`.
+
+## When to Use This Skill
+
+### Must Use
+
+- Distributing an MCP server to end users who install via Claude Desktop,
+  Cursor, or another MCPB-aware client — no CLI, no `npx`, no registry.
+- Attaching a single signed artifact with a stable hash to a GitHub release.
+- Exposing install-time configuration (tokens, paths, toggles) through the
+  client's native install dialog via `user_config`.
+
+### Recommended
+
+- Shipping optional platform-specific binaries so users without Node installed
+  can still run the server.
+- Producing reproducible builds — MCPB archives are deterministic by default
+  (same inputs → byte-identical output → matching SHA-256).
+
+### Skip When
+
+- You need an interactive CLI with subcommands per tool — use `build-for-cli`.
+- You're hosting the server yourself over HTTP — use `deploy-to-node` or a
+  serverless target (`deploy-to-vercel`, `deploy-to-lambda`, `deploy-to-cloudflare`).
+- You're embedding tools in an existing Node.js application — use `build-for-sdk`.
+
+> **Decision:** Choose `build-for-mcpb` when users install your server through
+> an MCPB-aware client; choose `build-for-cli` for terminal-first distribution.
+
+## Build Commands
+
+```bash
+# Basic bundle — dist/mcpb/{name}-{version}.mcpb
+frontmcp build --target mcpb
+
+# Include a SEA binary for the host platform
+frontmcp build --target mcpb --sea
+
+# Merge pre-built cross-platform binaries from CI
+frontmcp build --target mcpb --merge-from ./ci-bins
+
+# Skip zipping and inspect the staging directory
+frontmcp build --target mcpb --stage-only
+
+# Validate a produced archive
+frontmcp mcpb validate dist/mcpb/my-server-1.0.0.mcpb
+```
+
+## Requirements
+
+- **Node.js ≥ 22** at build time.
+- The entry file must export or instantiate a `@FrontMcp`-decorated class
+  (the build-time schema extractor boots it in introspection mode).
+- `@frontmcp/sdk` must be installed and reachable at the path used by the
+  build (never exclude it from bundling).
+- For `--sea` builds, Node.js ≥ 24 is required (FrontMCP targets the current SEA API).
+
+## What the Archive Contains
+
+```text
+dist/mcpb/
+  my-server-1.0.0.mcpb              # the distributable artifact
+  __stage/                          # removed after successful zip
+    manifest.json                   # MCPB v0.3 manifest (generated)
+    server/
+      index.js                      # esbuild single-file CJS bundle
+      package.json                  # minimal { type: "commonjs" } marker
+      _skills/                      # when capabilities.skills
+    bin/                            # when --sea or --merge-from
+      darwin-arm64/my-server
+      win32-x64/my-server.exe
+    icon.png                        # when resolved
+    README.md                       # when present in project root
+```
+
+## Manifest Sources
+
+| MCPB field                                      | Source (priority order)                                                             |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `name`, `version`                               | frontmcp.config → package.json                                                      |
+| `description`                                   | deployment.longDescription first line → package.json.description                    |
+| `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)                    |
+| `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"` |
+| `compatibility.platforms`                       | deployment.compatibility.platforms → `["darwin","linux","win32"]`                   |
+
+## Setup Steps → user_config + env
+
+If your exec config declares a `setup.steps` questionnaire, each step becomes
+an MCPB `user_config` entry and a matching `mcp_config.env` variable wired via
+`${user_config.KEY}` substitution.
+
+Type resolution:
+
+| FrontMCP schema                                      | MCPB `type`           |
+| ---------------------------------------------------- | --------------------- |
+| `z.string()`                                         | `string`              |
+| `z.number()` / `z.number().int()`                    | `number`              |
+| `z.boolean()`                                        | `boolean`             |
+| `z.array(z.string())`                                | `string` + `multiple` |
+| `deployment.userConfig.X.type: 'directory'` override | `directory`           |
+| `deployment.userConfig.X.type: 'file'` override      | `file`                |
+
+Secrets: defaults are stripped when `sensitive: true` so tokens never appear
+in the manifest.
+
+Unsupported: `showWhen` / `next` branching — MCPB forms are flat; the
+generator logs a warning and renders every step unconditionally.
+
+## Cross-Platform Binaries
+
+Node SEA builds for the host OS/arch only. To ship a `.mcpb` that runs
+binary-only on every platform, run the build in a CI matrix and assemble with
+`--merge-from`:
+
+```text
+ci-bins/
+  darwin-arm64/my-server
+  darwin-x64/my-server
+  linux-x64/my-server
+  win32-x64/my-server.exe
+```
+
+Platforms without a binary automatically fall through to the Node command +
+bundled JS, so a partial matrix is fine.
+
+## Common Patterns
+
+| Pattern                 | Correct                                    | Incorrect                    | Why                                                             |
+| ----------------------- | ------------------------------------------ | ---------------------------- | --------------------------------------------------------------- |
+| Entry path              | `${__dirname}/server/index.js`             | Absolute host path           | Host app extracts to a fresh tmp dir each install               |
+| User config reference   | `${user_config.apiToken}`                  | `$API_TOKEN`                 | MCPB substitution happens at install time, not shell expansion  |
+| Sensitive defaults      | Omit `default`                             | Emit the real token          | Manifests ship in plaintext; anything in `default` is committed |
+| External services       | Declare in `privacy_policies`              | Omit                         | Stores/clients surface these during install review              |
+| Multi-platform binaries | CI matrix + `--merge-from`                 | Build on one OS and ship     | SEA binaries are OS/arch-specific                               |
+| Prompt `text`           | Leave empty, set `prompts_generated: true` | Try to serialize `execute()` | JS logic doesn't fit MCPB's static `${arguments.KEY}` template  |
+
+## Verification Checklist
+
+**Build**
+
+- [ ] `frontmcp build --target mcpb` exits 0
+- [ ] `dist/mcpb/{name}-{version}.mcpb` exists and is a valid ZIP
+- [ ] Archive size is reasonable (< 50 MB typical; warn-threshold fires at 50 MB)
+- [ ] Two back-to-back builds produce identical SHA-256 (deterministic mode on)
+
+**Manifest**
+
+- [ ] `manifest_version: "0.3"`
+- [ ] `server.entry_point` matches the file present in the archive
+- [ ] Every `${user_config.KEY}` reference has a matching `user_config[KEY]`
+- [ ] No `${…}` substitutions outside the allow-list
+
+**Install**
+
+- [ ] Opening the `.mcpb` in Claude Desktop shows the expected name, description, author, tools
+- [ ] `user_config` form renders with correct titles / descriptions / default values
+- [ ] Server starts over stdio and answers `initialize` / `tools/list`
+
+## Troubleshooting
+
+| Problem                                                | Cause                                                          | Solution                                                                                                                    |
+| ------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `@frontmcp/sdk is required for schema extraction`      | SDK missing or externalized from bundle                        | Ensure `@frontmcp/sdk` is installed                                                                                         |
+| Archive > 100 MB                                       | node_modules bundled or node runtime bloated                   | Tune `build.esbuild.external`, drop `--sea`, or disable `includeNodeModules`                                                |
+| `Unknown substitution variable` on validate            | Typo in `mcp_config.args` / `env`                              | Only `__dirname`, `HOME`, `DESKTOP`, `DOCUMENTS`, `DOWNLOADS`, `pathSeparator`, and declared `user_config` keys are allowed |
+| `entry_point is not present in archive`                | Custom `--entry` flag or bundler moved the file                | Re-run without the override, or update the config's `entry`                                                                 |
+| Two builds produce different SHA-256                   | `--no-deterministic` set, or inputs embed a changing timestamp | Restore deterministic mode; scan your sources for live date/time values                                                     |
+| `platform_overrides.{platform}.command` missing binary | `--merge-from` folders don't match MCPB platform keys          | See the expected layout below                                                                                               |
+
+Expected `--merge-from` layout (platform dirs must match MCPB platform keys):
+
+```text
+{dir}/
+  darwin-arm64/{name}
+  darwin-x64/{name}
+  linux-arm64/{name}
+  linux-x64/{name}
+  win32-x64/{name}.exe
+```
+
+## Examples
+
+| Example                                                                | Level | Description                                                                                    |
+| ---------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------- |
+| [`mcpb-bundle-build`](../examples/build-for-mcpb/mcpb-bundle-build.md) | Basic | Produce a .mcpb archive for Claude Desktop with metadata, tools, and install-time user_config. |
+
+> See all examples in [`examples/build-for-mcpb/`](../examples/build-for-mcpb/)
+
+## Reference
+
+- **MCPB spec:** <https://github.com/modelcontextprotocol/mcpb>
+- **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/mcpb>
+- **Related skills:** `build-for-cli`, `build-for-sdk`, `mcp-client-integration`

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

@@ -61,8 +61,7 @@ class MySDK {}
 The `create()` factory spins up a server from a flat config object — no decorators or classes needed:
 
 ```typescript
-import { create } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { create, z } from '@frontmcp/sdk';
 
 const server = await create({
   info: { name: 'my-service', version: '1.0.0' },