freeagent-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam
+
+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.

package/README.md

@@ -0,0 +1,359 @@
+# freeagent-mcp
+
+[![npm version](https://img.shields.io/npm/v/freeagent-mcp.svg)](https://www.npmjs.com/package/freeagent-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for the [FreeAgent](https://www.freeagent.com/) accounting API. Provides 76 tools covering invoices, expenses, contacts, projects, timeslips, banking, bills, estimates, credit notes, accounting reports, and more.
+
+## Features
+
+- **Company** - Company info, business categories, tax timeline
+- **Users** - List, get, create, update, and delete users
+- **Contacts** - Full CRUD for clients and suppliers
+- **Projects** - Create and manage projects
+- **Tasks** - Manage project tasks with billing rates
+- **Timeslips** - Track time with start/stop timer support
+- **Invoices** - Create, send, and manage invoices with status transitions
+- **Estimates** - Quotes, estimates, and proposals with approval workflows
+- **Bills** - Manage supplier bills
+- **Credit Notes** - Issue and manage credit notes
+- **Expenses** - Track and categorize expenses
+- **Banking** - Bank accounts and transaction management
+- **Categories** - Browse accounting categories
+- **Accounting Reports** - Profit & loss, balance sheet, trial balance
+
+## 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
+
+See the [FreeAgent API Quick Start](https://dev.freeagent.com/docs/quick_start) for detailed instructions.
+
+## Installation
+
+### Using npx (recommended)
+
+```bash
+npx freeagent-mcp-server
+```
+
+### Global install
+
+```bash
+npm install -g freeagent-mcp-server
+freeagent-mcp
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/samaxbytez/freeagent-mcp.git
+cd freeagent-mcp
+npm install
+npm run build
+npm start
+```
+
+## Configuration
+
+### Environment Variables
+
+| 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`) |
+
+For production, set:
+```
+FREEAGENT_BASE_URL=https://api.freeagent.com/v2
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "freeagent": {
+      "command": "npx",
+      "args": ["-y", "freeagent-mcp-server"],
+      "env": {
+        "FREEAGENT_ACCESS_TOKEN": "your_access_token_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "freeagent": {
+      "command": "npx",
+      "args": ["-y", "freeagent-mcp-server"],
+      "env": {
+        "FREEAGENT_ACCESS_TOKEN": "your_access_token_here"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+freeagent-mcp/
+├── src/
+│   ├── index.ts              # Entry point, server setup
+│   ├── client.ts             # FreeAgent API HTTP client
+│   ├── utils.ts              # Shared utilities (responses, logging)
+│   ├── client.test.ts        # Client tests
+│   ├── utils.test.ts         # Utils tests
+│   └── tools/
+│       ├── company.ts        # Company info tools (3)
+│       ├── users.ts          # User management tools (6)
+│       ├── contacts.ts       # Contact CRUD tools (5)
+│       ├── projects.ts       # Project management tools (5)
+│       ├── tasks.ts          # Task management tools (5)
+│       ├── timeslips.ts      # Time tracking tools (7)
+│       ├── invoices.ts       # Invoice tools (9)
+│       ├── estimates.ts      # Estimate tools (7)
+│       ├── bills.ts          # Bill management tools (5)
+│       ├── credit-notes.ts   # Credit note tools (5)
+│       ├── expenses.ts       # Expense tracking tools (5)
+│       ├── banking.ts        # Banking tools (7)
+│       ├── categories.ts     # Category tools (2)
+│       ├── accounting.ts     # Accounting report tools (5)
+│       └── tools.test.ts     # Tool handler tests
+├── package.json
+├── tsconfig.json
+└── smithery.yaml
+```
+
+## Tools Reference
+
+### Company (3 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_get_company` | Get company information | `GET /company` |
+| `freeagent_list_business_categories` | List business categories | `GET /company/business_categories` |
+| `freeagent_get_tax_timeline` | Get tax timeline | `GET /company/tax_timeline` |
+
+### Users (6 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_users` | List users with optional view filter | `GET /users` |
+| `freeagent_get_user` | Get a specific user | `GET /users/:id` |
+| `freeagent_get_current_user` | Get the authenticated user | `GET /users/me` |
+| `freeagent_create_user` | Create a new user | `POST /users` |
+| `freeagent_update_user` | Update a user | `PUT /users/:id` |
+| `freeagent_delete_user` | Delete a user | `DELETE /users/:id` |
+
+### Contacts (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_contacts` | List contacts with filtering and sorting | `GET /contacts` |
+| `freeagent_get_contact` | Get a specific contact | `GET /contacts/:id` |
+| `freeagent_create_contact` | Create a new contact | `POST /contacts` |
+| `freeagent_update_contact` | Update a contact | `PUT /contacts/:id` |
+| `freeagent_delete_contact` | Delete a contact | `DELETE /contacts/:id` |
+
+### Projects (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_projects` | List projects with optional view filter | `GET /projects` |
+| `freeagent_get_project` | Get a specific project | `GET /projects/:id` |
+| `freeagent_create_project` | Create a new project | `POST /projects` |
+| `freeagent_update_project` | Update a project | `PUT /projects/:id` |
+| `freeagent_delete_project` | Delete a project | `DELETE /projects/:id` |
+
+### Tasks (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_tasks` | List tasks with optional filtering | `GET /tasks` |
+| `freeagent_get_task` | Get a specific task | `GET /tasks/:id` |
+| `freeagent_create_task` | Create a new task for a project | `POST /tasks` |
+| `freeagent_update_task` | Update a task | `PUT /tasks/:id` |
+| `freeagent_delete_task` | Delete a task | `DELETE /tasks/:id` |
+
+### Timeslips (7 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_timeslips` | List timeslips with date and status filters | `GET /timeslips` |
+| `freeagent_get_timeslip` | Get a specific timeslip | `GET /timeslips/:id` |
+| `freeagent_create_timeslip` | Create a new timeslip | `POST /timeslips` |
+| `freeagent_update_timeslip` | Update a timeslip | `PUT /timeslips/:id` |
+| `freeagent_delete_timeslip` | Delete a timeslip | `DELETE /timeslips/:id` |
+| `freeagent_start_timer` | Start a timer on a timeslip | `POST /timeslips/:id/timer` |
+| `freeagent_stop_timer` | Stop a timer on a timeslip | `DELETE /timeslips/:id/timer` |
+
+### Invoices (9 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_invoices` | List invoices with view and contact filters | `GET /invoices` |
+| `freeagent_get_invoice` | Get a specific invoice | `GET /invoices/:id` |
+| `freeagent_create_invoice` | Create a new invoice | `POST /invoices` |
+| `freeagent_update_invoice` | Update an invoice | `PUT /invoices/:id` |
+| `freeagent_delete_invoice` | Delete an invoice | `DELETE /invoices/:id` |
+| `freeagent_mark_invoice_as_sent` | Mark invoice as sent | `PUT /invoices/:id/transitions/mark_as_sent` |
+| `freeagent_mark_invoice_as_draft` | Mark invoice as draft | `PUT /invoices/:id/transitions/mark_as_draft` |
+| `freeagent_mark_invoice_as_cancelled` | Cancel an invoice | `PUT /invoices/:id/transitions/mark_as_cancelled` |
+| `freeagent_send_invoice_email` | Email an invoice | `POST /invoices/:id/send_email` |
+
+### Estimates (7 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_estimates` | List estimates with filters | `GET /estimates` |
+| `freeagent_get_estimate` | Get a specific estimate | `GET /estimates/:id` |
+| `freeagent_create_estimate` | Create a new estimate | `POST /estimates` |
+| `freeagent_update_estimate` | Update an estimate | `PUT /estimates/:id` |
+| `freeagent_delete_estimate` | Delete an estimate | `DELETE /estimates/:id` |
+| `freeagent_mark_estimate_as_sent` | Mark estimate as sent | `PUT /estimates/:id/transitions/mark_as_sent` |
+| `freeagent_mark_estimate_as_approved` | Mark estimate as approved | `PUT /estimates/:id/transitions/mark_as_approved` |
+
+### Bills (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_bills` | List bills with view and date filters | `GET /bills` |
+| `freeagent_get_bill` | Get a specific bill | `GET /bills/:id` |
+| `freeagent_create_bill` | Create a new bill | `POST /bills` |
+| `freeagent_update_bill` | Update a bill | `PUT /bills/:id` |
+| `freeagent_delete_bill` | Delete a bill | `DELETE /bills/:id` |
+
+### Credit Notes (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_credit_notes` | List credit notes with filters | `GET /credit_notes` |
+| `freeagent_get_credit_note` | Get a specific credit note | `GET /credit_notes/:id` |
+| `freeagent_create_credit_note` | Create a new credit note | `POST /credit_notes` |
+| `freeagent_update_credit_note` | Update a credit note | `PUT /credit_notes/:id` |
+| `freeagent_delete_credit_note` | Delete a credit note | `DELETE /credit_notes/:id` |
+
+### Expenses (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_expenses` | List expenses with date and project filters | `GET /expenses` |
+| `freeagent_get_expense` | Get a specific expense | `GET /expenses/:id` |
+| `freeagent_create_expense` | Create a new expense | `POST /expenses` |
+| `freeagent_update_expense` | Update an expense | `PUT /expenses/:id` |
+| `freeagent_delete_expense` | Delete an expense | `DELETE /expenses/:id` |
+
+### Banking (7 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_bank_accounts` | List bank accounts | `GET /bank_accounts` |
+| `freeagent_get_bank_account` | Get a specific bank account | `GET /bank_accounts/:id` |
+| `freeagent_create_bank_account` | Create a new bank account | `POST /bank_accounts` |
+| `freeagent_update_bank_account` | Update a bank account | `PUT /bank_accounts/:id` |
+| `freeagent_delete_bank_account` | Delete a bank account | `DELETE /bank_accounts/:id` |
+| `freeagent_list_bank_transactions` | List transactions for a bank account | `GET /bank_transactions` |
+| `freeagent_get_bank_transaction` | Get a specific bank transaction | `GET /bank_transactions/:id` |
+
+### Categories (2 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_list_categories` | List all accounting categories | `GET /categories` |
+| `freeagent_get_category` | Get a specific category by nominal code | `GET /categories/:nominal_code` |
+
+### Accounting Reports (5 tools)
+
+| Tool | Description | API Endpoint |
+|------|-------------|-------------|
+| `freeagent_get_profit_and_loss` | Get profit and loss summary | `GET /accounting/profit_and_loss/summary` |
+| `freeagent_get_balance_sheet` | Get balance sheet | `GET /accounting/balance_sheet` |
+| `freeagent_get_opening_balances` | Get opening balances | `GET /accounting/balance_sheet/opening_balances` |
+| `freeagent_get_trial_balance` | Get trial balance summary | `GET /accounting/trial_balance/summary` |
+| `freeagent_get_trial_balance_opening` | Get trial balance opening balances | `GET /accounting/trial_balance/summary/opening_balances` |
+
+## Example Prompts
+
+- "Show me the company information from FreeAgent"
+- "List all active contacts"
+- "Create a new invoice for contact 12345 dated today with 30 day payment terms"
+- "How much time did I log this week?"
+- "Start a timer on timeslip 67890"
+- "Show my profit and loss for the current year"
+- "List all overdue invoices"
+- "Create an expense for lunch at $25 under the entertainment category"
+- "What's my current balance sheet?"
+- "List all open bills from suppliers"
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run type-check
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+### Adding New Tools
+
+1. Create a new file in `src/tools/` (or add to an existing one)
+2. Follow the pattern: export a `registerXxxTools(server, client)` function
+3. Register each tool with `server.tool()` or `server.registerTool()`
+4. Always use `logToolCall()`, `jsonResponse()`, and `errorResponse()`
+5. Import and call the register function in `src/index.ts`
+6. Add tests in `src/tools/tools.test.ts`
+
+## Troubleshooting
+
+**"Missing required environment variable: FREEAGENT_ACCESS_TOKEN"**
+Set the `FREEAGENT_ACCESS_TOKEN` environment variable with a valid OAuth2 access token.
+
+**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.
+
+**"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.
+
+**Tool not found**
+Ensure you're using the correct tool name with the `freeagent_` prefix (e.g., `freeagent_list_invoices`, not `list_invoices`).
+
+**Empty responses**
+Some endpoints return empty responses for successful DELETE operations. This is expected behavior.
+
+## License
+
+MIT

package/build/client.d.ts

@@ -0,0 +1,18 @@
+export declare class FreeAgentApiError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    constructor(status: number, errorCode: string, message: string);
+}
+export declare class FreeAgentClient {
+    private accessToken;
+    private baseUrl;
+    constructor(accessToken: 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>;
+    putForm<T = unknown>(path: string, body?: Record<string, string>): Promise<T>;
+    putJson<T = unknown>(path: string, body: unknown): Promise<T>;
+    patchJson<T = unknown>(path: string, body: unknown): Promise<T>;
+    deleteReq<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    private request;
+}

package/build/client.js

@@ -0,0 +1,93 @@
+const DEFAULT_BASE_URL = "https://api.sandbox.freeagent.com/v2";
+export class FreeAgentApiError extends Error {
+    status;
+    errorCode;
+    constructor(status, errorCode, message) {
+        super(`FreeAgent API error (${status}): ${errorCode} - ${message}`);
+        this.name = "FreeAgentApiError";
+        this.status = status;
+        this.errorCode = errorCode;
+    }
+}
+function parseApiError(status, body) {
+    try {
+        const parsed = JSON.parse(body);
+        const code = parsed?.error ?? parsed?.code ?? "unknown";
+        const message = parsed?.message ??
+            parsed?.error_description ??
+            parsed?.errors?.error?.message ??
+            `HTTP ${status}`;
+        return new FreeAgentApiError(status, code, message);
+    }
+    catch {
+        return new FreeAgentApiError(status, "unknown", `HTTP ${status} error`);
+    }
+}
+function encodeFormBody(data) {
+    return new URLSearchParams(data).toString();
+}
+export class FreeAgentClient {
+    accessToken;
+    baseUrl;
+    constructor(accessToken, baseUrl) {
+        this.accessToken = accessToken;
+        this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+    }
+    async get(path, params) {
+        return this.request("GET", path, undefined, undefined, params);
+    }
+    async postForm(path, body) {
+        return this.request("POST", path, body, "form");
+    }
+    async postJson(path, body) {
+        return this.request("POST", path, body, "json");
+    }
+    async putForm(path, body) {
+        return this.request("PUT", path, body, "form");
+    }
+    async putJson(path, body) {
+        return this.request("PUT", path, body, "json");
+    }
+    async patchJson(path, body) {
+        return this.request("PATCH", path, body, "json");
+    }
+    async deleteReq(path, params) {
+        return this.request("DELETE", path, undefined, undefined, params);
+    }
+    async request(method, path, body, bodyType, params) {
+        const url = new URL(path, this.baseUrl);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.accessToken}`,
+            Accept: "application/json",
+            "User-Agent": "freeagent-mcp/1.0.0",
+        };
+        let encodedBody;
+        if (body && bodyType === "json") {
+            headers["Content-Type"] = "application/json";
+            encodedBody = JSON.stringify(body);
+        }
+        else if (body && bodyType === "form") {
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+            encodedBody = encodeFormBody(body);
+        }
+        const response = await fetch(url.toString(), {
+            method,
+            headers,
+            body: encodedBody,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw parseApiError(response.status, errorBody);
+        }
+        const text = await response.text();
+        if (!text)
+            return {};
+        return JSON.parse(text);
+    }
+}
+//# sourceMappingURL=client.js.map

package/build/client.js.map

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

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { FreeAgentClient } from "./client.js";
+import { registerCompanyTools } from "./tools/company.js";
+import { registerUserTools } from "./tools/users.js";
+import { registerContactTools } from "./tools/contacts.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerTimeslipTools } from "./tools/timeslips.js";
+import { registerInvoiceTools } from "./tools/invoices.js";
+import { registerEstimateTools } from "./tools/estimates.js";
+import { registerBillTools } from "./tools/bills.js";
+import { registerCreditNoteTools } from "./tools/credit-notes.js";
+import { registerExpenseTools } from "./tools/expenses.js";
+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_BASE_URL = process.env.FREEAGENT_BASE_URL;
+if (!FREEAGENT_ACCESS_TOKEN) {
+    console.error("Missing required environment variable: FREEAGENT_ACCESS_TOKEN");
+    process.exit(1);
+}
+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");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

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

package/build/tools/accounting.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreeAgentClient } from "../client.js";
+export declare function registerAccountingTools(server: McpServer, client: FreeAgentClient): void;

package/build/tools/accounting.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { jsonResponse, errorResponse, logToolCall, buildParams } from "../utils.js";
+export function registerAccountingTools(server, client) {
+    server.tool("freeagent_get_profit_and_loss", "Get the profit and loss summary from FreeAgent with optional date range filtering", {
+        from_date: z
+            .string()
+            .optional()
+            .describe("Start date for the P&L report in YYYY-MM-DD format"),
+        to_date: z
+            .string()
+            .optional()
+            .describe("End date for the P&L report in YYYY-MM-DD format"),
+    }, async ({ from_date, to_date }) => {
+        logToolCall("freeagent_get_profit_and_loss", { from_date, to_date });
+        try {
+            const params = buildParams({ from_date, to_date });
+            const data = await client.get("/accounting/profit_and_loss/summary", params);
+            return jsonResponse(data);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.tool("freeagent_get_balance_sheet", "Get the balance sheet from FreeAgent, optionally as at a specific date", {
+        as_at_date: z
+            .string()
+            .optional()
+            .describe("Date to retrieve the balance sheet as at, in YYYY-MM-DD format"),
+    }, async ({ as_at_date }) => {
+        logToolCall("freeagent_get_balance_sheet", { as_at_date });
+        try {
+            const params = buildParams({ as_at_date });
+            const data = await client.get("/accounting/balance_sheet", params);
+            return jsonResponse(data);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.tool("freeagent_get_opening_balances", "Get the opening balances from the FreeAgent balance sheet", {}, async () => {
+        logToolCall("freeagent_get_opening_balances");
+        try {
+            const data = await client.get("/accounting/balance_sheet/opening_balances");
+            return jsonResponse(data);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.tool("freeagent_get_trial_balance", "Get the trial balance summary from FreeAgent with optional date range filtering", {
+        from_date: z
+            .string()
+            .optional()
+            .describe("Start date for the trial balance in YYYY-MM-DD format"),
+        to_date: z
+            .string()
+            .optional()
+            .describe("End date for the trial balance in YYYY-MM-DD format"),
+    }, async ({ from_date, to_date }) => {
+        logToolCall("freeagent_get_trial_balance", { from_date, to_date });
+        try {
+            const params = buildParams({ from_date, to_date });
+            const data = await client.get("/accounting/trial_balance/summary", params);
+            return jsonResponse(data);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.tool("freeagent_get_trial_balance_opening", "Get the trial balance opening balances from FreeAgent", {}, async () => {
+        logToolCall("freeagent_get_trial_balance_opening");
+        try {
+            const data = await client.get("/accounting/trial_balance/summary/opening_balances");
+            return jsonResponse(data);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=accounting.js.map

package/build/tools/accounting.js.map

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

package/build/tools/banking.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreeAgentClient } from "../client.js";
+export declare function registerBankingTools(server: McpServer, client: FreeAgentClient): void;