freeagent-mcp-server 1.0.1 → 1.1.0

package/README.md

@@ -7,6 +7,7 @@ MCP server for the [FreeAgent](https://www.freeagent.com/) accounting API. Provi
 
 ## Features
 
+- **OAuth2 Authentication** - Built-in browser-based auth flow with automatic token refresh
 - **Company** - Company info, business categories, tax timeline
 - **Users** - List, get, create, update, and delete users
 - **Contacts** - Full CRUD for clients and suppliers
@@ -24,15 +25,36 @@ MCP server for the [FreeAgent](https://www.freeagent.com/) accounting API. Provi
 
 ## Prerequisites
 
-You need a FreeAgent account and OAuth2 access token. To get one:
-
 1. Sign up for a [FreeAgent Developer](https://dev.freeagent.com/) account
 2. Create a sandbox account for testing
-3. Register an application to get OAuth credentials
-4. Complete the OAuth2 authorization flow to obtain an access token
+3. Register an application in the Developer Dashboard
+4. Set the **OAuth redirect URI** to `http://localhost:3456/callback`
+5. Note your **Client ID** and **Client Secret**
 
 See the [FreeAgent API Quick Start](https://dev.freeagent.com/docs/quick_start) for detailed instructions.
 
+## Getting Started
+
+### 1. Set environment variables
+
+```bash
+export FREEAGENT_CLIENT_ID="your_client_id"
+export FREEAGENT_CLIENT_SECRET="your_client_secret"
+# export FREEAGENT_SANDBOX=false  # uncomment for production accounts
+```
+
+### 2. Authenticate (one-time)
+
+```bash
+npx freeagent-mcp-server auth
+```
+
+This opens your browser to authorize the app. After approval, tokens are saved to `~/.freeagent-mcp/tokens.json` and automatically refreshed when they expire.
+
+### 3. Configure your MCP client
+
+See the [Configuration](#configuration) section below.
+
 ## Installation
 
 ### Using npx (recommended)
@@ -64,13 +86,13 @@ npm start
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `FREEAGENT_ACCESS_TOKEN` | Yes | Your FreeAgent OAuth2 access token |
-| `FREEAGENT_BASE_URL` | No | API base URL (defaults to `https://api.sandbox.freeagent.com/v2`) |
+| `FREEAGENT_CLIENT_ID` | Yes* | OAuth2 client ID from Developer Dashboard |
+| `FREEAGENT_CLIENT_SECRET` | Yes* | OAuth2 client secret from Developer Dashboard |
+| `FREEAGENT_SANDBOX` | No | Set to `false` for production (defaults to `true`) |
+| `FREEAGENT_ACCESS_TOKEN` | No | Legacy: direct access token (skips stored token flow) |
+| `FREEAGENT_BASE_URL` | No | Override API base URL |
 
-For production, set:
-```
-FREEAGENT_BASE_URL=https://api.freeagent.com/v2
-```
+*Not required if using `FREEAGENT_ACCESS_TOKEN` directly.
 
 ### Claude Desktop
 
@@ -83,7 +105,8 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "freeagent-mcp-server"],
       "env": {
-        "FREEAGENT_ACCESS_TOKEN": "your_access_token_here"
+        "FREEAGENT_CLIENT_ID": "your_client_id",
+        "FREEAGENT_CLIENT_SECRET": "your_client_secret"
       }
     }
   }
@@ -101,7 +124,8 @@ Add to your `.mcp.json`:
       "command": "npx",
       "args": ["-y", "freeagent-mcp-server"],
       "env": {
-        "FREEAGENT_ACCESS_TOKEN": "your_access_token_here"
+        "FREEAGENT_CLIENT_ID": "your_client_id",
+        "FREEAGENT_CLIENT_SECRET": "your_client_secret"
       }
     }
   }
@@ -114,8 +138,10 @@ Add to your `.mcp.json`:
 freeagent-mcp/
 ├── src/
 │   ├── index.ts              # Entry point, server setup
+│   ├── auth.ts               # OAuth2 flow, token storage & refresh
 │   ├── client.ts             # FreeAgent API HTTP client
 │   ├── utils.ts              # Shared utilities (responses, logging)
+│   ├── auth.test.ts          # Auth module tests
 │   ├── client.test.ts        # Client tests
 │   ├── utils.test.ts         # Utils tests
 │   └── tools/
@@ -336,17 +362,23 @@ npm run format
 
 ## Troubleshooting
 
-**"Missing required environment variable: FREEAGENT_ACCESS_TOKEN"**
-Set the `FREEAGENT_ACCESS_TOKEN` environment variable with a valid OAuth2 access token.
+**"Missing credentials" error on startup**
+Set `FREEAGENT_CLIENT_ID` and `FREEAGENT_CLIENT_SECRET` environment variables, then run `npx freeagent-mcp-server auth` to authenticate.
+
+**"No stored tokens found"**
+You need to complete the one-time auth flow first: `npx freeagent-mcp-server auth`
+
+**Authentication times out**
+Ensure port 3456 is available and your browser can reach `http://localhost:3456/callback`. Check that your FreeAgent app's redirect URI is set to `http://localhost:3456/callback`.
 
 **401 Unauthorized errors**
-Your access token may have expired. FreeAgent OAuth tokens expire - you'll need to refresh your token using the OAuth2 refresh flow.
+Your tokens may have been revoked. Re-run `npx freeagent-mcp-server auth` to re-authenticate.
 
 **"FreeAgent API error (403)"**
 Your token may not have the required permission level. Check that your FreeAgent app has the appropriate access scopes.
 
 **Sandbox vs Production**
-By default the server connects to the FreeAgent sandbox. Set `FREEAGENT_BASE_URL=https://api.freeagent.com/v2` for production.
+By default the server connects to the FreeAgent sandbox. Set `FREEAGENT_SANDBOX=false` for production.
 
 **Tool not found**
 Ensure you're using the correct tool name with the `freeagent_` prefix (e.g., `freeagent_list_invoices`, not `list_invoices`).

package/build/auth.d.ts

@@ -0,0 +1,17 @@
+export interface OAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    sandbox: boolean;
+}
+export interface StoredTokens {
+    access_token: string;
+    refresh_token: string;
+    expires_at: number;
+}
+export declare function getApiBase(sandbox: boolean): string;
+export declare function loadTokens(): StoredTokens | null;
+export declare function saveTokens(tokens: StoredTokens): void;
+export declare function isTokenExpired(tokens: StoredTokens): boolean;
+export declare function refreshAccessToken(config: OAuthConfig, refreshToken: string): Promise<StoredTokens>;
+export declare function getValidAccessToken(config: OAuthConfig): Promise<string>;
+export declare function runAuthFlow(config: OAuthConfig): Promise<void>;

package/build/auth.js

@@ -0,0 +1,195 @@
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { TOKEN_BUFFER_MS } from "./utils.js";
+const TOKEN_DIR = join(homedir(), ".freeagent-mcp");
+const TOKEN_FILE = join(TOKEN_DIR, "tokens.json");
+const CALLBACK_PORT = 3456;
+const AUTH_TIMEOUT_MS = 120_000;
+export function getApiBase(sandbox) {
+    return sandbox
+        ? "https://api.sandbox.freeagent.com/v2"
+        : "https://api.freeagent.com/v2";
+}
+export function loadTokens() {
+    try {
+        const data = readFileSync(TOKEN_FILE, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveTokens(tokens) {
+    mkdirSync(TOKEN_DIR, { recursive: true });
+    writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(TOKEN_FILE, 0o600);
+    }
+    catch {
+        // chmod may fail on some platforms, file was already created with mode
+    }
+}
+export function isTokenExpired(tokens) {
+    return Date.now() >= tokens.expires_at - TOKEN_BUFFER_MS;
+}
+export async function refreshAccessToken(config, refreshToken) {
+    const base = getApiBase(config.sandbox);
+    const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+    const response = await fetch(`${base}/token_endpoint`, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+        }).toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token refresh failed (${response.status}): ${text}`);
+    }
+    const data = (await response.json());
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: Date.now() + data.expires_in * 1000,
+    };
+}
+let refreshPromise = null;
+export async function getValidAccessToken(config) {
+    const tokens = loadTokens();
+    if (!tokens) {
+        throw new Error("No stored tokens found. Run `npx freeagent-mcp-server auth` to authenticate.");
+    }
+    if (!isTokenExpired(tokens)) {
+        return tokens.access_token;
+    }
+    // Mutex: if a refresh is already in flight, wait for it
+    if (refreshPromise) {
+        const refreshed = await refreshPromise;
+        return refreshed.access_token;
+    }
+    try {
+        refreshPromise = refreshAccessToken(config, tokens.refresh_token);
+        const newTokens = await refreshPromise;
+        saveTokens(newTokens);
+        return newTokens.access_token;
+    }
+    finally {
+        refreshPromise = null;
+    }
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin"
+        ? "open"
+        : platform === "win32"
+            ? "start"
+            : "xdg-open";
+    exec(`${cmd} "${url}"`);
+}
+async function exchangeCodeForTokens(config, code) {
+    const base = getApiBase(config.sandbox);
+    const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+    const response = await fetch(`${base}/token_endpoint`, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: `http://localhost:${CALLBACK_PORT}/callback`,
+        }).toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token exchange failed (${response.status}): ${text}`);
+    }
+    const data = (await response.json());
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: Date.now() + data.expires_in * 1000,
+    };
+}
+export async function runAuthFlow(config) {
+    const state = randomBytes(16).toString("hex");
+    const base = getApiBase(config.sandbox);
+    const authUrl = `${base}/approve_app?response_type=code` +
+        `&client_id=${encodeURIComponent(config.clientId)}` +
+        `&redirect_uri=${encodeURIComponent(`http://localhost:${CALLBACK_PORT}/callback`)}` +
+        `&state=${encodeURIComponent(state)}`;
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Authentication timed out after 120 seconds"));
+        }, AUTH_TIMEOUT_MS);
+        const server = createServer(async (req, res) => {
+            const url = new URL(req.url || "/", `http://localhost:${CALLBACK_PORT}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const returnedState = url.searchParams.get("state");
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.writeHead(400);
+                res.end(`Authentication failed: ${error}`);
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            if (returnedState !== state) {
+                res.writeHead(400);
+                res.end("State mismatch - possible CSRF attack");
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error("OAuth state mismatch"));
+                return;
+            }
+            if (!code) {
+                res.writeHead(400);
+                res.end("No authorization code received");
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error("No authorization code in callback"));
+                return;
+            }
+            try {
+                const tokens = await exchangeCodeForTokens(config, code);
+                saveTokens(tokens);
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end("<html><body><h1>Authentication successful!</h1>" +
+                    "<p>You can close this window and return to your terminal.</p>" +
+                    "</body></html>");
+                clearTimeout(timeout);
+                server.close();
+                resolve();
+            }
+            catch (err) {
+                res.writeHead(500);
+                res.end("Token exchange failed");
+                clearTimeout(timeout);
+                server.close();
+                reject(err);
+            }
+        });
+        server.listen(CALLBACK_PORT, () => {
+            console.log(`\nOpening browser for FreeAgent authorization...`);
+            console.log(`If the browser doesn't open, visit:\n${authUrl}\n`);
+            openBrowser(authUrl);
+        });
+    });
+}
+//# sourceMappingURL=auth.js.map

package/build/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/build/client.d.ts

@@ -4,9 +4,9 @@ export declare class FreeAgentApiError extends Error {
     constructor(status: number, errorCode: string, message: string);
 }
 export declare class FreeAgentClient {
-    private accessToken;
+    private getAccessToken;
     private baseUrl;
-    constructor(accessToken: string, baseUrl?: string);
+    constructor(tokenOrProvider: string | (() => Promise<string>), baseUrl?: string);
     get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
     postForm<T = unknown>(path: string, body?: Record<string, string>): Promise<T>;
     postJson<T = unknown>(path: string, body: unknown): Promise<T>;

package/build/client.js

@@ -27,10 +27,13 @@ function encodeFormBody(data) {
     return new URLSearchParams(data).toString();
 }
 export class FreeAgentClient {
-    accessToken;
+    getAccessToken;
     baseUrl;
-    constructor(accessToken, baseUrl) {
-        this.accessToken = accessToken;
+    constructor(tokenOrProvider, baseUrl) {
+        this.getAccessToken =
+            typeof tokenOrProvider === "function"
+                ? tokenOrProvider
+                : async () => tokenOrProvider;
         this.baseUrl = baseUrl || DEFAULT_BASE_URL;
     }
     async get(path, params) {
@@ -63,8 +66,9 @@ export class FreeAgentClient {
                 url.searchParams.set(k, v);
             }
         }
+        const accessToken = await this.getAccessToken();
         const headers = {
-            Authorization: `Bearer ${this.accessToken}`,
+            Authorization: `Bearer ${accessToken}`,
             Accept: "application/json",
             "User-Agent": "freeagent-mcp/1.0.0",
         };

package/build/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/build/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { FreeAgentClient } from "./client.js";
+import { runAuthFlow, getValidAccessToken, getApiBase } from "./auth.js";
 import { registerCompanyTools } from "./tools/company.js";
 import { registerUserTools } from "./tools/users.js";
 import { registerContactTools } from "./tools/contacts.js";
@@ -17,37 +18,84 @@ import { registerBankingTools } from "./tools/banking.js";
 import { registerCategoryTools } from "./tools/categories.js";
 import { registerAccountingTools } from "./tools/accounting.js";
 const FREEAGENT_ACCESS_TOKEN = process.env.FREEAGENT_ACCESS_TOKEN;
+const FREEAGENT_CLIENT_ID = process.env.FREEAGENT_CLIENT_ID;
+const FREEAGENT_CLIENT_SECRET = process.env.FREEAGENT_CLIENT_SECRET;
+const FREEAGENT_SANDBOX = process.env.FREEAGENT_SANDBOX !== "false";
 const FREEAGENT_BASE_URL = process.env.FREEAGENT_BASE_URL;
-if (!FREEAGENT_ACCESS_TOKEN) {
-    console.error("Missing required environment variable: FREEAGENT_ACCESS_TOKEN");
-    process.exit(1);
+function buildOAuthConfig() {
+    if (FREEAGENT_CLIENT_ID && FREEAGENT_CLIENT_SECRET) {
+        return {
+            clientId: FREEAGENT_CLIENT_ID,
+            clientSecret: FREEAGENT_CLIENT_SECRET,
+            sandbox: FREEAGENT_SANDBOX,
+        };
+    }
+    return null;
 }
-const client = new FreeAgentClient(FREEAGENT_ACCESS_TOKEN, FREEAGENT_BASE_URL);
-const server = new McpServer({
-    name: "freeagent-mcp",
-    version: "1.0.0",
-});
-registerCompanyTools(server, client);
-registerUserTools(server, client);
-registerContactTools(server, client);
-registerProjectTools(server, client);
-registerTaskTools(server, client);
-registerTimeslipTools(server, client);
-registerInvoiceTools(server, client);
-registerEstimateTools(server, client);
-registerBillTools(server, client);
-registerCreditNoteTools(server, client);
-registerExpenseTools(server, client);
-registerBankingTools(server, client);
-registerCategoryTools(server, client);
-registerAccountingTools(server, client);
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("FreeAgent MCP Server running on stdio");
+// Handle `npx freeagent-mcp-server auth` subcommand
+if (process.argv[2] === "auth") {
+    const config = buildOAuthConfig();
+    if (!config) {
+        console.error("Missing FREEAGENT_CLIENT_ID and FREEAGENT_CLIENT_SECRET environment variables.\n" +
+            "Set these from your FreeAgent Developer Dashboard app credentials.");
+        process.exit(1);
+    }
+    runAuthFlow(config)
+        .then(() => {
+        console.log("Authentication complete! Tokens saved.");
+        console.log("You can now start the MCP server.");
+        process.exit(0);
+    })
+        .catch((err) => {
+        console.error("Authentication failed:", err.message);
+        process.exit(1);
+    });
+}
+else {
+    // Normal server mode
+    let client;
+    if (FREEAGENT_ACCESS_TOKEN) {
+        // Legacy: direct access token
+        client = new FreeAgentClient(FREEAGENT_ACCESS_TOKEN, FREEAGENT_BASE_URL);
+    }
+    else {
+        const config = buildOAuthConfig();
+        if (!config) {
+            console.error("Missing credentials. Provide one of:\n" +
+                "  1. FREEAGENT_CLIENT_ID + FREEAGENT_CLIENT_SECRET (recommended)\n" +
+                "  2. FREEAGENT_ACCESS_TOKEN (legacy)\n\n" +
+                "For option 1, run `npx freeagent-mcp-server auth` first to authenticate.");
+            process.exit(1);
+        }
+        const baseUrl = FREEAGENT_BASE_URL || getApiBase(config.sandbox);
+        client = new FreeAgentClient(() => getValidAccessToken(config), baseUrl);
+    }
+    const server = new McpServer({
+        name: "freeagent-mcp",
+        version: "1.0.0",
+    });
+    registerCompanyTools(server, client);
+    registerUserTools(server, client);
+    registerContactTools(server, client);
+    registerProjectTools(server, client);
+    registerTaskTools(server, client);
+    registerTimeslipTools(server, client);
+    registerInvoiceTools(server, client);
+    registerEstimateTools(server, client);
+    registerBillTools(server, client);
+    registerCreditNoteTools(server, client);
+    registerExpenseTools(server, client);
+    registerBankingTools(server, client);
+    registerCategoryTools(server, client);
+    registerAccountingTools(server, client);
+    async function main() {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("FreeAgent MCP Server running on stdio");
+    }
+    main().catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    });
 }
-main().catch((error) => {
-    console.error("Fatal error:", error);
-    process.exit(1);
-});
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,MAAM,sBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;AAClE,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;AAE1D,IAAI,CAAC,sBAAsB,EAAE,CAAC;IAC5B,OAAO,CAAC,KAAK,CAAC,+DAA+D,CAAC,CAAC;IAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,sBAAsB,EAAE,kBAAkB,CAAC,CAAC;AAE/E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAClC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAClC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAClC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACxC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;AACzD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freeagent-mcp-server",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "MCP server for the FreeAgent API",
   "type": "module",
   "license": "MIT",