@ferrlabs/mcp 4.0.0 → 5.1.0

package/LICENSE

@@ -1,21 +1,373 @@
-MIT License
-
-Copyright 2024-present FerrLabs Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -10,21 +10,36 @@
 
 Add to your MCP client configuration (Claude Code, Cursor, etc.):
 
+```json
+{
+  "mcpServers": {
+    "ferrlabs": {
+      "command": "npx",
+      "args": ["-y", "@ferrlabs/mcp"]
+    }
+  }
+}
+```
+
+The first time you call a tool that needs auth, the MCP opens `auth.ferrlabs.com` in your default browser (OAuth 2.0 loopback PKCE). After you click Allow, the token is saved locally and reused for future sessions. No env var required.
+
+### CI / scripted / headless use
+
+Bypass the browser dance by injecting a token directly:
+
 ```json
 {
   "mcpServers": {
     "ferrlabs": {
       "command": "npx",
       "args": ["-y", "@ferrlabs/mcp"],
-      "env": {
-        "FERRLABS_API_TOKEN": "fl_..."
-      }
+      "env": { "FERRLABS_API_TOKEN": "fl_..." }
     }
   }
 }
 ```
 
-Create a token from `app.ferrlabs.com` (Settings → API Tokens) and assign the scopes you want the assistant to have. The token is forwarded as `x-api-token` to `api.ferrlabs.com`.
+Create the token from `app.ferrlabs.com` → Settings → API Tokens. It's forwarded as `x-api-token` to `api.ferrlabs.com`.
 
 ## Available Tools
 
@@ -55,11 +70,26 @@ FerrFlow CLI-specific tools (`dry_run`, `validate_config`, `read_config`, `read_
 
 ## Configuration
 
-| Variable             | Description                                                                  | Default                    |
-| -------------------- | ---------------------------------------------------------------------------- | -------------------------- |
-| `API_URL`            | FerrLabs API base URL (no `/v1` suffix — paths are prefixed in code)         | `https://api.ferrlabs.com` |
-| `FERRLABS_API_TOKEN` | FerrLabs API token (required for authenticated tools)                        | —                          |
-| `FERRFLOW_API_TOKEN` | **Deprecated** — accepted as a fallback for backward compatibility with v3.x | —                          |
+| Variable                  | Description                                                                           | Default                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `API_URL`                 | FerrLabs API base URL (no `/v1` suffix — paths are prefixed in code)                  | `https://api.ferrlabs.com`                                                |
+| `FERRLABS_AUTH_URL`       | Auth SPA base URL (where the OAuth browser flow lands)                                | `https://auth.ferrlabs.com`                                               |
+| `FERRLABS_API_TOKEN`      | Pre-provisioned token. Bypasses the OAuth flow. Use for CI / scripted environments.   | —                                                                         |
+| `FERRFLOW_API_TOKEN`      | **Deprecated** — accepted as a fallback for backward compatibility with v3.x.         | —                                                                         |
+| `FERRLABS_MCP_NO_OAUTH`   | Set to `1` to disable the OAuth fallback. Then `FERRLABS_API_TOKEN` becomes required. | unset                                                                     |
+| `FERRLABS_MCP_TOKEN_PATH` | Override the path where the OAuth-acquired token is persisted.                        | `%APPDATA%\ferrlabs\mcp\token.json` / `~/.config/ferrlabs/mcp/token.json` |
+| `FERRLABS_MCP_NO_PERSIST` | Set to `1` to keep the token in memory only (re-auth on every cold start).            | unset                                                                     |
+
+### How auth resolution works
+
+On the first authenticated tool call, the MCP looks for a token in this order:
+
+1. In-memory cache (set during this MCP process's lifetime)
+2. `FERRLABS_API_TOKEN` (or `FERRFLOW_API_TOKEN`) env var
+3. Persisted token file (`FERRLABS_MCP_TOKEN_PATH`)
+4. **OAuth 2.0 loopback PKCE flow** — opens the user's browser, captures the callback on `http://127.0.0.1:54321/cb`, exchanges the code for a session token via `POST /v1/auth/exchange`. Token is persisted to step 3 for future sessions.
+
+If you set `FERRLABS_MCP_NO_OAUTH=1`, step 4 is skipped — useful for CI where opening a browser would hang.
 
 ## Smoke test
 
@@ -86,4 +116,4 @@ Tokens issued by the legacy FerrFlow-only API are not valid against the unified
 
 ## License
 
-MIT
+Mozilla Public License 2.0 — see [LICENSE](LICENSE).

package/dist/auth/__tests__/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/auth/__tests__/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../src/auth/__tests__/index.test.ts"],"names":[],"mappings":""}

package/dist/auth/__tests__/index.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+describe('getToken', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        vi.resetModules();
+        process.env = { ...originalEnv };
+        delete process.env.FERRLABS_API_TOKEN;
+        delete process.env.FERRFLOW_API_TOKEN;
+        delete process.env.FERRLABS_MCP_NO_OAUTH;
+        process.env.FERRLABS_MCP_NO_PERSIST = '1';
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it('returns FERRLABS_API_TOKEN when set, without touching persistence or OAuth', async () => {
+        process.env.FERRLABS_API_TOKEN = 'fl_env_token';
+        const { getToken } = await import('../index.js');
+        expect(await getToken()).toBe('fl_env_token');
+    });
+    it('falls back to FERRFLOW_API_TOKEN (legacy compat)', async () => {
+        process.env.FERRFLOW_API_TOKEN = 'fl_legacy_token';
+        const { getToken } = await import('../index.js');
+        expect(await getToken()).toBe('fl_legacy_token');
+    });
+    it('throws when no token and FERRLABS_MCP_NO_OAUTH=1', async () => {
+        process.env.FERRLABS_MCP_NO_OAUTH = '1';
+        const { getToken } = await import('../index.js');
+        await expect(getToken()).rejects.toThrow(/FERRLABS_API_TOKEN environment variable is required/);
+    });
+    it('caches the token across calls (env path)', async () => {
+        process.env.FERRLABS_API_TOKEN = 'fl_cached';
+        const { getToken } = await import('../index.js');
+        const a = await getToken();
+        process.env.FERRLABS_API_TOKEN = 'fl_changed';
+        const b = await getToken();
+        expect(a).toBe(b);
+        expect(a).toBe('fl_cached');
+    });
+});

package/dist/auth/__tests__/oauth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth.test.d.ts.map

package/dist/auth/__tests__/oauth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.test.d.ts","sourceRoot":"","sources":["../../../src/auth/__tests__/oauth.test.ts"],"names":[],"mappings":""}

package/dist/auth/__tests__/oauth.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { generatePkcePair } from '../oauth.js';
+import { createHash } from 'node:crypto';
+describe('generatePkcePair', () => {
+    it('returns a verifier between 43 and 128 chars (RFC 7636)', () => {
+        const { verifier } = generatePkcePair();
+        expect(verifier.length).toBeGreaterThanOrEqual(43);
+        expect(verifier.length).toBeLessThanOrEqual(128);
+    });
+    it('returns a challenge that is SHA-256(verifier) base64url-encoded', () => {
+        const { verifier, challenge } = generatePkcePair();
+        const expected = createHash('sha256').update(verifier).digest('base64url');
+        expect(challenge).toBe(expected);
+    });
+    it('returns different verifier+challenge pairs each call', () => {
+        const a = generatePkcePair();
+        const b = generatePkcePair();
+        expect(a.verifier).not.toBe(b.verifier);
+        expect(a.challenge).not.toBe(b.challenge);
+    });
+    it('returns base64url-encoded values (no +, /, =)', () => {
+        const { verifier, challenge } = generatePkcePair();
+        expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/);
+        expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+});

package/dist/auth/index.d.ts

@@ -0,0 +1,3 @@
+export declare function getToken(): Promise<string>;
+export declare function resetTokenCacheForTesting(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAMA,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAgChD;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}

package/dist/auth/index.js

@@ -0,0 +1,36 @@
+import { readPersistedToken, writePersistedToken } from './persistence.js';
+import { runLoopbackOauthFlow } from './oauth.js';
+let cached = null;
+let inFlight = null;
+export async function getToken() {
+    if (cached)
+        return cached;
+    const envToken = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
+    if (envToken) {
+        cached = envToken;
+        return envToken;
+    }
+    const persisted = await readPersistedToken();
+    if (persisted) {
+        cached = persisted;
+        return persisted;
+    }
+    if (process.env.FERRLABS_MCP_NO_OAUTH === '1') {
+        throw new Error('FERRLABS_API_TOKEN environment variable is required (FERRLABS_MCP_NO_OAUTH=1 disables the OAuth fallback).');
+    }
+    if (!inFlight) {
+        inFlight = (async () => {
+            const { token } = await runLoopbackOauthFlow();
+            await writePersistedToken(token);
+            cached = token;
+            return token;
+        })().finally(() => {
+            inFlight = null;
+        });
+    }
+    return inFlight;
+}
+export function resetTokenCacheForTesting() {
+    cached = null;
+    inFlight = null;
+}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,12 @@
+interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+export declare function generatePkcePair(): PkcePair;
+export interface RunLoopbackFlowResult {
+    token: string;
+    scope?: string;
+}
+export declare function runLoopbackOauthFlow(): Promise<RunLoopbackFlowResult>;
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAWA,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C;AA4FD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CA+C3E"}

package/dist/auth/oauth.js

@@ -0,0 +1,123 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+const AUTH_BASE = process.env.FERRLABS_AUTH_URL ?? 'https://auth.ferrlabs.com';
+const API_BASE = process.env.API_URL ?? 'https://api.ferrlabs.com';
+const CLIENT_ID = 'mcp';
+const REDIRECT_PORTS = [54321, 54322];
+const AUTH_TIMEOUT_MS = 2 * 60 * 1000;
+export function generatePkcePair() {
+    const verifier = randomBytes(64).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+function generateState() {
+    return randomBytes(16).toString('base64url');
+}
+function openBrowser(url) {
+    const args = (() => {
+        switch (platform()) {
+            case 'win32':
+                return { cmd: 'cmd', args: ['/c', 'start', '""', url] };
+            case 'darwin':
+                return { cmd: 'open', args: [url] };
+            default:
+                return { cmd: 'xdg-open', args: [url] };
+        }
+    })();
+    const child = spawn(args.cmd, args.args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {
+        // ignore — caller will time out and surface the URL via error
+    });
+    child.unref();
+}
+function listenForCallback(port, expectedState) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            try {
+                const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+                if (url.pathname !== '/cb') {
+                    res.writeHead(404).end('Not found');
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                const state = url.searchParams.get('state');
+                if (!code || !state) {
+                    res.writeHead(400).end('Missing code or state');
+                    return;
+                }
+                if (state !== expectedState) {
+                    res.writeHead(400).end('state mismatch');
+                    reject(new Error('OAuth callback state mismatch (CSRF protection triggered)'));
+                    server.close();
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', Connection: 'close' });
+                res.end("<!doctype html><html><body style='font-family:sans-serif;padding:2rem;color:#1e293b'><h1>Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
+                setImmediate(() => server.close());
+                resolve({ code, state });
+            }
+            catch (err) {
+                res.writeHead(500).end('Internal error');
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        server.on('error', reject);
+        server.listen(port, '127.0.0.1');
+    });
+}
+async function exchangeCodeForToken(code, codeVerifier, redirectUri) {
+    const res = await fetch(`${API_BASE}/v1/auth/exchange`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'User-Agent': 'ferrlabs-mcp/oauth' },
+        body: JSON.stringify({
+            code,
+            client_id: CLIENT_ID,
+            redirect_uri: redirectUri,
+            code_verifier: codeVerifier,
+        }),
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`OAuth exchange failed (HTTP ${res.status}): ${body.error ?? body.message ?? 'unknown'}`);
+    }
+    const data = (await res.json());
+    if (!data.token)
+        throw new Error('OAuth exchange returned no token');
+    return data.token;
+}
+export async function runLoopbackOauthFlow() {
+    const pkce = generatePkcePair();
+    const state = generateState();
+    let port = null;
+    let callbackPromise = null;
+    for (const candidate of REDIRECT_PORTS) {
+        try {
+            callbackPromise = listenForCallback(candidate, state);
+            port = candidate;
+            break;
+        }
+        catch {
+            callbackPromise = null;
+        }
+    }
+    if (port === null || !callbackPromise) {
+        throw new Error(`Could not bind any of the loopback ports (${REDIRECT_PORTS.join(', ')}). Close whatever is using them and retry.`);
+    }
+    const redirectUri = `http://127.0.0.1:${port}/cb`;
+    const authorizeUrl = new URL(`${AUTH_BASE}/authorize`);
+    authorizeUrl.searchParams.set('client_id', CLIENT_ID);
+    authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+    authorizeUrl.searchParams.set('response_type', 'code');
+    authorizeUrl.searchParams.set('code_challenge', pkce.challenge);
+    authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+    authorizeUrl.searchParams.set('state', state);
+    openBrowser(authorizeUrl.toString());
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`OAuth flow timed out after ${AUTH_TIMEOUT_MS / 1000}s. If your browser didn't open, visit: ${authorizeUrl.toString()}`)), AUTH_TIMEOUT_MS);
+    });
+    const { code } = await Promise.race([callbackPromise, timeoutPromise]);
+    const token = await exchangeCodeForToken(code, pkce.verifier, redirectUri);
+    return { token };
+}

package/dist/auth/persistence.d.ts

@@ -0,0 +1,4 @@
+export declare function readPersistedToken(): Promise<string | null>;
+export declare function writePersistedToken(token: string, scopes?: string[]): Promise<void>;
+export declare function clearPersistedToken(): Promise<void>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/auth/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/auth/persistence.ts"],"names":[],"mappings":"AAmCA,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYjE;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBzF;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOzD"}

package/dist/auth/persistence.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir, platform } from 'node:os';
+function defaultTokenPath() {
+    const override = process.env.FERRLABS_MCP_TOKEN_PATH;
+    if (override)
+        return override;
+    const home = homedir();
+    switch (platform()) {
+        case 'win32':
+            return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'ferrlabs', 'mcp', 'token.json');
+        case 'darwin':
+            return join(home, 'Library', 'Application Support', 'ferrlabs', 'mcp', 'token.json');
+        default:
+            return join(process.env.XDG_CONFIG_HOME ?? join(home, '.config'), 'ferrlabs', 'mcp', 'token.json');
+    }
+}
+export async function readPersistedToken() {
+    if (process.env.FERRLABS_MCP_NO_PERSIST === '1')
+        return null;
+    try {
+        const raw = await readFile(defaultTokenPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.token === 'string' && parsed.token.length > 0) {
+            return parsed.token;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writePersistedToken(token, scopes) {
+    if (process.env.FERRLABS_MCP_NO_PERSIST === '1')
+        return;
+    const path = defaultTokenPath();
+    await mkdir(dirname(path), { recursive: true });
+    const payload = {
+        token,
+        obtained_at: new Date().toISOString(),
+        scopes,
+    };
+    await writeFile(path, JSON.stringify(payload, null, 2), 'utf8');
+    if (platform() !== 'win32') {
+        try {
+            await chmod(path, 0o600);
+        }
+        catch {
+            // ignore — best effort on platforms that don't support POSIX modes
+        }
+    }
+}
+export async function clearPersistedToken() {
+    const { unlink } = await import('node:fs/promises');
+    try {
+        await unlink(defaultTokenPath());
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/tools/issues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/tools/issues.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgCpE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QA+BpD"}
+{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/tools/issues.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBpE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QA+BpD"}

package/dist/tools/issues.js

@@ -1,12 +1,6 @@
 import { z } from 'zod';
 import { apiRequest } from './api-client.js';
-const API_TOKEN = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
-function requireToken() {
-    if (!API_TOKEN) {
-        throw new Error('FERRLABS_API_TOKEN environment variable is required for authenticated operations.');
-    }
-    return API_TOKEN;
-}
+import { getToken } from '../auth/index.js';
 export function registerIssuesTools(server) {
     server.tool('list_issues', 'List FerrTrack issues for a project (FerrTrack — issue tracker)', {
         org_slug: z.string().min(1).describe('Organization slug'),
@@ -20,7 +14,7 @@ export function registerIssuesTools(server) {
             .optional()
             .describe('Items per page (default 25, max 100)'),
     }, async ({ org_slug, project_slug, page, per_page }) => {
-        const token = requireToken();
+        const token = await getToken();
         const params = new URLSearchParams();
         if (page !== undefined)
             params.set('page', String(page));

package/dist/tools/orgs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orgs.d.ts","sourceRoot":"","sources":["../../src/tools/orgs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA+BpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QA+BlD"}
+{"version":3,"file":"orgs.d.ts","sourceRoot":"","sources":["../../src/tools/orgs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqBpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QA+BlD"}

package/dist/tools/orgs.js

@@ -1,15 +1,9 @@
 import { z } from 'zod';
 import { apiRequest } from './api-client.js';
-const API_TOKEN = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
-function requireToken() {
-    if (!API_TOKEN) {
-        throw new Error('FERRLABS_API_TOKEN environment variable is required for authenticated operations.');
-    }
-    return API_TOKEN;
-}
+import { getToken } from '../auth/index.js';
 export function registerOrgsTools(server) {
     server.tool('list_orgs', 'List FerrLabs organizations the authenticated user belongs to', {}, async () => {
-        const token = requireToken();
+        const token = await getToken();
         const orgs = await apiRequest('/v1/orgs', { token });
         return {
             content: [{ type: 'text', text: JSON.stringify(orgs, null, 2) }],
@@ -18,7 +12,7 @@ export function registerOrgsTools(server) {
     server.tool('list_projects', 'List projects inside a FerrLabs organization', {
         org_slug: z.string().min(1).describe('Organization slug (from list_orgs)'),
     }, async ({ org_slug }) => {
-        const token = requireToken();
+        const token = await getToken();
         const projects = await apiRequest(`/v1/orgs/${encodeURIComponent(org_slug)}/projects`, { token });
         return {
             content: [{ type: 'text', text: JSON.stringify(projects, null, 2) }],

package/dist/tools/subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/tools/subscriptions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA0BpE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,QAkB3D"}
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/tools/subscriptions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgBpE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,QAkB3D"}

package/dist/tools/subscriptions.js

@@ -1,17 +1,11 @@
 import { z } from 'zod';
 import { apiRequest } from './api-client.js';
-const API_TOKEN = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
-function requireToken() {
-    if (!API_TOKEN) {
-        throw new Error('FERRLABS_API_TOKEN environment variable is required for authenticated operations.');
-    }
-    return API_TOKEN;
-}
+import { getToken } from '../auth/index.js';
 export function registerSubscriptionsTools(server) {
     server.tool('list_subscriptions', 'List FerrLabs product subscriptions for an organization (FerrVault, FerrTrack, FerrGrowth, FerrFleet)', {
         org_slug: z.string().min(1).describe('Organization slug'),
     }, async ({ org_slug }) => {
-        const token = requireToken();
+        const token = await getToken();
         const subs = await apiRequest(`/v1/orgs/${encodeURIComponent(org_slug)}/subscriptions`, { token });
         return {
             content: [{ type: 'text', text: JSON.stringify(subs, null, 2) }],

package/dist/tools/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/tools/tokens.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsCpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QA4EnD"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/tools/tokens.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4BpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QA4EnD"}

package/dist/tools/tokens.js

@@ -1,15 +1,9 @@
 import { z } from 'zod';
 import { apiRequest } from './api-client.js';
-const API_TOKEN = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
-function requireToken() {
-    if (!API_TOKEN) {
-        throw new Error('FERRLABS_API_TOKEN environment variable is required for authenticated operations (FERRFLOW_API_TOKEN is accepted as a fallback for backward compatibility).');
-    }
-    return API_TOKEN;
-}
+import { getToken } from '../auth/index.js';
 export function registerTokenTools(server) {
     server.tool('get_me', 'Get the current authenticated FerrLabs user profile', {}, async () => {
-        const token = requireToken();
+        const token = await getToken();
         const user = await apiRequest('/v1/auth/me', { token });
         return {
             content: [
@@ -21,7 +15,7 @@ export function registerTokenTools(server) {
         };
     });
     server.tool('list_tokens', 'List all API tokens for the authenticated user', {}, async () => {
-        const token = requireToken();
+        const token = await getToken();
         const tokens = await apiRequest('/v1/auth/tokens', { token });
         return {
             content: [
@@ -37,7 +31,7 @@ export function registerTokenTools(server) {
         scopes: z.array(z.string()).describe('Token scopes (e.g. ["*"] for all)'),
         expires_at: z.string().optional().describe('Expiration date (ISO 8601)'),
     }, async ({ name, scopes, expires_at }) => {
-        const token = requireToken();
+        const token = await getToken();
         const result = await apiRequest('/v1/auth/tokens', {
             method: 'POST',
             body: { name, scopes, expires_at },
@@ -56,7 +50,7 @@ export function registerTokenTools(server) {
     server.tool('revoke_token', 'Revoke a FerrLabs API token by ID', {
         token_id: z.string().uuid().describe('Token ID to revoke'),
     }, async ({ token_id }) => {
-        const token = requireToken();
+        const token = await getToken();
         await apiRequest(`/v1/auth/tokens/${token_id}`, {
             method: 'DELETE',
             token,

package/dist/tools/vaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vaults.d.ts","sourceRoot":"","sources":["../../src/tools/vaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuBpE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QAmBpD"}
+{"version":3,"file":"vaults.d.ts","sourceRoot":"","sources":["../../src/tools/vaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAapE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QAmBpD"}

package/dist/tools/vaults.js

@@ -1,18 +1,12 @@
 import { z } from 'zod';
 import { apiRequest } from './api-client.js';
-const API_TOKEN = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
-function requireToken() {
-    if (!API_TOKEN) {
-        throw new Error('FERRLABS_API_TOKEN environment variable is required for authenticated operations.');
-    }
-    return API_TOKEN;
-}
+import { getToken } from '../auth/index.js';
 export function registerVaultsTools(server) {
     server.tool('list_vaults', 'List FerrVault vaults inside a project (FerrVault — secrets management)', {
         org_slug: z.string().min(1).describe('Organization slug'),
         project_slug: z.string().min(1).describe('Project slug'),
     }, async ({ org_slug, project_slug }) => {
-        const token = requireToken();
+        const token = await getToken();
         const vaults = await apiRequest(`/v1/orgs/${encodeURIComponent(org_slug)}/projects/${encodeURIComponent(project_slug)}/vaults`, { token });
         return {
             content: [{ type: 'text', text: JSON.stringify(vaults, null, 2) }],

package/package.json

@@ -39,7 +39,7 @@
     "model-context-protocol",
     "ai"
   ],
-  "license": "MIT",
+  "license": "MPL-2.0",
   "main": "./dist/index.js",
   "name": "@ferrlabs/mcp",
   "publishConfig": {
@@ -50,7 +50,7 @@
     "url": "https://github.com/FerrLabs/MCP.git"
   },
   "type": "module",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "scripts": {
     "build": "tsc",
     "ci:local": "pnpm typecheck && pnpm test && pnpm build",