fimo 0.21.0-staging.4 → 0.21.0-staging.5

package/assets/skills/fimo/SKILL.md

@@ -33,7 +33,7 @@ Pick by task:
 - Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
-- Project MCP setup — configure `fimo mcp` for a local agent → `fimo-cli` (`references/mcp.md`)
+- Remote MCP integrations — add, inspect, search, or run an MCP server → `fimo-cli` (`references/mcp.md`)
 - The Fimo Studio dashboard / web app UI → `fimo-studio`
 - Migrating an existing site into Fimo → `fimo-migration`
 

package/assets/skills/fimo-cli/SKILL.md

@@ -106,7 +106,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
 - "Create / scaffold / run / validate an agent / agent bundle / wire or enable its triggers / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
 - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
-- "Connect an agent to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
+- "Add, inspect, search, or run a remote MCP server / use `fimo mcp`" → `references/mcp.md`
 - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest Fimo conventions" → `references/agent-setup.md`
 - "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
 - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`

package/assets/skills/fimo-cli/references/integrations.md

@@ -2,6 +2,10 @@
 
 Use integrations to enable external services for a Fimo project. API keys are stored by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
+Start with `fimo integrations list` whenever the task could benefit from an external service. It is the project-scoped,
+runtime-truthful inventory; use `info` only for the relevant integration instead of loading every provider's tools into
+context.
+
 ## Inspect
 
 ```bash
@@ -14,6 +18,26 @@ fimo integrations status firecrawl
 
 When running inside an autonomous agent session, `fimo integrations list` shows the effective integrations available to that agent runtime, scoped by `.fimo/agents/<name>/config.yaml`. It lists only usable tools, plus the auth column and the config path that granted access.
 
+## Add a remote MCP server
+
+Remote MCP servers have a focused command group while remaining integrations underneath:
+
+```bash
+fimo mcp add sentry --url https://mcp.sentry.dev/mcp
+
+fimo mcp search "issue tracking"
+fimo mcp info sentry
+fimo mcp run sentry <tool> --input '{"key":"value"}'
+```
+
+Automatic discovery connects public endpoints directly and opens the provider authorization page for OAuth servers.
+Use `--auth none` to require a public endpoint, `--auth bearer --token-stdin` for a bearer token, or `--auth header
+--header-name <name> --token-stdin` for a custom private header. A custom header value is sent exactly as piped, so it
+carries any prefix itself. Fimo requires an HTTPS Streamable HTTP endpoint,
+encrypts credentials, assigns an `mcp_`-prefixed integration key, and reads the server's current tools live. OAuth and
+manual headers are alternative grants and are never sent together. Local stdio commands such as `npx` are not supported. Agents continue to use `fimo integrations list|info|run`
+so native and MCP providers share one runtime policy surface.
+
 ## Integration References
 
 Load the integration reference when the user names a specific integration:

package/assets/skills/fimo-cli/references/mcp.md

@@ -1,83 +1,124 @@
-# Project MCP
+# Remote MCP integrations
 
-The **Project MCP** lets an AI coding client use Fimo's project workflows through the Model Context Protocol. It is
-the same Fimo tool surface exposed in two ways:
+Use the `mcp` command group to connect a project to remote Model Context Protocol servers. Fimo stores the connection,
+keeps its credential server-side, and makes the server's tools available through the same integration gateway as native
+providers.
 
-- **Local MCP**: `fimo mcp` over stdio, for an AI client running next to a checkout.
-- **Remote MCP**: `https://api.fimo.ai/api/mcp` over authenticated Streamable HTTP, for ChatGPT, Claude, and other
-  clients that support OAuth.
+## Add a server
 
-The local and remote Project MCP modes share the same catalog. The public Docs MCP at
-`https://fimo.ai/docs/mcp` is separate: it is unauthenticated, read-only, and only provides Fimo documentation.
+Start with automatic discovery:
 
-## Set up the local MCP
+```bash
+fimo mcp add sentry --url https://mcp.sentry.dev/mcp
+```
 
-Authenticate the CLI first:
+Fimo connects public servers immediately. When the server advertises OAuth, Fimo opens its authorization page. Use
+`--no-open` to print the URL for a browser on another machine.
+
+Bearer token:
 
 ```bash
-fimo login
+printf '%s\n' "$MCP_TOKEN" | fimo mcp add sentry \
+  --url https://mcp.sentry.dev/mcp \
+  --auth bearer \
+  --token-stdin
 ```
 
-Then configure the MCP client to launch:
+Multiple custom headers:
 
-```text
-fimo mcp
+```bash
+printf '%s\n' "$MCP_HEADERS_JSON" | fimo mcp add internal \
+  --url https://mcp.example.com/mcp \
+  --auth header \
+  --header Authorization \
+  --header X-Workspace \
+  --headers-stdin
 ```
 
-For clients that accept a JSON command configuration, the equivalent entry is:
-
-```json
-{
-  "mcpServers": {
-    "fimo": {
-      "command": "npx",
-      "args": ["fimo@latest", "mcp"]
-    }
-  }
-}
+`MCP_HEADERS_JSON` must be one JSON object containing every configured header and no others, for example
+`{"Authorization":"Bearer abc123","X-Workspace":"workspace-secret"}`. Header names are matched case-insensitively.
+**Each value is the complete header value and is sent byte for byte**, so include any prefix the server expects. There
+is no scheme or prefix option; anything the header needs goes in the value.
+
+Use `--auth none` for a public endpoint or `--auth bearer --token-stdin` for a bearer token, which is the shortcut for
+sending `Authorization: Bearer <token>` from the token alone. The single-header form,
+`--auth header --header-name <name> --token-stdin`, pipes one complete header value.
+
+Fimo requires an HTTPS Streamable HTTP endpoint, validates the MCP handshake before saving it, encrypts the credentials,
+and never prints their values. The resulting integration key begins with `mcp_` so it cannot collide with a native
+provider.
+
+OAuth and manual credentials are alternative connection grants. Fimo never sends custom secret headers alongside an
+OAuth access token.
+
+## Reconnect OAuth
+
+If live discovery or execution reports that an OAuth connection needs authorization again:
+
+```bash
+fimo mcp reconnect sentry
 ```
 
-Do not add shell output or logging around the command: stdout is reserved for MCP JSON-RPC frames. Diagnostics are
-written to stderr.
+This replaces the organization-owned OAuth grant and requires organization admin access. Add `--no-open` to print the
+authorization URL.
 
-## Project and Branch scope
+## Rotate credentials
 
-When launched inside a linked Fimo project, `fimo mcp` reads the project from `.fimo.settings.json` and uses the
-current git branch as the default Branch. This keeps an AI client working against the same Branch as the checkout.
+Rotation replaces the complete credential bundle on the connection already enabled for this project:
 
-Outside a linked project, the server still works, but each project-scoped tool call must provide `projectId` and
-`env` (the compatibility-preserved wire field for a Branch name). The canonical catalog tool is `branches_list`;
-`envs_list` remains a compatibility alias. The client can also pass a Branch override when launching the CLI. Never
-edit `.fimo.settings.json` manually to change scope.
+```bash
+printf '%s\n' "$MCP_HEADERS_JSON" | fimo mcp rotate internal --headers-stdin
+printf '%s\n' "$MCP_TOKEN" | fimo mcp rotate sentry --token-stdin
+```
 
-The CLI credential represents the signed-in user's Fimo authority. If an MCP server is invoked from a Fimo agent
-session, the session's frozen capability snapshot still limits the operations available to that agent.
+Custom-header rotation requires the complete value of every configured header. It never merges a partial update, and
+neither command prints the submitted values. Rotation updates the organization-owned connection and requires organization admin access.
 
-## Capabilities
+## Discover servers and tools
 
-The Project MCP catalog covers:
+```bash
+fimo mcp list
+fimo mcp search "issue tracking"
+fimo mcp info sentry
+```
+
+- `list` shows only remote MCP integrations available to the current project.
+- `search` searches the live tool names and descriptions across those servers.
+- `info` shows one server's endpoint, authentication shape, and current live tool catalog.
+
+`info` and `run` accept either the short server name (`sentry`) or its complete integration key (`mcp_sentry`). The
+catalog is loaded live; Fimo does not persist or expose a stale copy to the model.
+
+## Run a tool
+
+```bash
+fimo mcp run sentry search_issues --input '{"query":"open regressions"}'
+fimo mcp run sentry projects_list
+fimo mcp run sentry search_issues --input @request.json
+```
+
+Omit `--input` when the tool takes no arguments. Use inline JSON, a project-relative `@file`, or `--input -` to read JSON
+from stdin.
 
-- **Identity and navigation** — current user, projects, and Branches.
-- **Content** — schemas, collection entries, search, create/update/delete, bounded bulk operations, and Singles.
-- **Labels** — list, read, set, batch-set, and delete localized labels.
-- **Media** — list and inspect assets, read canonical pages or ask one targeted question with `assets_read`, generate images or videos, create folders, move, and delete assets. Binary
-  upload remains `fimo assets upload`.
-- **Forms** — create, read, update, and delete forms; inspect submissions and statistics.
-- **Files** — read, glob, grep, write, edit, and delete project files within the scoped Branch. Sensitive files
-  such as credentials and `.env` files are excluded.
-- **Agents** — list agents, start a run, and inspect run status.
+## Studio and project agents
 
-Use the MCP client's tool list as the wire-level source of truth. The catalog is shared with the remote endpoint, so a
-client configured locally sees the same tool names and input shapes as a remote client.
+Remote MCP servers remain normal project integrations underneath the focused CLI. Studio chat and autonomous agents
+discover and run them through:
+
+```bash
+fimo integrations list
+fimo integrations info mcp_sentry
+fimo integrations run mcp_sentry search_issues --input '{"query":"open regressions"}'
+```
 
-## Local versus remote authorization
+An autonomous agent only sees integrations enabled in its committed `integrations:` policy. Studio receives a frozen
+snapshot of the integrations enabled when the turn starts. Neither surface receives the underlying credential or opens
+a direct connection to the remote server.
 
-Local MCP uses the stored CLI credential (or `FIMO_API_TOKEN` when explicitly configured). It does not use the
-browser OAuth consent screen. Remote MCP uses Fimo OAuth with `read`, `write`, and `agents` scopes; the user selects
-the optional capabilities during consent.
+## Supported servers
 
-In both modes, Fimo still checks the user's project permissions, Branch access, input validation, and file safety
-rules for every operation. MCP does not grant access to projects the user cannot already access.
+Remote connections support HTTPS Streamable HTTP servers with OAuth, no authentication, a bearer token, or custom
+private headers. Local stdio commands such as `npx`, arbitrary child processes, resources, and prompts are not supported.
 
-For ChatGPT, Claude, or another remote MCP client, use the setup guide in the public [MCP documentation](https://fimo.ai/docs/ai/mcp)
-instead of the local stdio configuration above.
+To connect ChatGPT, Claude, or another remote MCP client to Fimo itself, use Fimo's hosted Project MCP at
+`https://api.fimo.ai/api/mcp`. That is a separate direction from connecting a Fimo project to an external MCP server.

package/assets/skills/fimo-studio/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   Triggers: "in Fimo Studio", "in the dashboard", "in the web app",
   "how do I X in the UI", or screenshots of the dashboard. Topics
   covered: dashboard content and CMS, publishing from the dashboard,
-  dashboard SEO/domain settings, schedules and run history, outbound webhooks,
+  dashboard SEO/domain settings, project connections, schedules and run history, outbound webhooks,
   visual editing, version history UI, dashboard sharing/billing, dashboard chat,
   and the command palette. Never describe
   UI locations, buttons, or panels from memory — always read the relevant
@@ -41,6 +41,7 @@ Read the relevant reference file when the user's question matches a topic.
 | SEO Settings             | references/seo-settings.md              | "How do I set up SEO?", "Favicon, title, share image" |
 | Schedules                | references/schedules.md                 | "Recurring commands", "Run history", "Run now"        |
 | Webhooks                 | references/webhooks.md                  | "React to forms", "Send events to another service"    |
+| Connections              | references/connections.md               | "Connect a service", "Add an MCP server"              |
 | Preview & Responsive     | references/preview-and-responsive.md    | "How does it look on mobile?", "How do I test sizes?" |
 | Visual Editing           | references/visual-editing.md            | "Can I edit visually?", "How do I change colors?"     |
 | Version History          | references/version-history.md           | "How do I undo?", "How do I go back?"                 |
@@ -58,6 +59,7 @@ Read the relevant reference file when the user's question matches a topic.
 | Adding images           | Media Library, AI Chat, Edit Mode                                              |
 | Content/CMS             | AI Chat, Media Library                                                         |
 | Webhooks                | Project secrets, Forms, Publishing, Agents                                     |
+| Connections             | AI Chat, Agents, Project secrets                                               |
 | Schedules               | Project secrets, Environments, Agents                                          |
 | Visual changes          | Edit Mode (quick tweaks), AI Chat (bigger changes), Code Editor (full control) |
 | Something went wrong    | Version History, AI Chat                                                       |

package/assets/skills/fimo-studio/references/connections.md

@@ -0,0 +1,52 @@
+# Connections
+
+Connections let a project use external services without exposing credentials to editors, chat, or agents. Studio, the
+CLI, and project agents all resolve the same project-scoped connection state.
+
+## See what is available
+
+1. Open the project.
+2. Open **More**, then **Settings**.
+3. Choose **Connections**.
+
+The page has two groups:
+
+- **Services** are integrations maintained by Fimo, such as Firecrawl, Fal, and Slack.
+- **MCP servers** are remote servers installed for this project. Choose **Add MCP server** beside this group to add one.
+
+Each row shows whether the connection is enabled, disabled, or needs attention. Open a row to enable or disable it for
+the current project, inspect its endpoint and live tools, or perform the repair appropriate to its authentication.
+
+## Add an MCP server
+
+Choose **Add MCP server** to open one setup flow:
+
+1. Pick a recommended server, choose **Custom MCP server**, or, if you are an organization owner or admin, choose
+   **Use from another project**.
+2. Recommended servers fill their name and endpoint. A custom server asks for a name and Streamable HTTP HTTPS URL.
+3. **Connect with** offers the recommended sign-in path. Fimo checks the endpoint; public servers connect immediately,
+   while OAuth servers open their provider sign-in page and return after approval.
+4. Open **Other ways to connect** when the server instead documents a bearer token, one or more custom headers, or no
+   authentication.
+
+For **Paste an access token**, enter only the token; Fimo adds the `Bearer` scheme. For **Send custom headers**, enter
+each complete value exactly as the server expects, including any prefix (`Authorization` with `Bearer abc123`). Fimo
+encrypts every saved grant and never shows its private value again.
+
+**Use from another project** does not make other projects' servers generally visible. It is an explicit admin-only
+picker that attaches an existing organization Connection to this project without revealing or copying its credential.
+
+Each authentication method has one repair:
+
+- **Reconnect** signs in again for OAuth.
+- **Update credentials** replaces a bearer token or the complete custom-header bundle after it stops working.
+- **Rotate credentials** replaces a healthy token or header bundle proactively.
+- **Retry connection** asks a public server for its tools again without touching any credential.
+
+Only organization owners and admins can replace a shared credential. OAuth and manual secret headers are never sent
+together.
+
+After the server is added, its detail shows the endpoint and the tools Fimo discovered. Only enabled servers become
+available to Studio chat, autonomous agents, and the Fimo CLI for this project. Agents should discover them with
+`fimo integrations list`, inspect them with `fimo integrations info <integration>`, and run an allowed tool with
+`fimo integrations run <integration> <tool>`.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-23T14:49:49.653Z",
+  "bundledAt": "2026-08-23T18:29:50.492Z",
   "cliVersion": "0.20.0",
   "external": [
     "oxc-parser",