Un servidor MCP financiero centrado en una sola tarea: convertir extractos bancarios en PDF a JSON, Excel o CSV verificados, no un MCP de contabilidad general. Se ejecuta localmente con tu clave API de MainBook, o a través del endpoint alojado de MainBook en https://mcp.mainbook.ai/mcp con esa misma clave.
Señala a tu asistente un extracto y pídele una hoja de cálculo. El PDF se envía a MainBook, que extrae cada transacción, normaliza las fechas a YYYY-MM-DD, mantiene el dinero como cantidades exactas y vuelve a añadir el extracto para que saldo inicial + ingresos − gastos coincida con el saldo de cierre. Las filas que no encajan se marcan en lugar de pasarlas sin avisar.
> 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.No se conecta a cuentas bancarias y no es una API de banca abierta o de datos bancarios. Lee archivos de extractos que ya tengas. No se extrae nada y no se involucran credenciales bancarias.
Una cuenta de MainBook y las carpetas que contienen tus extractos. La conversión es la única herramienta que gasta créditos de página. De las otras cuatro, get_balance y list_conversions solo leen, get_conversion puede escribir un archivo de resultado, y output_folder cambia una preferencia local; ninguna modifica nada en tu cuenta de MainBook.
Inicia sesión una vez desde un terminal:
uvx mainbook-mcp auth loginEl comando abre MainBook en tu navegador, muestra el mismo código corto en ambos lugares y espera tu aprobación. Almacena la credencial en el llavero del sistema operativo cuando el paquete opcional keyring está instalado y funcionando. En caso contrario, usa ~/.config/mainbook/credentials.json con permisos privados de directorio y archivo. Usa mainbook-mcp auth status para comprobar la credencial activa en el lado del servidor sin gastar créditos de página. mainbook-mcp auth logout revoca primero esa clave almacenada, luego elimina la copia local; si no se puede alcanzar MainBook, indica claramente que la clave puede seguir activa. Iniciar sesión de nuevo revoca la clave almacenada anteriormente antes de guardar su reemplazo. La respuesta del token de dispositivo no incluye un correo electrónico ni un ID de cuenta, por lo que el estado dice que no se proporcionó la identidad de la cuenta en lugar de adivinarlo.
Luego añade una entrada a la configuración MCP de tu cliente. Este es el mismo bloque para Claude Desktop (Configuración → Desarrollador → Editar Config), Claude Code y Cursor; no se copia ninguna clave en él:
{
"mcpServers": {
"mainbook": {
"command": "uvx",
"args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
}
}
}Codex lee TOML, así que pon lo mismo en ~/.codex/config.toml:
[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]uvx viene con uv; instálalo una vez con brew install uv o curl -LsSf https://astral.sh/uv/install.sh | sh. Obtiene y ejecuta el paquete publicado, por lo que no hay nada que descargar manualmente ni nada que actualizar. Si prefieres no añadir uv, ejecuta pip install mainbook-mcp y usa "command": "mainbook-mcp" con los mismos argumentos; entonces lo actualizas tú mismo con pip install -U mainbook-mcp.
Los argumentos de carpeta son los únicos lugares donde el servidor puede leer un extracto o escribir un resultado; cualquier cosa fuera de ellos es rechazada. MAINBOOK_ALLOWED_DIRS establece la misma lista a través del entorno en su lugar, separada por os.pathsep de la plataforma (: en macOS/Linux, ; en Windows).
MAINBOOK_API_KEY tiene prioridad sobre cualquier inicio de sesión almacenado. Mantén el método manual para automatización donde no haya un navegador interactivo disponible. auth login advierte cuando esta variable anulará la credencial recién almacenada:
export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcpCrea y revoca claves manuales en https://mainbook.ai/developer. Nunca las subas al repositorio.
Claude Desktop también acepta un paquete de un solo archivo: Extensiones → Instalar Extensión… y selecciona mainbook.mcpb. Pide la clave API y las carpetas en un diálogo y gestiona su propio entorno de ejecución de Python, por lo que no necesita instalar nada primero. El bloque de configuración anterior hace el mismo trabajo y es más adecuado si ya mantienes otros servidores allí. Construye el paquete desde este directorio con:
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: crea un trabajo de crédito de página de pago, sube un PDF, inicia la conversión, espera hasta 30-900 segundos y devuelve el resultado revisado. El JSON permanece en línea. En modo stdio local, los bytes XLSX/CSV se escriben en disco y solo la ruta completa entra en el contexto del modelo.
get_conversion: comprueba un trabajo después de un tiempo de espera y devuelve JSON en línea o escribe XLSX/CSV en un destino local elegido.
list_conversions: devuelve una página de cursor de trabajos de la cuenta más next_cursor.
get_balance: devuelve el total, los créditos reservados y disponibles, todos medidos en páginas PDF.
output_folder: lee o cambia la carpeta de resultados local predeterminada.
El modo stdio local lista las cinco herramientas. El modo HTTP alojado lista exactamente las cuatro primeras; output_folder no se anuncia de forma remota porque el disco del servidor no pertenece al cliente.
No hay herramientas para comprar créditos, pagos, eliminar trabajos o cambiar datos de la cuenta.
Las herramientas que pueden crear una conversión, escribir un archivo de resultado local o cambiar la preferencia de salida están marcadas como no solo lectura. get_conversion es de solo lectura a través de HTTP alojado, donde no escribe ningún archivo, y no solo lectura a través de stdio local, donde puede escribir XLSX o CSV. Ninguna está marcada como destructiva porque los archivos de resultado existentes nunca se reemplazan.
Para clientes stdio locales (Claude Desktop, Claude Code, Cursor y Codex), los resultados XLSX y CSV se escriben en el primer destino disponible en este orden:
output_path proporcionado a convert_bank_statement o get_conversion (un nombre de archivo absoluto o una carpeta existente);
la carpeta recordada por output_folder;
junto al PDF de origen, con el mismo nombre base y la extensión del resultado.
get_conversion no puede inferir la carpeta del PDF original. Sin output_path o una carpeta recordada válida, devuelve un error claro en lugar de adivinar un destino. Cada respuesta de archivo exitosa contiene la ruta absoluta y explica qué regla la seleccionó. Los archivos existentes nunca se reemplazan: a statement.xlsx le sigue statement (2).xlsx, luego (3), y así sucesivamente.
Pídele al cliente que llame a output_folder sin argumentos para ver la configuración actual y cada carpeta permitida. Establécelo con un directorio absoluto permitido, o pasa next_to_source para restaurar el valor predeterminado. La preferencia es compartida por los clientes locales en la misma máquina en ~/.mainbook/preferences.json. Una carpeta guardada que falta o ya no está permitida se ignora, y esa alternativa se indica en el resultado.
El JSON permanece en línea. También se escribe en un archivo .json solo cuando se proporciona un output_path explícito. En modo HTTP remoto, las rutas locales y output_folder no están disponibles; XLSX/CSV sigue devolviendo una instrucción de descarga REST porque el disco del servidor no pertenece al cliente.
Python 3.11 o más reciente
Una cuenta de MainBook
Desde este directorio:
python3 -m venv .venv
.venv/bin/python -m pip install .Para preferir el llavero del sistema operativo sobre la alternativa JSON privada, instala el extra opcional en cada entorno que ejecute el comando de inicio de sesión o el servidor local:
.venv/bin/python -m pip install '.[keyring]'Usa una instalación normal, no pip install -e .. En este repositorio, la instalación editable escribe un archivo .pth que el intérprete no recoge, por lo que python -m mainbook_mcp falla con "No module named mainbook_mcp" mientras el paquete parece instalado. Un archivo idéntico con otro nombre se respeta, por lo que el contenido es correcto y la causa sigue sin explicación: una instalación normal lo evita por completo.
Si usas el método manual para automatización, mantén los valores mb_live_... en un entorno secreto o en la configuración del cliente. Nunca los subas al repositorio.
MainBook ejecuta este servidor por ti en https://mcp.mainbook.ai/mcp, por lo que un cliente que hable MCP remoto no necesita instalar nada. Apúntalo a esa URL y envía tu propia clave:
Authorization: Bearer mb_live_REPLACE_MELa clave se lee de cada solicitud, por lo que cada usuario de un cliente llega a su propia cuenta de MainBook y gasta sus propios créditos de página. initialize y tools/list responden sin clave; cada llamada a herramienta requiere una. Las rutas de archivo locales y output_folder no existen a través de HTTP: pasa file_url en lugar de file_path, y los resultados XLSX o CSV vuelven como una instrucción de descarga REST, porque el disco del servidor no es tuyo.
También puedes ejecutar tú mismo el mismo modo remoto. Es HTTP transmisible sin estado con respuestas JSON:
mainbook-mcp --transport http --host 127.0.0.1 --port 8000El endpoint MCP es entonces http://127.0.0.1:8000/mcp. Cada cliente debe enviar su propio encabezado:
Authorization: Bearer mb_live_REPLACE_MEEl encabezado se lee de cada solicitud de llamada a herramienta y nunca se almacena en el estado global. El modo HTTP alojado no inspecciona MAINBOOK_API_KEY, el llavero del sistema operativo ni el archivo de credenciales local. Para el modo remoto de 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"Reemplaza la URL con tu propio host si implementas esto tú mismo; una implementación autohospedada aún necesita terminación HTTPS normal y controles de acceso.
MAINBOOK_API_KEY: opcional en stdio y tiene prioridad sobre un inicio de sesión almacenado; ignorada en modo HTTP, donde cada llamada a herramienta debe llevar su propio encabezado Bearer.
MAINBOOK_API_BASE_URL: host REST, predeterminado https://api.mainbook.ai. El servidor añade /api/v1/developer.
MAINBOOK_ALLOWED_DIRS: carpetas locales permitidas para lecturas de origen y escrituras de resultado, separadas por os.pathsep de la plataforma (: en macOS/Linux y ; en Windows). Los argumentos de directorio posicionales tienen prioridad. Si no se proporciona ninguno, los valores predeterminados son ~/Downloads, ~/Desktop y ~/Documents.
MAINBOOK_MCP_TRANSPORT: stdio (predeterminado) o http.
MAINBOOK_MCP_HOST: host de enlace HTTP, predeterminado 127.0.0.1.
MAINBOOK_MCP_PORT: puerto de enlace HTTP, predeterminado 8000.
file_path y file_url son mutuamente excluyentes. file_path solo se acepta a través de stdio local; el modo HTTP lo rechaza antes de que se ejecute el cargador del sistema de archivos y requiere file_url.
El acceso local a file_path y la escritura de archivos de resultado usan las mismas carpetas configuradas. Los directorios CLI posicionales tienen prioridad sobre MAINBOOK_ALLOWED_DIRS; la variable de entorno tiene prioridad sobre los valores predeterminados ~/Downloads, ~/Desktop y ~/Documents. Cada raíz se expande y resuelve, las raíces faltantes se ignoran y las raíces activas se imprimen en stderr cuando el servidor se inicia. Si no quedan raíces, el acceso local falla de forma segura mientras el servidor continúa ejecutándose.
Los directorios padre de salida se resuelven antes de escribir y se verifican por identidad de directorio, por lo que un enlace simbólico no puede redirigir un resultado fuera de las carpetas permitidas. La creación de resultados es exclusiva y segura frente a colisiones; los archivos existentes no se sobrescriben.
~/.mainbook/preferences.json se reemplaza de forma atómica. El directorio .mainbook tiene modo 0700 y el archivo de preferencias tiene modo 0600; las preferencias mal formadas o ilegibles se ignoran de forma segura.
Las credenciales de terminal usan el llavero del sistema cuando el paquete opcional es utilizable. La alternativa ~/.config/mainbook/credentials.json se reemplaza de forma atómica dentro de un directorio con modo 0700 y tiene modo 0600; sus entradas de nivel superior están indexadas por la URL base de la API.
Las rutas locales se expanden y resuelven estrictamente antes de la verificación de la lista de permitidos, por lo que .. y los enlaces simbólicos no pueden hacer que un destino externo parezca estar dentro de una carpeta permitida. La ruta resuelta debe estar estrictamente por debajo de una raíz, no ser igual a la raíz misma.
El archivo local se abre una vez. El servidor usa fstat en ese descriptor para exigir un archivo regular y aplicar el límite de 50 MiB, luego realiza la lectura acotada a través del mismo descriptor. Esto cierra la ventana de reemplazo entre verificación y lectura, pero no elimina por completo la condición de carrera entre resolver la ruta y abrirla; la ruta aún puede ser reemplazada durante ese intervalo.
Un archivo local debe contener %PDF- dentro de sus primeros 1024 bytes antes de que se invoque pypdf. Las extensiones de nombre de archivo no se usan para decidir si un archivo es un PDF.
Los archivos remotos deben usar HTTPS. No se siguen redirecciones.
Las respuestas DNS se rechazan si alguna dirección es privada, de bucle local, de enlace local, de metadatos, reservada o no pública, tanto para IPv4 como para IPv6.
Las descargas de URL se conectan a una IP numérica ya validada mientras se conserva el nombre de host original para la verificación del certificado TLS y la cabecera HTTP Host, cerrando las condiciones de carrera de reenlace DNS.
Content-Length y el recuento real de bytes transmitidos están limitados de forma independiente a 50 MiB.
Los PDF se analizan localmente con pypdf y están limitados a 500 páginas.
Las cabeceras de carga prefirmadas de MainBook se reenvían sin cambios; la clave Bearer de MainBook nunca se envía al almacenamiento.
.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 .Todas las pruebas REST usan mocks o un stub local. Ninguna prueba requiere o acepta una clave real de la API de MainBook.
Convert one PDF bank statement through the complete MainBook workflow: create a job, upload, start, poll, and return structured data. This creates a job and spends page credits; it is not read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | No | Public HTTPS URL of a PDF for remote mode. Redirects and non-public network addresses are rejected. Exactly one source is required. | |
| file_path | No | Path to a PDF on the MCP server machine. This field is only available over stdio and is rejected in HTTP mode; remote clients must use file_url. The path must be inside the allowed folders, which default to Downloads, Desktop, and Documents. Exactly one of file_path and file_url is required. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. The file extension is corrected to match result_type. | |
| result_type | No | JSON is returned inline. Over stdio, XLSX or CSV is written to an allowed local folder and the full path is returned. HTTP mode returns safe download instructions. Binary bytes never enter model context. | json |
| idempotency_key | No | Optional value forwarded verbatim in the Idempotency-Key REST header. | |
| timeout_seconds | No | Internal polling budget from 30 to 900 seconds. Timeout leaves the job running and returns its job_id for get_conversion. The default stays under the 60-second request timeout most MCP clients enforce; a client that gives up first discards the job_id and the conversion looks lost. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description adds value by explicitly stating the workflow creates a job, spends page credits, and is not read-only. It does not contradict any annotation and provides useful behavioral context beyond the boolean hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that are front-loaded and highly efficient. The first sentence immediately conveys the action and workflow; the second adds critical behavioral context. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multi-step workflow, 6 parameters, output schema exists), the description covers the high-level workflow and side effects. It could briefly mention that results can be inline JSON or file-based (from result_type), but the parameter descriptions and output schema fill that gap. Overall complete for an agent to understand purpose and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The overall description does not add parameter-specific meaning, but the individual parameter descriptions are already thorough. The tool description appropriately focuses on the overall workflow rather than repeating schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Convert one PDF bank statement' with a specific verb and resource, and outlines the complete workflow (create, upload, start, poll, return). It explicitly distinguishes itself from read-only siblings (get_balance, get_conversion) by stating 'it is not read-only' and 'spends page credits'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the primary conversion tool and notes it is not read-only, giving clear context for use. However, it does not explicitly state when not to use it or reference alternatives like list_conversions or get_conversion for post-processing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return total, reserved, and available MainBook credits. Every value is measured in PDF pages.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| units | No | |
| balance | Yes | |
| reserved | Yes | |
| available | Yes | |
| explanation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a read-only, externally mutable resource. The description adds clarity by specifying the exact credits (total, reserved, available) and confirming the unit (PDF pages). No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, dense sentences with no wasted words. The first sentence states what the tool returns, the second clarifies the measurement unit. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description fully covers the purpose, items returned, and units. The output schema presumably details the structure, so no additional return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and there are no parameters to document. The description provides the meaning of the return values (total, reserved, available) which is helpful, but since there are no params, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and identifies the resource ('MainBook credits') and three precise items (total, reserved, available). It distinguishes itself from siblings like 'convert_bank_statement' or 'list_conversions' by being clearly a balance/account query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an agent needs to check credit balances before performing PDF-related operations. It does not explicitly state when not to use it or name alternatives, but with 0 params and a dedicated name, its niche is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current state of one MainBook conversion. When successful, return JSON inline or save XLSX/CSV locally over stdio. HTTP mode returns safe download instructions. Use this after convert_bank_statement times out.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Conversion job UUID returned by MainBook. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. | |
| result_type | No | Result representation to retrieve after the job succeeds. | json |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by explaining output modes (inline JSON, local file save over stdio, HTTP download instructions). However, it does not disclose potential side effects or whether repeated polling affects the conversion state. The annotations (readOnlyHint: false, openWorldHint: true) signal uncertainty, but the description does not fully address behavioral traits like idempotency or changes to the conversion state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy. The first sentence states the purpose, the next two explain behavior in different modes, and the last gives a usage hint. Every sentence adds value, and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (polling tool with output schema and sibling tools), the description covers output modes and when to use it, but it lacks guidance on polling frequency, lifecycle (one-time or repeatable), and failure handling. The existence of an output schema reduces the burden for return values, but more context on the polling workflow would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description in the schema (job_id, output_path, result_type). The tool description does not add any additional parameter semantics beyond what the schema already provides. With full coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the current state of one MainBook conversion, using a specific verb ('Get') and resource ('one MainBook conversion'). It effectively distinguishes from siblings: convert_bank_statement is the preceding step, list_conversions lists all conversions, and get_balance is unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Use this after convert_bank_statement times out.' This tells the agent exactly when to invoke this tool. While it does not explicitly state when not to use it or list alternatives beyond the sibling set, the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List one cursor page of conversion jobs visible to the MainBook account. Pass the returned next_cursor to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Jobs on this page, from 1 to 100. | |
| cursor | No | Opaque next_cursor from the previous page. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| units | No | |
| conversions | Yes | |
| next_cursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context beyond that: it clarifies scope ('visible to the MainBook account') and the cursor-based pagination mechanism. This extra detail is valuable for an agent deciding how to interact with the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The first sentence states the core purpose and scope; the second gives the key usage instruction for pagination. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (pagination list with two parameters), full schema coverage, presence of an output schema, and comprehensive annotations, the description is complete. It does not need to explain return values (output schema covers that) and provides all necessary usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both limit and cursor. The description mentions 'cursor page' and 'next_cursor,' reinforcing the cursor parameter's role but adding no new semantic detail beyond what the schema already provides. Baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List one cursor page of conversion jobs visible to the MainBook account.' It uses a specific verb ('list'), resource ('conversion jobs'), and includes scope constraints ('one cursor page', 'MainBook account'), effectively distinguishing it from sibling tools like get_conversion (single item) and convert_bank_statement (action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the agent to 'Pass the returned next_cursor to continue,' providing clear pagination usage. It implies the tool is for listing pages of conversions but does not explicitly state when not to use it or compare to alternatives. However, given distinct siblings, the guidance is effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or change the default local result folder. Call with no path to inspect the current setting and allowed folders. Pass an allowed absolute folder, or 'next_to_source' to restore the default behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Allowed absolute folder to remember, or 'next_to_source' to reset. Omit to read without changing anything. |
| Name | Required | Description |
|---|---|---|
| message | Yes | |
| output_folder | Yes | |
| allowed_folders | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. Description adds context about inspecting vs changing, 'allowed folders' restriction, and special 'next_to_source' value. This enriches the behavioral model beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, output schema present, and clear annotations, the description covers all needed context: read vs write, allowed folder restriction, reset behavior. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description aligns perfectly. Both clarify that omitting path reads, providing a path changes it, and 'next_to_source' is a special reset value. No gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read or change the default local result folder' with specific verbs and resource. It distinguishes from siblings which deal with bank statements and balances, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Call with no path to inspect the current setting' for read, 'Pass an allowed absolute folder, or 'next_to_source' to restore' for write. No sibling overlap requires exclusion clauses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.1convert_bank_statementget_balanceget_conversionlist_conversionsoutput_folderEach tool has a clearly distinct purpose: convert_bank_statement handles submission, get_balance checks credits, list_conversions enumerates jobs, get_conversion retrieves state/results, and output_folder manages local storage. No overlap in functionality.
Tool names mostly follow a verb_noun pattern with consistent snake_case. 'convert_bank_statement', 'get_balance', 'list_conversions', and 'get_conversion' are clear. 'output_folder' is slightly less standard as a verb but still readable and consistent in style.
Five tools cover the core workflows for a PDF statement converter: submission, credit monitoring, job listing, status retrieval, and output configuration. This is well-scoped without unnecessary extras or missing essentials.
The set provides a complete lifecycle for converting statements: submit, monitor progress, retrieve results, manage output folder, and check credits. Minor gaps like cancel/delete are absent but not critical given the workflow's design.
Convert PDF bank statements into structured transactions, accounts, and balances.
Turn bank statement PDFs, CSVs, XLSX and OFX into categorised transactions plus a summary.
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.
PDF tools + invoice extraction, bank statement parsing, GST reconciliation & GSTIN validation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/human-beyond/mainbook-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
