Финансовый MCP-сервер, выполняющий одну задачу: преобразование PDF-выписок из банка в проверенный JSON, Excel или CSV — не универсальный бухгалтерский MCP. Он работает локально с вашим API-ключом MainBook или через хостируемый эндпоинт MainBook по адресу https://mcp.mainbook.ai/mcp с тем же ключом.
Укажите вашему ассистенту на выписку и попросите создать электронную таблицу. PDF отправляется в MainBook, который извлекает каждую транзакцию, нормализует даты в формат YYYY-MM-DD, сохраняет точные суммы и повторно добавляет выписку так, чтобы начальный баланс + поступления − списания совпадал с конечным балансом. Строки, которые не соответствуют, помечаются, а не передаются молча.
> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.
mainbook - convert_bank_statement (MCP)
63 transactions · 4 pages · 4 credits
Totals reconciled against the statement
Saved to ~/Downloads/march-statement.xlsx
Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match
the statement, and nothing was flagged.Это не подключается к банковским счетам и не является API Open Banking или банковских данных. Он читает файлы выписок, которые у вас уже есть. Ничего не извлекается, и никакие банковские учетные данные не используются.
Учетная запись MainBook и папки с вашими выписками. Конвертация — единственный инструмент, который расходует кредиты страниц. Из остальных четырех get_balance и list_conversions только читают, get_conversion может записать файл результата, а output_folder изменяет локальную настройку; ни один из них не изменяет ничего в вашей учетной записи MainBook.
Один раз войдите из терминала:
uvx mainbook-mcp auth loginКоманда открывает MainBook в вашем браузере, показывает один и тот же короткий код в обоих местах и ожидает вашего подтверждения. Она сохраняет учетные данные в системной связке ключей, если установлен и работает дополнительный пакет keyring. В противном случае используется ~/.config/mainbook/credentials.json с приватными правами на каталог и файл. Используйте mainbook-mcp auth status, чтобы проверить активные учетные данные на стороне сервера без расходования кредитов страниц. mainbook-mcp auth logout сначала отзывает сохраненный ключ, затем удаляет локальную копию; если MainBook недоступен, он прямо сообщает, что ключ может оставаться активным. Повторный вход отзывает ранее сохраненный ключ перед сохранением его замены. Ответ с токеном устройства не содержит email или идентификатор учетной записи, поэтому статус сообщает, что идентификатор учетной записи не был предоставлен, вместо того чтобы гадать.
Затем добавьте одну запись в конфигурацию MCP вашего клиента. Это тот же блок для Claude Desktop (Settings → Developer → Edit Config), Claude Code и Cursor; ключ в него не копируется:
{
"mcpServers": {
"mainbook": {
"command": "uvx",
"args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
}
}
}Codex читает TOML, поэтому поместите то же самое в ~/.codex/config.toml:
[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]uvx поставляется с uv; установите его один раз с помощью brew install uv или curl -LsSf https://astral.sh/uv/install.sh | sh. Он загружает и запускает опубликованный пакет, поэтому ничего не нужно скачивать вручную и обновлять. Если вы не хотите добавлять uv, выполните pip install mainbook-mcp и используйте "command": "mainbook-mcp" с теми же аргументами — тогда вы обновляете его самостоятельно с помощью pip install -U mainbook-mcp.
Аргументы папок — единственные места, откуда сервер может читать выписку или куда записывать результат; все, что за их пределами, отклоняется. MAINBOOK_ALLOWED_DIRS задает тот же список через переменную окружения, разделенный os.pathsep платформы (: на macOS/Linux, ; на Windows).
MAINBOOK_API_KEY имеет приоритет над любым сохраненным входом. Оставьте ручной метод для автоматизации, где интерактивный браузер недоступен. auth login предупреждает, когда эта переменная будет постоянно переопределять только что сохраненные учетные данные:
export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcpСоздавайте и отзывайте ручные ключи на https://mainbook.ai/developer. Никогда не фиксируйте их.
Claude Desktop также принимает однофайловый пакет: Extensions → Install Extension… и выберите mainbook.mcpb. Он запрашивает API-ключ и папки в диалоговом окне и управляет собственным окружением Python, поэтому ничего предварительно устанавливать не нужно. Блок конфигурации выше делает то же самое и лучше подходит, если вы уже храните другие серверы там. Соберите пакет из этого каталога с помощью:
npx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json
npx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpbRelated MCP server: document-to-json-mcp
convert_bank_statement: создает платное задание с кредитами страниц, загружает один PDF, запускает конвертацию, опрашивает до 30–900 секунд и возвращает проверенный результат. JSON остается встроенным. В локальном режиме stdio байты XLSX/CSV записываются на диск, и в контекст модели попадает только полный путь.
get_conversion: проверяет задание после тайм-аута и возвращает JSON встроенно или записывает XLSX/CSV в выбранное локальное место назначения.
list_conversions: возвращает одну страницу курсора заданий учетной записи плюс next_cursor.
get_balance: возвращает общее количество, зарезервированные и доступные кредиты, все измеряется в страницах PDF.
output_folder: читает или изменяет папку результатов по умолчанию.
Локальный режим stdio перечисляет все пять инструментов. Хостируемый HTTP-режим перечисляет ровно первые четыре; output_folder не рекламируется удаленно, потому что диск сервера не принадлежит клиенту.
Нет инструментов для покупки кредитов, платежей, удаления заданий или изменения данных учетной записи. Инструменты, которые могут создать конвертацию, записать локальный файл результата или изменить настройку вывода, помечены как не только для чтения. get_conversion доступен только для чтения через хостируемый HTTP, где он не записывает файлы, и не только для чтения через локальный stdio, где он может записать XLSX или CSV. Ни один не помечен как разрушительный, потому что существующие файлы результатов никогда не заменяются.
Для локальных клиентов stdio (Claude Desktop, Claude Code, Cursor и Codex) результаты XLSX и CSV записываются в первое доступное место назначения в следующем порядке:
output_path, переданный в convert_bank_statement или get_conversion (абсолютное имя файла или существующая папка);
папка, запомненная output_folder;
рядом с исходным PDF, с тем же базовым именем и расширением результата.
get_conversion не может определить исходную папку PDF. Без output_path или действительной запомненной папки он возвращает четкую ошибку вместо того, чтобы угадывать место назначения. Каждый успешный ответ с файлом содержит абсолютный путь и объясняет, какое правило его выбрало. Существующие файлы никогда не заменяются: за statement.xlsx следует statement (2).xlsx, затем (3) и так далее.
Попросите клиента вызвать output_folder без аргументов, чтобы увидеть текущую настройку и все разрешенные папки. Установите ее с помощью разрешенного абсолютного каталога или передайте next_to_source, чтобы восстановить значение по умолчанию. Настройка является общей для локальных клиентов на одной машине в ~/.mainbook/preferences.json. Сохраненная папка, которая отсутствует или больше не разрешена, игнорируется, и это резервное поведение указывается в результате.
JSON остается встроенным. Он также записывается в файл .json только при явном указании output_path. В удаленном HTTP-режиме локальные пути и output_folder недоступны; XLSX/CSV по-прежнему возвращает инструкцию для загрузки через REST, потому что диск сервера не принадлежит клиенту.
Python 3.11 или новее
Учетная запись MainBook
Из этого каталога:
python3 -m venv .venv
.venv/bin/python -m pip install .Чтобы предпочесть системную связку ключей резервному JSON, установите дополнительный пакет в каждом окружении, где выполняется команда входа или локальный сервер:
.venv/bin/python -m pip install '.[keyring]'Используйте обычную установку, а не pip install -e .. В этом репозитории редактируемая установка создает файл .pth, который интерпретатор не подхватывает, поэтому python -m mainbook_mcp завершается с ошибкой "No module named mainbook_mcp", хотя пакет выглядит установленным. Идентичный файл под другим именем обрабатывается, поэтому содержимое в порядке, а причина все еще не объяснена — обычная установка полностью обходит эту проблему.
Если вы используете ручной метод для автоматизации, храните значения mb_live_... в секретной переменной окружения или конфигурации клиента. Никогда не фиксируйте их.
MainBook запускает этот сервер для вас по адресу https://mcp.mainbook.ai/mcp, поэтому клиенту, который использует удаленный MCP, ничего устанавливать не нужно. Укажите ему этот URL и отправьте свой собственный ключ:
Authorization: Bearer mb_live_REPLACE_MEКлюч читается из каждого запроса, поэтому каждый пользователь клиента получает доступ к своей учетной записи MainBook и расходует свои собственные кредиты страниц. initialize и tools/list отвечают без ключа; каждый вызов инструмента требует его. Локальные пути к файлам и output_folder не существуют через HTTP — передавайте file_url вместо file_path, а результаты XLSX или CSV возвращаются как инструкция для загрузки через REST, потому что диск сервера не ваш.
Вы также можете запустить тот же удаленный режим самостоятельно. Это Streamable HTTP без сохранения состояния с JSON-ответами:
mainbook-mcp --transport http --host 127.0.0.1 --port 8000Тогда эндпоинт MCP будет http://127.0.0.1:8000/mcp. Каждый клиент должен отправлять свой собственный заголовок:
Authorization: Bearer mb_live_REPLACE_MEЗаголовок читается из каждого запроса вызова инструмента и никогда не сохраняется в глобальном состоянии. Хостируемый HTTP-режим не проверяет MAINBOOK_API_KEY, системную связку ключей или локальный файл учетных данных. Для удаленного режима Codex:
[mcp_servers.mainbook]
url = "https://mcp.mainbook.ai/mcp"
bearer_token_env_var = "MAINBOOK_API_KEY"
tool_timeout_sec = 920
default_tools_approval_mode = "writes"Замените URL на свой собственный хост, если развертываете это самостоятельно; самостоятельное развертывание все равно требует обычного HTTPS-терминирования и контроля доступа.
MAINBOOK_API_KEY: необязателен в stdio и имеет приоритет над сохраненным входом; игнорируется в HTTP-режиме, где каждый вызов инструмента должен нести свой собственный заголовок Bearer.
MAINBOOK_API_BASE_URL: REST-хост, по умолчанию https://api.mainbook.ai. Сервер добавляет /api/v1/developer.
MAINBOOK_ALLOWED_DIRS: локальные папки, разрешенные для чтения исходных файлов и записи результатов, разделенные os.pathsep платформы (: на macOS/Linux и ; на Windows). Аргументы каталогов в командной строке имеют приоритет. Если ни то, ни другое не указано, по умолчанию используются ~/Downloads, ~/Desktop и ~/Documents.
MAINBOOK_MCP_TRANSPORT: stdio (по умолчанию) или http.
MAINBOOK_MCP_HOST: HTTP-хост привязки, по умолчанию 127.0.0.1.
MAINBOOK_MCP_PORT: HTTP-порт привязки, по умолчанию 8000.
file_path и file_url являются взаимоисключающими. file_path принимается только через локальный stdio; HTTP-режим отклоняет его до того, как запустится загрузчик файловой системы, и требует file_url.
Доступ к локальному file_path и запись результирующих файлов используют одни и те же настроенные папки. Приоритет имеют директории, переданные через CLI, перед MAINBOOK_ALLOWED_DIRS; переменная окружения имеет приоритет над значениями по умолчанию: ~/Downloads, ~/Desktop и ~/Documents. Каждый корень раскрывается и разрешается, отсутствующие корни игнорируются, а активные корни выводятся в stderr при запуске сервера. Если корней не осталось, локальный доступ блокируется с отказом, а сервер продолжает работу.
Родительские каталоги выходных файлов разрешаются перед записью и проверяются по идентификатору каталога, поэтому символическая ссылка не может перенаправить результат за пределы разрешенных папок. Создание результата является эксклюзивным и безопасным в плане коллизий; существующие файлы не перезаписываются.
~/.mainbook/preferences.json заменяется атомарно. Каталог .mainbook имеет режим 0700, а файл настроек — 0600; некорректные или нечитаемые настройки безопасно игнорируются.
Учетные данные терминала используют связку ключей ОС, если опциональный пакет доступен. Резервный файл ~/.config/mainbook/credentials.json заменяется атомарно внутри каталога с режимом 0700 и имеет режим 0600; его записи верхнего уровня ключевы по базовому URL API.
Локальные пути раскрываются и строго разрешаются перед проверкой белого списка, поэтому .. и символические ссылки не могут заставить цель, находящуюся снаружи, выглядеть так, будто она находится внутри разрешенной папки. Разрешенный путь должен находиться строго ниже корня, а не совпадать с самим корнем.
Локальный файл открывается один раз. Сервер использует fstat для этого дескриптора, чтобы проверить, что это обычный файл, и применить ограничение в 50 МиБ, после чего выполняет ограниченное чтение через тот же дескриптор. Это закрывает окно подмены между проверкой и чтением, но не полностью устраняет состояние гонки между разрешением пути и его открытием; в течение этого интервала путь всё ещё может быть заменен.
Локальный файл должен содержать %PDF- в своих первых 1024 байтах, прежде чем будет вызван pypdf. Расширения имен файлов не используются для определения того, является ли файл PDF.
Удаленные файлы должны использовать HTTPS. Перенаправления не отслеживаются.
DNS-ответы отклоняются, если какой-либо адрес является частным, loopback, link-local, метаданных, зарезервированным или иным образом непубличным, для IPv4 и IPv6.
Загрузки по URL подключаются к уже проверенному числовому IP-адресу, сохраняя исходное имя хоста для проверки TLS-сертификата и HTTP-заголовка Host, что предотвращает состояние гонки, связанное с повторной привязкой DNS.
Content-Length и фактическое количество переданных байтов независимо ограничены 50 МиБ.
PDF-файлы обрабатываются локально с помощью pypdf и ограничены 500 страницами.
Заголовки предварительно подписанных загрузок от MainBook передаются без изменений; ключ Bearer MainBook никогда не отправляется в хранилище.
.venv/bin/python -m pip install '.[dev]'
.venv/bin/pytest
.venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate
.venv/bin/ruff check .Все REST-тесты используют заглушки или локальный стенд. Ни один тест не требует и не принимает реальный ключ API MainBook.
Convert one PDF bank statement through the complete MainBook workflow: create a job, upload, start, poll, and return structured data. This creates a job and spends page credits; it is not read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | No | Public HTTPS URL of a PDF for remote mode. Redirects and non-public network addresses are rejected. Exactly one source is required. | |
| file_path | No | Path to a PDF on the MCP server machine. This field is only available over stdio and is rejected in HTTP mode; remote clients must use file_url. The path must be inside the allowed folders, which default to Downloads, Desktop, and Documents. Exactly one of file_path and file_url is required. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. The file extension is corrected to match result_type. | |
| result_type | No | JSON is returned inline. Over stdio, XLSX or CSV is written to an allowed local folder and the full path is returned. HTTP mode returns safe download instructions. Binary bytes never enter model context. | json |
| idempotency_key | No | Optional value forwarded verbatim in the Idempotency-Key REST header. | |
| timeout_seconds | No | Internal polling budget from 30 to 900 seconds. Timeout leaves the job running and returns its job_id for get_conversion. The default stays under the 60-second request timeout most MCP clients enforce; a client that gives up first discards the job_id and the conversion looks lost. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description adds value by explicitly stating the workflow creates a job, spends page credits, and is not read-only. It does not contradict any annotation and provides useful behavioral context beyond the boolean hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that are front-loaded and highly efficient. The first sentence immediately conveys the action and workflow; the second adds critical behavioral context. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multi-step workflow, 6 parameters, output schema exists), the description covers the high-level workflow and side effects. It could briefly mention that results can be inline JSON or file-based (from result_type), but the parameter descriptions and output schema fill that gap. Overall complete for an agent to understand purpose and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The overall description does not add parameter-specific meaning, but the individual parameter descriptions are already thorough. The tool description appropriately focuses on the overall workflow rather than repeating schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Convert one PDF bank statement' with a specific verb and resource, and outlines the complete workflow (create, upload, start, poll, return). It explicitly distinguishes itself from read-only siblings (get_balance, get_conversion) by stating 'it is not read-only' and 'spends page credits'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the primary conversion tool and notes it is not read-only, giving clear context for use. However, it does not explicitly state when not to use it or reference alternatives like list_conversions or get_conversion for post-processing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return total, reserved, and available MainBook credits. Every value is measured in PDF pages.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| units | No | |
| balance | Yes | |
| reserved | Yes | |
| available | Yes | |
| explanation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a read-only, externally mutable resource. The description adds clarity by specifying the exact credits (total, reserved, available) and confirming the unit (PDF pages). No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, dense sentences with no wasted words. The first sentence states what the tool returns, the second clarifies the measurement unit. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description fully covers the purpose, items returned, and units. The output schema presumably details the structure, so no additional return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and there are no parameters to document. The description provides the meaning of the return values (total, reserved, available) which is helpful, but since there are no params, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and identifies the resource ('MainBook credits') and three precise items (total, reserved, available). It distinguishes itself from siblings like 'convert_bank_statement' or 'list_conversions' by being clearly a balance/account query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an agent needs to check credit balances before performing PDF-related operations. It does not explicitly state when not to use it or name alternatives, but with 0 params and a dedicated name, its niche is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current state of one MainBook conversion. When successful, return JSON inline or save XLSX/CSV locally over stdio. HTTP mode returns safe download instructions. Use this after convert_bank_statement times out.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Conversion job UUID returned by MainBook. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. | |
| result_type | No | Result representation to retrieve after the job succeeds. | json |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by explaining output modes (inline JSON, local file save over stdio, HTTP download instructions). However, it does not disclose potential side effects or whether repeated polling affects the conversion state. The annotations (readOnlyHint: false, openWorldHint: true) signal uncertainty, but the description does not fully address behavioral traits like idempotency or changes to the conversion state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy. The first sentence states the purpose, the next two explain behavior in different modes, and the last gives a usage hint. Every sentence adds value, and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (polling tool with output schema and sibling tools), the description covers output modes and when to use it, but it lacks guidance on polling frequency, lifecycle (one-time or repeatable), and failure handling. The existence of an output schema reduces the burden for return values, but more context on the polling workflow would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description in the schema (job_id, output_path, result_type). The tool description does not add any additional parameter semantics beyond what the schema already provides. With full coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the current state of one MainBook conversion, using a specific verb ('Get') and resource ('one MainBook conversion'). It effectively distinguishes from siblings: convert_bank_statement is the preceding step, list_conversions lists all conversions, and get_balance is unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Use this after convert_bank_statement times out.' This tells the agent exactly when to invoke this tool. While it does not explicitly state when not to use it or list alternatives beyond the sibling set, the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List one cursor page of conversion jobs visible to the MainBook account. Pass the returned next_cursor to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Jobs on this page, from 1 to 100. | |
| cursor | No | Opaque next_cursor from the previous page. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| units | No | |
| conversions | Yes | |
| next_cursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context beyond that: it clarifies scope ('visible to the MainBook account') and the cursor-based pagination mechanism. This extra detail is valuable for an agent deciding how to interact with the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The first sentence states the core purpose and scope; the second gives the key usage instruction for pagination. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (pagination list with two parameters), full schema coverage, presence of an output schema, and comprehensive annotations, the description is complete. It does not need to explain return values (output schema covers that) and provides all necessary usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both limit and cursor. The description mentions 'cursor page' and 'next_cursor,' reinforcing the cursor parameter's role but adding no new semantic detail beyond what the schema already provides. Baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List one cursor page of conversion jobs visible to the MainBook account.' It uses a specific verb ('list'), resource ('conversion jobs'), and includes scope constraints ('one cursor page', 'MainBook account'), effectively distinguishing it from sibling tools like get_conversion (single item) and convert_bank_statement (action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the agent to 'Pass the returned next_cursor to continue,' providing clear pagination usage. It implies the tool is for listing pages of conversions but does not explicitly state when not to use it or compare to alternatives. However, given distinct siblings, the guidance is effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or change the default local result folder. Call with no path to inspect the current setting and allowed folders. Pass an allowed absolute folder, or 'next_to_source' to restore the default behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Allowed absolute folder to remember, or 'next_to_source' to reset. Omit to read without changing anything. |
| Name | Required | Description |
|---|---|---|
| message | Yes | |
| output_folder | Yes | |
| allowed_folders | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. Description adds context about inspecting vs changing, 'allowed folders' restriction, and special 'next_to_source' value. This enriches the behavioral model beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, output schema present, and clear annotations, the description covers all needed context: read vs write, allowed folder restriction, reset behavior. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description aligns perfectly. Both clarify that omitting path reads, providing a path changes it, and 'next_to_source' is a special reset value. No gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read or change the default local result folder' with specific verbs and resource. It distinguishes from siblings which deal with bank statements and balances, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Call with no path to inspect the current setting' for read, 'Pass an allowed absolute folder, or 'next_to_source' to restore' for write. No sibling overlap requires exclusion clauses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.1convert_bank_statementget_balanceget_conversionlist_conversionsoutput_folderEach tool has a clearly distinct purpose: convert_bank_statement handles submission, get_balance checks credits, list_conversions enumerates jobs, get_conversion retrieves state/results, and output_folder manages local storage. No overlap in functionality.
Tool names mostly follow a verb_noun pattern with consistent snake_case. 'convert_bank_statement', 'get_balance', 'list_conversions', and 'get_conversion' are clear. 'output_folder' is slightly less standard as a verb but still readable and consistent in style.
Five tools cover the core workflows for a PDF statement converter: submission, credit monitoring, job listing, status retrieval, and output configuration. This is well-scoped without unnecessary extras or missing essentials.
The set provides a complete lifecycle for converting statements: submit, monitor progress, retrieve results, manage output folder, and check credits. Minor gaps like cancel/delete are absent but not critical given the workflow's design.
Convert PDF bank statements into structured transactions, accounts, and balances.
Turn bank statement PDFs, CSVs, XLSX and OFX into categorised transactions plus a summary.
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.
PDF tools + invoice extraction, bank statement parsing, GST reconciliation & GSTIN validation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/human-beyond/mainbook-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
