財務に特化したMCPサーバーで、やることは1つだけ：PDFの銀行口座明細を検証済みのJSON、Excel、またはCSVに変換することです。汎用的な会計MCPではありません。 これはローカルで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.銀行口座に接続しません。Open Bankingや銀行データAPIではありません。あなたが既に持っている明細ファイルを読み取ります。スクレイピングは一切行わず、銀行の認証情報は一切関与しません。
MainBookアカウントと、明細が保存されているフォルダーです。変換だけがページクレジットを消費するツールです。残りの4つのツールのうち、get_balance と list_conversions は読み取りのみ、get_conversion は結果ファイルを書き込む可能性があり、output_folder はローカルの設定を変更します。いずれもMainBookアカウント内のデータを変更することはありません。
ターミナルから一度サインインします：
uvx mainbook-mcp auth loginこのコマンドはブラウザでMainBookを開き、両方の場所に同じ短いコードを表示し、承認を待ちます。オプションの keyring パッケージがインストールされて動作している場合は、OSのキーリングに認証情報を保存します。それ以外の場合は、プライベートなディレクトリとファイル権限を持つ ~/.config/mainbook/credentials.json を使用します。mainbook-mcp auth status で、ページクレジットを消費せずにサーバー側のアクティブな認証情報を確認できます。mainbook-mcp auth logout は、まず保存されたキーを取り消し、次にローカルコピーを削除します。MainBookに到達できない場合は、キーがまだアクティブである可能性があることを明示します。再度サインインすると、新しいキーを保存する前に以前に保存されたキーを取り消します。デバイストークンの応答にはメールアドレスやアカウントIDは含まれないため、ステータスはアカウントの識別情報が提供されなかったと表示します（推測はしません）。
次に、クライアントのMCP設定に1つのエントリを追加します。これは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：有料のページクレジットジョブを作成し、1つのPDFをアップロードし、変換を開始し、最大30〜900秒間ポーリングし、レビュー済みの結果を返します。JSONはインラインのままです。ローカルのstdioモードでは、XLSX/CSVのバイトはディスクに書き込まれ、完全なパスだけがモデルコンテキストに入ります。
get_conversion：タイムアウト後にジョブを確認し、JSONをインラインで返すか、XLSX/CSVを選択したローカル保存先に書き込みます。
list_conversions：アカウントのジョブの1カーソルページと next_cursor を返します。
get_balance：合計、予約済み、利用可能なクレジット（すべてPDFページ数）を返します。
output_folder：デフォルトのローカル結果フォルダーを読み取りまたは変更します。
ローカルのstdioモードでは5つのツールすべてがリストされます。ホストされたHTTPモードでは、最初の4つだけがリストされます。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 .OSのキーリングをプライベートJSONのフォールバックより優先するには、ログインコマンドまたはローカルサーバーを実行するすべての環境でオプションの追加パッケージをインストールします：
.venv/bin/python -m pip install '.[keyring]'通常のインストールを使用し、pip install -e . は使用しないでください。このチェックアウトでは、editableインストールは .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 はキーなしで応答します。すべてのツール呼び出しにはキーが必要です。HTTPではローカルファイルパスと output_folder は存在しません。file_path の代わりに file_url を渡し、XLSXまたはCSVの結果はRESTダウンロード指示として返されます。サーバーのディスクはあなたのものではないからです。
同じリモートモードを自分で実行することもできます。ステートレスなストリーミング可能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、OSキーリング、またはローカルの認証情報ファイルを調べません。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 に出力されます。ルートが残っていない場合、ローカルアクセスはフェイルクローズし、サーバーは実行を継続します。
出力親ディレクトリは書き込み前に解決され、ディレクトリ ID に基づいてチェックされるため、シンボリックリンクで結果を許可フォルダ外にリダイレクトすることはできません。結果の作成は排他的で衝突安全であり、既存のファイルは上書きされません。
~/.mainbook/preferences.json はアトミックに置き換えられます。.mainbook ディレクトリのモードは 0700、設定ファイルのモードは 0600 です。不正または読み取り不能な設定は安全に無視されます。
ターミナル資格情報は、オプションパッケージが使用可能な場合は OS キーリングを使用します。フォールバックの ~/.config/mainbook/credentials.json は、モード 0700 のディレクトリ内でアトミックに置き換えられ、モードは 0600 です。そのトップレベルのエントリは API ベース URL でキー付けされます。
ローカルパスは許可リストチェックの前に展開および厳密に解決されるため、.. やシンボリックリンクで外部のターゲットを許可フォルダ内にあるように見せかけることはできません。解決されたパスはルートの厳密に下にある必要があり、ルート自体と等しくてはなりません。
ローカルファイルは 1 回だけ開かれます。サーバーはそのディスクリプタで 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
