**一个专注于单一任务的金融 MCP 服务器：将 PDF 银行对账单转换为经过校验的 JSON、Excel 或 CSV——而非通用会计工具。**它可在本地使用你的 MainBook API 密钥运行，也可通过 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。它读取你已经拥有的对账单文件。不会抓取任何数据，也不涉及银行凭证。
一个 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，它会明确说明密钥可能仍处于活动状态。重新登录会先撤销此前存储的密钥，再保存替换密钥。设备令牌响应不包含邮箱或账户 ID，因此状态会如实显示未提供账户身份，而非进行猜测。
然后在客户端的 MCP 配置中添加一项。以下代码块适用于 Claude Desktop（设置 → 开发者 → 编辑配置）、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 也接受单文件包：扩展 → 安装扩展… 并选择 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 结果将按以下顺序写入第一个可用的目标：
convert_bank_statement 或 get_conversion 提供的 output_path（绝对文件名或已存在的文件夹）；
由 output_folder 记住的文件夹；
源 PDF 旁边，使用相同的基本名称和结果扩展名。
get_conversion 无法推断原始 PDF 文件夹。如果没有 output_path 或有效的已记住文件夹，它会返回一个清晰的错误信息，而非猜测目标。每个成功的文件响应都包含绝对路径，并说明选择该路径的规则。现有文件永远不会被替换：statement.xlsx 后面是 statement (2).xlsx，然后是 (3)，依此类推。
要求客户端不带参数调用 output_folder 以查看当前设置和所有允许的文件夹。使用允许的绝对目录进行设置，或传递 next_to_source 以恢复默认值。该偏好由同一台机器上的本地客户端共享，存储在 ~/.mainbook/preferences.json 中。已保存的文件夹如果缺失或不再允许，则会被忽略，并在结果中说明回退情况。
JSON 保持内联。仅当提供了显式的 output_path 时，才会写入 .json 文件。在远程 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 8000MCP 端点随后为 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；其顶层条目以 API 基础 URL 为键。
本地路径在允许列表检查前会被展开并严格解析，因此 .. 和符号链接无法使外部目标看起来位于允许文件夹内。解析后的路径必须严格位于根目录之下，而不能等于根目录本身。
本地文件只打开一次。服务器使用 fstat 对该文件描述符进行检查，要求其为常规文件并强制执行 50 MiB 限制，然后通过同一文件描述符执行有界读取。这关闭了检查与读取之间的替换窗口，但并未完全消除解析路径与打开文件之间的竞态条件；在此期间路径仍可能被替换。
在调用 pypdf 之前，本地文件必须在其前 1024 字节内包含 %PDF-。文件扩展名不用于判断文件是否为 PDF。
远程文件必须使用 HTTPS。不跟随重定向。
如果 DNS 应答中的任何地址是私有的、回环的、链路本地的、元数据的、保留的或非公开的（包括 IPv4 和 IPv6），则该应答被拒绝。
URL 下载连接到已验证的数字 IP，同时保留原始主机名用于 TLS 证书验证和 HTTP Host 标头，从而消除 DNS 重新绑定竞态条件。
Content-Length 和实际的流式字节数分别以 50 MiB 为上限。
PDF 使用 pypdf 在本地解析，页数上限为 500 页。
来自 MainBook 的预签名上传标头原样转发；MainBook Bearer 密钥永远不会发送到存储。
.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 测试均使用模拟或本地存根。没有测试需要或接受真实的 MainBook API 密钥。
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
