freeagent-mcp-remote

Этот «коннектор» создан, чтобы дать Claude доступ к моим данным FreeAgent. На данный момент это внутренний инструмент, однако я старался писать ясно и для широкой публики на случай, если он окажется полезен другим. Если вам нужна помощь с настройкой, адаптацией или вы хотели бы похожий инструмент для своего бизнеса, задайте вопрос.

Вдохновлено samaxbytez/freeagent-mcp. Хотя изначально я думал, что буду разрабатывать на его основе, я решил начать с нуля, используя [https://gofastmcp.com] и Python.

• WIP — «work in progress». Термин, используемый разработчиками; в этом readme он отмечает функциональность, которая ещё недоступна. Эквивалент «скоро появится».

Что доступно

У них общая настройка, поэтому, выполнив шаги ниже, вы уже сегодня получите рабочую половину.

Как это работает

Этот проект — небольшой сервер, который находится между FreeAgent и Claude (или другим ИИ-провайдером) и действует как переводчик. После подключения вы можете спрашивать Claude, например: «какие банковские операции за март всё ещё не объяснены?» — и Claude сможет пойти и посмотреть.

Техническое название такого переводчика — MCP-сервер. MCP — это общий стандарт для подключения ИИ-ассистентов к внешним инструментам. В Claude они отображаются как коннекторы. Чтобы пользоваться этим, вам больше ничего знать не нужно.

Дополнительное чтение:

Что такое MCP? объясняет это простыми словами (представьте «порт USB-C для ИИ»).

Начните работу с пользовательскими коннекторами.

Настройка

Нужно и для инструмента командной строки, и (позже) для коннектора. Написано в расчёте на то, что вы умеете пользоваться терминалом, но, возможно, раньше не создавали сервисов на Python.

1. Получите учётные данные FreeAgent

Прежде чем подключаться к FreeAgent, нужно зарегистрировать «приложение». Это даёт вам две строки — идентификатор клиента и секрет клиента, — которые вместе идентифицируют этот сервер для FreeAgent. Так одно «приложение» можно установить в разных организациях FreeAgent, и, например, если «приложение» окажется вредоносным, FreeAgent сможет удалить его сразу из всех организаций. К сожалению, регистрация обязательна, даже если вы хотите подключиться только к своему аккаунту.

1. Перейдите в панель разработчика FreeAgent и войдите.

2. Создайте приложение.

3. Установите OAuth redirect URI в значение http://localhost:8723/callback. Именно сюда FreeAgent вернёт ваш браузер после того, как вы одобрите доступ, поэтому адрес должен совпадать точно — завершающий слэш всё сломает.

   Этот адрес используется инструментом командной строки, потому что браузер возвращается на вашу собственную машину. Коннектор же после развёртывания доступен по публичному веб-адресу, поэтому ему нужен свой зарегистрированный redirect URI — <the container's URL>/auth/callback. Сейчас с этим ничего делать не нужно; руководство по развёртыванию рассматривает это в нужный момент. Это стоит знать лишь для того, чтобы, увидев позже два разных адреса, вы не решили, что один из них — ошибка.

4. Скопируйте .env.example в .env, если ещё этого не сделали. Этот файл не отслеживается git благодаря .gitignore. Скопируйте OAuth-идентификатор и секрет в него как FREEAGENT_CLIENT_ID и FREEAGENT_CLIENT_SECRET.

2. Установка

Единственное, что нужно установить заранее, — это uv, инструмент для управления Python-проектами. Он сам подбирает нужную версию Python, поэтому Python не обязательно должен быть установлен, и вам не нужно ничего знать о виртуальных окружениях.

На Mac, с Homebrew:

brew install uv
uv --version    # check it worked

Другие платформы и другие способы установки описаны в руководстве по установке uv.

Затем:

git clone <this-repo> && cd freeagent-mcp-remote
uv sync                 # creates .venv, installs everything, fetches Python 3.14
cp .env.example .env    # then add the credentials from the step above

uv sync в первый раз занимает минуту, а затем выполняется почти мгновенно.

uv run <command> выполняет команды внутри этого окружения, поэтому каждая команда ниже начинается с него.

3. Авторизация

uv run scripts/fa_auth.py

Откроется браузер, вы одобрите доступ, и токен будет записан в .env. Access-токены FreeAgent действуют час, но рядом сохраняется refresh-токен, который используется автоматически, так что это действительно разовый шаг.

Песочница. FreeAgent предлагает бесплатную песочницу на signup.sandbox.freeagent.com — одноразовую компанию, с которой можно безопасно работать на запись. Для неё нужна отдельная регистрация и отдельная регистрация приложения; учётные данные песочницы не работают с продакшеном. Чтобы указать на неё, задайте FREEAGENT_API_BASE_URL=https://api.sandbox.freeagent.com/v2 — адреса для входа подхватятся автоматически, так что их невозможно перепутать. Это стоит сделать перед любыми операциями записи; для чтения не обязательно, потому что в песочнице нет ваших реальных данных.

Использование инструмента командной строки

Это работает уже сейчас. Он читает любую часть вашего аккаунта FreeAgent из терминала и берёт на себя вход в систему.

Данные FreeAgent организованы в «эндпоинты» — /company, /invoices, /bank_accounts и так далее. Все они перечислены в документации FreeAgent API. Запрос к одному из них выглядит так:

uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

Что можно попробовать

Всё перечисленное доступно только для чтения и безопасно.

# Your company profile: year end dates, VAT registration, company type
uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

# Bank accounts, including how many transactions are still unexplained
uv run fastmcp call scripts/freeagent_api_caller.py request path=/bank_accounts

# Trial balance — every nominal account and its total
uv run fastmcp call scripts/freeagent_api_caller.py request \
    path=/accounting/trial_balance/summary

# One contact, to see what fields a contact has
uv run fastmcp call scripts/freeagent_api_caller.py request \
    --input-json '{"path": "/contacts", "params": {"per_page": "1"}}'

# Click around in a browser instead
uv run fastmcp dev inspector scripts/freeagent_api_caller.py

Простые аргументы передаются как key=value. Вложенные — params и body — требуют --input-json, который может нести весь вызов целиком.

Как ограничить вывод

Эндпоинт списка может вернуть тысячи записей. Есть два способа сократить вывод, и их можно комбинировать:

• per_page=1 ограничивает количество возвращаемых записей. Обычно это то, что нужно: одна реальная запись показывает фактические форматы значений.

• shape_only=true имена полей и типы, без значений. Полезно для изучения структуры API во время разработки.

uv run fastmcp call scripts/freeagent_api_caller.py request path=/invoices shape_only=true

Другие опции

Для изменения данных (POST, PUT, DELETE) требуется confirm_write=true. Это намеренное препятствие — ведь это ваши настоящие бухгалтерские записи. Для таких операций используйте песочницу.

[WIP] Коннектор Claude

Ещё не готово. Когда будет готово, вы сможете добавить это в Claude как коннектор и задавать вопросы на обычном языке, а не вызывать эндпоинты самостоятельно:

• Разбирать необъяснённые банковские операции и предлагать, как их категоризировать

• Просматривать отчёт о прибылях и убытках, баланс или оборотно-сальдовую ведомость за период

• Просматривать журнальные проводки или вносить корректировки

• Готовить цифры для деклараций по НДС и налогу на прибыль

• Проверять данные по зарплате и PAYE

• Обдумывать распределение между зарплатой и дивидендами на основе вашей фактической прибыли

• Отслеживать время, задачи и проекты

Отличие от инструмента командной строки в том, что коннектор представляет каждую из этих возможностей как отдельную узкую функцию, а не одну общую команду «вызвать что угодно» — по причинам, описанным в разделе Безопасность ниже.

Для разработчиков

Повседневные команды

uv run pytest                  # run the tests
uv run pytest --lf             # just the ones that failed last time
uv run ruff format .           # auto-format the code
uv run ruff check .            # find likely mistakes and style problems
uv run mypy                    # check the types line up

mypy — тот, который не стоит пропускать: он настроен на строгий режим и ловит целый класс ошибок вида «здесь может быть ничего» до того, как они успеют проявиться.

Проверки при коммите

Git hook запускает все четыре проверки автоматически при каждом коммите. Включите его один раз:

git config core.hooksPath .githooks

Весь набор занимает около двух секунд. Если что-то падает, коммит останавливается, и вы получаете вывод.

Чтобы всё равно сделать коммит, используйте встроенный обходной механизм git:

git commit --no-verify -m "..."

Хук также категорически отказывается коммитить .env, в котором хранятся действующие секрет и access-токен FreeAgent.

Работа над коннектором

# What tools does the server expose, and what do their inputs look like?
uv run fastmcp inspect src/server.py:create_server

# Click through it in a browser
uv run fastmcp dev inspector src/server.py:create_server

Обратите внимание на :create_server в конце — для этих команд нужен файл и имя функции внутри него, которая создаёт сервер, а не только имя файла.

В документации FreeAgent есть пробелы, противоречия и как минимум две ошибки копирования-вставки, поэтому инструменты коннектора спроектированы на основе реальных ответов API, а не документации. Именно для этого нужен описанный выше инструмент командной строки. scripts/freeagent_api_caller.py предназначен только для локального использования и никогда не должен разворачиваться; есть тест, который падает, если этот файл попадёт на развёрнутый сервер.

Обучение

Кэши

После запуска инструментов появляются три каталога. Все они генерируются, находятся в .gitignore и никогда не являются входными данными для программы — удаление любого из них ничего не стоит, кроме более медленного следующего запуска.

• .mypy_cache/ — то, что mypy узнал о типах каждого файла, поэтому повторная проверка неизменённого файла — это чтение из кэша, а не новый анализ. Самый важный: без него каждый запуск заново анализирует информацию о типах всех ваших зависимостей.

• .pytest_cache/ — какие тесты падали в прошлый раз. Именно это обеспечивает работу pytest --lf (last-failed) и --ff (failed-first), позволяя итерировать только по сломанным тестам.

• .ruff_cache/ — результаты линтинга по каждому файлу. Ruff достаточно быстр, и вы вряд ли заметите, если этого кэша не будет.

Если что-то ведёт себя странно, rm -rf .mypy_cache .pytest_cache .ruff_cache — безопасный сброс.

Если вы застряли

Я создал это для бухгалтерских книг своей компании и оформил как следует на случай, если это окажется полезным кому-то ещё.

Если вы пытаетесь настроить что-то подобное и у вас не получается, я занимаюсь такой работой профессионально и готов поговорить.

Если вы нашли баг или что-то здесь не так, приветствуется создание issue.