Ein MCP-Server für Finanzen, der auf eine Aufgabe zugeschnitten ist: PDF-Kontoauszüge in geprüftes JSON, Excel oder CSV umzuwandeln – kein allgemeiner Buchhaltungs-MCP. Er läuft lokal mit Ihrem MainBook-API-Schlüssel oder über MainBooks gehosteten Endpunkt unter https://mcp.mainbook.ai/mcp mit demselben Schlüssel.
Weisen Sie Ihren Assistenten auf einen Auszug hin und bitten Sie um eine Tabelle. Das PDF geht an MainBook, das jede Transaktion extrahiert, Daten auf YYYY-MM-DD normalisiert, Geldbeträge exakt hält und den Auszug nachrechnet, sodass Anfangsbestand + Gutschriften – Belastungen mit dem Endbestand übereinstimmen muss. Zeilen, die nicht passen, werden markiert, anstatt stillschweigend weitergegeben zu werden.
> 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.Es verbindet sich nicht mit Bankkonten und ist keine Open-Banking- oder Bankdaten-API. Es liest Kontoauszugsdateien, die Sie bereits besitzen. Es wird nichts gescrapt und keine Bankzugangsdaten werden verwendet.
Ein MainBook-Konto und die Ordner, die Ihre Kontoauszüge enthalten. Die Konvertierung ist das einzige Tool, das Seitencredits verbraucht. Von den anderen vier lesen get_balance und list_conversions nur, get_conversion kann eine Ergebnisdatei schreiben, und output_folder ändert eine lokale Einstellung; keines von ihnen ändert etwas in Ihrem MainBook-Konto.
Einmalig von einem Terminal aus anmelden:
uvx mainbook-mcp auth loginDer Befehl öffnet MainBook in Ihrem Browser, zeigt denselben Kurzcode an beiden Stellen und wartet auf Ihre Zustimmung. Er speichert die Anmeldedaten im OS-Keyring, wenn das optionale Paket keyring installiert und funktionsfähig ist. Andernfalls verwendet er ~/.config/mainbook/credentials.json mit privaten Verzeichnis- und Dateiberechtigungen. Verwenden Sie mainbook-mcp auth status, um die aktive Anmeldedaten serverseitig zu überprüfen, ohne Seitencredits zu verbrauchen. mainbook-mcp auth logout widerruft zuerst den gespeicherten Schlüssel, entfernt dann die lokale Kopie; falls MainBook nicht erreichbar ist, wird klar gesagt, dass der Schlüssel möglicherweise noch aktiv ist. Eine erneute Anmeldung widerruft den zuvor gespeicherten Schlüssel, bevor der Ersatz gespeichert wird. Die Geräte-Token-Antwort enthält weder eine E-Mail noch eine Konto-ID, daher gibt der Status an, dass die Kontoidentität nicht bereitgestellt wurde, anstatt zu raten.
Fügen Sie dann einen Eintrag zur MCP-Konfiguration Ihres Clients hinzu. Dieser Block ist für Claude Desktop (Einstellungen → Entwickler → Konfiguration bearbeiten), Claude Code und Cursor identisch; kein Schlüssel wird hineinkopiert:
{
"mcpServers": {
"mainbook": {
"command": "uvx",
"args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
}
}
}Codex liest TOML, daher setzen Sie dasselbe in ~/.codex/config.toml:
[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]uvx wird mit uv ausgeliefert; installieren Sie es einmal mit brew install uv oder curl -LsSf https://astral.sh/uv/install.sh | sh. Es ruft das veröffentlichte Paket ab und führt es aus, sodass nichts manuell heruntergeladen oder aktualisiert werden muss. Wenn Sie uv nicht hinzufügen möchten, führen Sie pip install mainbook-mcp aus und verwenden Sie "command": "mainbook-mcp" mit denselben Argumenten – Sie aktualisieren es dann selbst mit pip install -U mainbook-mcp.
Die Ordnerargumente sind die einzigen Orte, von denen der Server einen Auszug lesen oder ein Ergebnis schreiben darf; alles außerhalb wird abgelehnt. MAINBOOK_ALLOWED_DIRS setzt dieselbe Liste über die Umgebungsvariable, getrennt durch das plattformspezifische os.pathsep (: auf macOS/Linux, ; auf Windows).
MAINBOOK_API_KEY hat Vorrang vor jedem gespeicherten Login. Behalten Sie die manuelle Methode für die Automatisierung bei, wenn kein interaktiver Browser verfügbar ist. auth login warnt, wenn diese Variable die neu gespeicherte Anmeldeinformation weiterhin überschreibt:
export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcpErstellen und widerrufen Sie manuelle Schlüssel unter https://mainbook.ai/developer. Übergeben Sie sie niemals.
Claude Desktop akzeptiert auch ein Ein-Datei-Bundle: Extensions → Install Extension… und wählen Sie mainbook.mcpb aus. Es fragt nach dem API-Schlüssel und den Ordnern in einem Dialog und verwaltet seine eigene Python-Laufzeitumgebung, sodass nichts zuerst installiert werden muss. Der obige Konfigurationsblock erfüllt denselben Zweck und ist besser geeignet, wenn Sie dort bereits andere Server verwalten. Erstellen Sie das Bundle aus diesem Verzeichnis mit:
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: Erstellt einen kostenpflichtigen Seitencredit-Job, lädt ein PDF hoch, startet die Konvertierung, fragt bis zu 30-900 Sekunden ab und gibt das geprüfte Ergebnis zurück. JSON bleibt inline. Im lokalen Stdio-Modus werden XLSX/CSV-Bytes auf die Festplatte geschrieben und nur der vollständige Pfad gelangt in den Modellkontext.
get_conversion: Überprüft einen Job nach einem Timeout und gibt JSON inline zurück oder schreibt XLSX/CSV an ein gewähltes lokales Ziel.
list_conversions: Gibt eine Cursor-Seite von Konto-Jobs plus next_cursor zurück.
get_balance: Gibt insgesamt, reservierte und verfügbare Credits zurück, alle gemessen in PDF-Seiten.
output_folder: Liest oder ändert den standardmäßigen lokalen Ergebnisordner.
Der lokale Stdio-Modus listet alle fünf Tools. Der gehostete HTTP-Modus listet genau die ersten vier; output_folder wird nicht remote angeboten, da die Festplatte des Servers nicht dem Client gehört.
Es gibt keine Tools zum Kaufen von Credits, Zahlungen, Löschen von Jobs oder Ändern von Kontodaten. Tools, die eine Konvertierung erstellen, eine lokale Ergebnisdatei schreiben oder die Ausgabeeinstellung ändern können, sind als nicht schreibgeschützt markiert. get_conversion ist über gehostetes HTTP schreibgeschützt, wo es keine Datei schreibt, und über lokales Stdio nicht schreibgeschützt, wo es XLSX oder CSV schreiben kann. Keines ist als destruktiv markiert, da vorhandene Ergebnisdateien nie ersetzt werden.
Für lokale Stdio-Clients (Claude Desktop, Claude Code, Cursor und Codex) werden XLSX- und CSV-Ergebnisse in der folgenden Reihenfolge an das erste verfügbare Ziel geschrieben:
output_path, das an convert_bank_statement oder get_conversion übergeben wurde (ein absoluter Dateiname oder ein vorhandener Ordner);
der von output_folder gemerkte Ordner;
neben dem Quell-PDF, mit demselben Basisnamen und der Ergebnis-Erweiterung.
get_conversion kann den ursprünglichen PDF-Ordner nicht ableiten. Ohne output_path oder einen gültigen gemerkten Ordner gibt es einen klaren Fehler zurück, anstatt ein Ziel zu erraten. Jede erfolgreiche Datei-Antwort enthält den absoluten Pfad und erklärt, welche Regel ihn ausgewählt hat. Vorhandene Dateien werden nie ersetzt: Auf statement.xlsx folgt statement (2).xlsx, dann (3), und so weiter.
Bitten Sie den Client, output_folder ohne Argument aufzurufen, um die aktuelle Einstellung und alle erlaubten Ordner anzuzeigen. Setzen Sie es mit einem erlaubten absoluten Verzeichnis oder übergeben Sie next_to_source, um die Standardeinstellung wiederherzustellen. Die Einstellung wird von lokalen Clients auf demselben Rechner in ~/.mainbook/preferences.json geteilt. Ein gespeicherter Ordner, der fehlt oder nicht mehr erlaubt ist, wird ignoriert, und dieser Rückfall wird im Ergebnis angegeben.
JSON bleibt inline. Es wird nur dann in eine .json-Datei geschrieben, wenn ein explizites output_path angegeben wird. Im Remote-HTTP-Modus sind lokale Pfade und output_folder nicht verfügbar; XLSX/CSV gibt weiterhin eine REST-Download-Anweisung zurück, da die Serverfestplatte nicht dem Client gehört.
Python 3.11 oder neuer
Ein MainBook-Konto
Aus diesem Verzeichnis:
python3 -m venv .venv
.venv/bin/python -m pip install .Um den OS-Keyring gegenüber dem privaten JSON-Rückfall zu bevorzugen, installieren Sie das optionale Extra in jeder Umgebung, die den Login-Befehl oder den lokalen Server ausführt:
.venv/bin/python -m pip install '.[keyring]'Verwenden Sie eine einfache Installation, nicht pip install -e .. In diesem Checkout schreibt die editierbare Installation eine .pth-Datei, die der Interpreter nicht aufnimmt, sodass python -m mainbook_mcp mit "No module named mainbook_mcp" fehlschlägt, während das Paket installiert aussieht. Eine identische Datei unter einem anderen Namen wird akzeptiert, sodass der Inhalt in Ordnung ist und die Ursache weiterhin ungeklärt ist – eine einfache Installation umgeht das vollständig.
Wenn Sie die manuelle Methode für die Automatisierung verwenden, bewahren Sie mb_live_...-Werte in einer geheimen Umgebung oder Client-Konfiguration auf. Übergeben Sie sie niemals.
MainBook betreibt diesen Server für Sie unter https://mcp.mainbook.ai/mcp, sodass ein Client, der Remote-MCP spricht, nichts installieren muss. Richten Sie ihn auf diese URL und senden Sie Ihren eigenen Schlüssel:
Authorization: Bearer mb_live_REPLACE_MEDer Schlüssel wird aus jeder Anfrage gelesen, sodass jeder Benutzer eines Clients auf sein eigenes MainBook-Konto zugreift und seine eigenen Seitencredits verbraucht. initialize und tools/list antworten ohne Schlüssel; jeder Tool-Aufruf erfordert einen. Lokale Dateipfade und output_folder existieren über HTTP nicht – übergeben Sie file_url anstelle von file_path, und XLSX- oder CSV-Ergebnisse kommen als REST-Download-Anweisung zurück, da die Festplatte des Servers nicht Ihre ist.
Sie können denselben Remote-Modus auch selbst ausführen. Es ist zustandsloses Streamable HTTP mit JSON-Antworten:
mainbook-mcp --transport http --host 127.0.0.1 --port 8000Der MCP-Endpunkt ist dann http://127.0.0.1:8000/mcp. Jeder Client sollte seinen eigenen Header senden:
Authorization: Bearer mb_live_REPLACE_MEDer Header wird aus jeder Tool-Call-Anfrage gelesen und nie im globalen Zustand gespeichert. Der gehostete HTTP-Modus prüft weder MAINBOOK_API_KEY, den OS-Keyring noch die lokale Anmeldedatendatei. Für den Codex-Remote-Modus:
[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"Ersetzen Sie die URL durch Ihren eigenen Host, wenn Sie dies selbst bereitstellen; eine selbst gehostete Bereitstellung benötigt weiterhin normale HTTPS-Terminierung und Zugriffskontrollen.
MAINBOOK_API_KEY: optional im Stdio-Modus und hat Vorrang vor einem gespeicherten Login; im HTTP-Modus ignoriert, wo jeder Tool-Aufruf seinen eigenen Bearer-Header tragen muss.
MAINBOOK_API_BASE_URL: REST-Host, Standard https://api.mainbook.ai. Der Server hängt /api/v1/developer an.
MAINBOOK_ALLOWED_DIRS: lokale Ordner, die für Quell-Lese- und Ergebnis-Schreibvorgänge erlaubt sind, getrennt durch das plattformspezifische os.pathsep (: auf macOS/Linux und ; auf Windows). Positionsargumente für Verzeichnisse haben Vorrang. Wenn keines angegeben wird, sind die Standardeinstellungen ~/Downloads, ~/Desktop und ~/Documents.
MAINBOOK_MCP_TRANSPORT: stdio (Standard) oder http.
MAINBOOK_MCP_HOST: HTTP-Bind-Host, Standard 127.0.0.1.
MAINBOOK_MCP_PORT: HTTP-Bind-Port, Standard 8000.
file_path und file_url schließen sich gegenseitig aus. file_path wird nur über lokales stdio akzeptiert; der HTTP-Modus lehnt es ab, bevor der Dateisystem-Loader läuft, und erfordert file_url.
Lokaler file_path-Zugriff und das Schreiben von Ergebnisdateien verwenden dieselben konfigurierten Ordner. Positionelle CLI-Verzeichnisse haben Vorrang vor MAINBOOK_ALLOWED_DIRS; die Umgebungsvariable hat Vorrang vor den Standardverzeichnissen ~/Downloads, ~/Desktop und ~/Documents. Jeder Wurzelordner wird erweitert und aufgelöst, fehlende Wurzelordner werden ignoriert, und die aktiven Wurzelordner werden beim Start des Servers auf stderr ausgegeben. Wenn keine Wurzelordner übrig bleiben, schlägt der lokale Zugriff geschlossen fehl, während der Server weiterläuft.
Ausgabe-Elternverzeichnisse werden vor dem Schreiben aufgelöst und anhand der Verzeichnisidentität überprüft, sodass ein Symlink ein Ergebnis nicht außerhalb der erlaubten Ordner umleiten kann. Die Erstellung von Ergebnissen ist exklusiv und kollisionssicher; vorhandene Dateien werden nicht überschrieben.
~/.mainbook/preferences.json wird atomar ersetzt. Das Verzeichnis .mainbook hat den Modus 0700 und die Präferenzdatei den Modus 0600; fehlerhafte oder nicht lesbare Präferenzen werden sicher ignoriert.
Terminal-Anmeldeinformationen verwenden den OS-Keyring, wenn das optionale Paket verwendbar ist. Der Fallback ~/.config/mainbook/credentials.json wird atomar innerhalb eines Verzeichnisses mit Modus 0700 ersetzt und hat den Modus 0600; seine Einträge auf oberster Ebene sind nach der API-Basis-URL verschlüsselt.
Lokale Pfade werden vor der Überprüfung der Zulassungsliste erweitert und streng aufgelöst, sodass .. und Symlinks ein externes Ziel nicht als innerhalb eines erlaubten Ordners erscheinen lassen können. Der aufgelöste Pfad muss strikt unter einem Wurzelordner liegen, nicht gleich dem Wurzelordner selbst.
Die lokale Datei wird einmal geöffnet. Der Server verwendet fstat auf diesem Deskriptor, um eine reguläre Datei zu erzwingen und das 50-MiB-Limit durchzusetzen, und führt dann die begrenzte Leseoperation über denselben Deskriptor durch. Dies schließt das Fenster für den Austausch zwischen Prüfung und Lesen, beseitigt jedoch nicht vollständig die Race-Bedingung zwischen dem Auflösen des Pfades und dem Öffnen; der Pfad kann in diesem Intervall immer noch ersetzt werden.
Eine lokale Datei muss innerhalb der ersten 1024 Bytes %PDF- enthalten, bevor pypdf aufgerufen wird. Dateinamenserweiterungen werden nicht verwendet, um zu entscheiden, ob eine Datei ein PDF ist.
Remote-Dateien müssen HTTPS verwenden. Weiterleitungen werden nicht verfolgt.
DNS-Antworten werden abgelehnt, wenn irgendeine Adresse privat, Loopback, link-lokal, Metadaten, reserviert oder anderweitig nicht öffentlich ist, sowohl für IPv4 als auch IPv6.
URL-Downloads verbinden sich mit einer bereits validierten numerischen IP, während der ursprüngliche Hostname für die TLS-Zertifikatsprüfung und den HTTP-Host-Header beibehalten wird, wodurch DNS-Rebinding-Race-Bedingungen geschlossen werden.
Content-Length und die tatsächliche gestreamte Byte-Anzahl sind unabhängig voneinander auf 50 MiB begrenzt.
PDFs werden lokal mit pypdf geparst und auf 500 Seiten begrenzt.
Vorsignierte Upload-Header von MainBook werden unverändert weitergeleitet; der MainBook Bearer-Schlüssel wird nie an den Speicher gesendet.
.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 .Alle REST-Tests verwenden Mocks oder einen lokalen Stub. Kein Test erfordert oder akzeptiert einen echten MainBook-API-Schlüssel.
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
