하나의 작업에 특화된 금융 MCP 서버입니다: 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.은행 계좌에 연결되지 않으며, 오픈 뱅킹 또는 은행 데이터 API가 아닙니다. 이미 보유한 명세서 파일을 읽습니다. 스크래핑이 없으며 은행 인증 정보가 필요하지 않습니다.
MainBook 계정과 명세서가 있는 폴더입니다. 변환만이 페이지 크레딧을 소모하는 유일한 도구입니다. 나머지 네 가지 중 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 구성에 항목 하나를 추가합니다. 이는 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-mcphttps://mainbook.ai/developer에서 수동 키를 생성 및 취소하세요. 절대 커밋하지 마세요.
Claude Desktop은 단일 파일 번들도 허용합니다: **확장 → 확장 설치…**에서 mainbook.mcpb를 선택하세요. 대화상자에서 API 키와 폴더를 요청하며 자체 Python 런타임을 관리하므로 먼저 설치할 필요가 없습니다. 위의 구성 블록도 동일한 작업을 수행하며, 이미 다른 서버를 유지 관리하는 경우 더 적합합니다. 이 디렉토리에서 번들을 빌드하세요:
npx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json
npx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpbRelated MCP server: document-to-json-mcp
convert_bank_statement: 유료 페이지 크레딧 작업을 생성하고, 하나의 PDF를 업로드하며, 변환을 시작하고, 최대 30-900초 동안 폴링한 후 검토된 결과를 반환합니다. JSON은 인라인으로 유지됩니다. 로컬 stdio 모드에서는 XLSX/CSV 바이트가 디스크에 기록되고 전체 경로만 모델 컨텍스트에 들어갑니다.
get_conversion: 타임아웃 후 작업을 확인하고 JSON을 인라인으로 반환하거나 XLSX/CSV를 선택한 로컬 대상에 씁니다.
list_conversions: 계정 작업의 한 커서 페이지와 next_cursor를 반환합니다.
get_balance: 총 크레딧, 예약된 크레딧, 사용 가능한 크레딧을 모두 PDF 페이지 단위로 반환합니다.
output_folder: 기본 로컬 결과 폴더를 읽거나 변경합니다.
로컬 stdio 모드는 다섯 가지 도구를 모두 나열합니다. 호스팅 HTTP 모드는 처음 네 가지 도구만 정확히 나열합니다. output_folder는 서버의 디스크가 클라이언트 소유가 아니므로 원격으로 광고되지 않습니다.
크레딧 구매, 결제, 작업 삭제 또는 계정 데이터 변경을 위한 도구는 없습니다. 변환을 생성하거나, 로컬 결과 파일을 쓰거나, 출력 환경설정을 변경할 수 있는 도구는 읽기 전용이 아닌 것으로 표시됩니다. get_conversion은 호스팅 HTTP를 통해서는 읽기 전용(파일을 쓰지 않음)이며, 로컬 stdio를 통해서는 읽기 전용이 아닙니다(XLSX 또는 CSV를 쓸 수 있음). 기존 결과 파일을 절대 대체하지 않으므로 어떤 것도 파괴적이라고 표시되지 않습니다.
로컬 stdio 클라이언트(Claude Desktop, Claude Code, Cursor 및 Codex)의 경우 XLSX 및 CSV 결과는 다음 순서로 사용 가능한 첫 번째 대상에 기록됩니다:
convert_bank_statement 또는 get_conversion에 제공된 output_path(절대 파일 이름 또는 기존 폴더);
output_folder가 기억하는 폴더;
원본 PDF 옆에 동일한 기본 이름과 결과 확장자로 저장.
get_conversion은 원본 PDF 폴더를 추론할 수 없습니다. output_path 또는 유효한 기억된 폴더가 없으면 대상을 추측하는 대신 명확한 오류를 반환합니다. 모든 성공적인 파일 응답에는 절대 경로가 포함되며 어떤 규칙이 선택되었는지 설명합니다. 기존 파일은 절대 대체되지 않습니다: statement.xlsx 다음에는 statement (2).xlsx, 그 다음에는 (3) 등이 생성됩니다.
클라이언트에게 인수 없이 output_folder를 호출하도록 요청하여 현재 설정과 허용된 모든 폴더를 확인하세요. 허용된 절대 디렉토리로 설정하거나, next_to_source를 전달하여 기본값으로 복원하세요. 이 환경설정은 동일한 머신의 로컬 클라이언트 간에 ~/.mainbook/preferences.json에서 공유됩니다. 저장된 폴더가 없거나 더 이상 허용되지 않으면 무시되며, 해당 대체 방법이 결과에 명시됩니다.
JSON은 인라인으로 유지됩니다. 명시적인 output_path가 제공된 경우에만 .json 파일에도 기록됩니다. 원격 HTTP 모드에서는 로컬 경로와 output_folder를 사용할 수 없습니다. XLSX/CSV는 서버 디스크가 클라이언트 소유가 아니므로 계속 REST 다운로드 지침을 반환합니다.
Python 3.11 이상
MainBook 계정
이 디렉토리에서:
python3 -m venv .venv
.venv/bin/python -m pip install .비공개 JSON 대체 방법보다 OS 키링을 선호하려면 로그인 명령어나 로컬 서버를 실행하는 모든 환경에서 선택적 추가 패키지를 설치하세요:
.venv/bin/python -m pip install '.[keyring]'일반 설치를 사용하고 pip install -e .는 사용하지 마세요. 이 체크아웃에서 편집 가능한 설치는 인터프리터가 인식하지 못하는 .pth 파일을 작성하므로, 패키지가 설치된 것처럼 보이지만 python -m mainbook_mcp는 "No module named mainbook_mcp" 오류와 함께 실패합니다. 다른 이름의 동일한 파일은 인식되므로 내용은 괜찮지만 원인은 여전히 설명되지 않습니다 — 일반 설치는 이 문제를 완전히 우회합니다.
자동화를 위해 수동 방식을 사용하는 경우 mb_live_... 값을 비밀 환경 변수나 클라이언트 구성에 보관하세요. 절대 커밋하지 마세요.
MainBook은 https://mcp.mainbook.ai/mcp에서 이 서버를 실행하므로, 원격 MCP를 지원하는 클라이언트는 아무것도 설치할 필요가 없습니다. 해당 URL을 가리키고 자신의 키를 보내세요:
Authorization: Bearer mb_live_REPLACE_ME키는 각 요청에서 읽히므로, 클라이언트의 모든 사용자는 자신의 MainBook 계정에 접근하고 자신의 페이지 크레딧을 소모합니다. initialize와 tools/list는 키 없이 응답합니다. 모든 도구 호출에는 키가 필요합니다. 로컬 파일 경로와 output_folder는 HTTP를 통해 존재하지 않습니다. file_path 대신 file_url을 전달하고, XLSX 또는 CSV 결과는 REST 다운로드 지침으로 반환됩니다. 서버의 디스크는 사용자의 것이 아니기 때문입니다.
동일한 원격 모드를 직접 실행할 수도 있습니다. JSON 응답이 있는 상태 비저장 스트리밍 가능 HTTP입니다:
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로 키 지정됩니다.
로컬 경로는 허용 목록 확인 전에 확장되고 엄격하게 확인되므로, ..와 심볼릭 링크가 외부 대상을 허용된 폴더 내부에 있는 것처럼 보이게 할 수 없습니다. 확인된 경로는 루트 자체가 아니라 루트보다 엄격하게 하위에 있어야 합니다.
로컬 파일은 한 번 열립니다. 서버는 해당 설명자에 fstat을 사용하여 일반 파일을 요구하고 50MiB 제한을 적용한 후, 동일한 설명자를 통해 제한된 읽기를 수행합니다. 이는 확인-대-읽기 교체 창을 닫지만, 경로 확인과 열기 사이의 경쟁을 완전히 제거하지는 않습니다. 해당 간격 동안 경로가 여전히 교체될 수 있습니다.
로컬 파일은 pypdf가 호출되기 전에 처음 1024바이트 내에 %PDF-를 포함해야 합니다. 파일 이름 확장자는 파일이 PDF인지 결정하는 데 사용되지 않습니다.
원격 파일은 HTTPS를 사용해야 합니다. 리디렉션은 따르지 않습니다.
IPv4 및 IPv6에서, DNS 응답은 모든 주소가 개인, 루프백, 링크-로컬, 메타데이터, 예약 또는 기타 비공개인 경우 거부됩니다.
URL 다운로드는 이미 확인된 숫자 IP에 연결하면서 TLS 인증서 확인 및 HTTP Host 헤더를 위해 원래 호스트 이름을 유지하여 DNS-리바인딩 경쟁을 차단합니다.
Content-Length와 실제 스트리밍된 바이트 수는 각각 독립적으로 50MiB로 제한됩니다.
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
