# AILANG Parse > Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells. - name: io.github.sunholo-data/parse - version: 0.13.1 - connection class: R0 (autonomous) - trust: 94/100 - quality: 81/100 (good) - owner: not claimed - descriptor: https://api.protogrid.dev/v1/servers/io.github.sunholo-data%2Fparse - tools: https://api.protogrid.dev/v1/servers/io.github.sunholo-data%2Fparse/tools **An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe. ## Connection (mcpServers) ```json { "mcpServers": { "parse": { "type": "http", "url": "https://docparse.ailang.sunholo.com/mcp/" } } } ``` ## Trust - hygiene: 100 - liveness: 100 - freshness: 85 - provenance: 90 - drivers: +repository +namespace-matches-repo +website +reachable +uptime-99% ~updated-48d-ago - Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed. ## Quality 81/100 (good) ### protocol: 88 (weight 25) - pass `protocol.modern`: supports 2026-07-28 (server/discover) - pass `protocol.stateless`: answers without a session - pass `protocol.transport`: streamable HTTP - warn `protocol.list_ttl`: tools/list declares ttlMs 0, so clients re-fetch it on every use ### authorization: n/a (weight 15) - n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth - n/a `auth.secret_in_url`: no templated URL ### tool hygiene: 93 (weight 30) - pass `tools.descriptions`: every tool has a description - warn `tools.description_length`: 3 tools have descriptions over 1,024 characters, which crowds the context - pass `tools.schemas`: every tool has an object input schema - pass `tools.annotations`: 12 of 12 tools declare readOnlyHint or destructiveHint - pass `tools.directory_hints`: every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint - pass `tools.token_cost`: about 3,166 tokens to load every tool - pass `tools.api_dump`: tools are not a one-to-one API dump ### stability: 25 (weight 15) - warn `stability.changes`: 31 tool changes in 30 days - fail `stability.rug_pull`: 6 tools kept their name but changed most of their description in 30 days; review before trusting them ### dependencies: 100 (weight 15) - pass `deps.known_vulns`: no known advisory in 7 resolved packages - n/a `deps.mcp_sdk_version`: the official MCP SDK is not in the dependency graph - pass `deps.resolvable`: @ailang/parse@0.13.1, ailang-parse@0.13.1 resolved: 7 packages - tools: 12, about 3,166 tokens to load them all - tool set hash: cde80d54db4bf52f2d66db794dbb195c - tools last changed: 2026-10-08T14:02:03.464Z - badge: [![protogrid quality](https://protogrid.dev/badge/io.github.sunholo-data/parse.svg)](https://protogrid.dev/servers/io.github.sunholo-data/parse) - Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed. ### Tool changes - 2026-10-08 `uploadDocument` changed (description) - before: Let the user pick a file to parse: shows the AILANG Parse card with a Choose file button. The card uploads the file and parses it into blocks automatically, then hands you the result. Use it when the user wants to pick a file, or when createUpload's curl fails with a network error. For a file already in your sandbox or workspace, use createUpload + curl instead. Never parse the file yourself. - after: Let the user pick a file to parse: shows the AILANG Parse card with a Choose file button. The card uploads the file and tries to summarise it for you; either way you get its fileRef. Then call mcpParse with that fileRef for the content (the same user can reuse it for 30 minutes; a large document comes in parts). Use this when the user wants to pick a file, or when createUpload's curl fails with a network error. For a file already in your sandbox or workspace, use createUpload + curl instead. Never parse the file yourself. - 2026-10-08 `mcpParse` changed (description, inputSchema) - before: Parse a document into structured blocks, Markdown, HTML or A2UI. Give the document ONE way: fileRef: an uploaded file (mcp-file://docparse/file_...). Each works once. file: in ChatGPT, the file the user attached (ChatGPT fills it in). filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". content + filename: short text only (Markdown, HTML, CSV); the filename's extension picks the parser. outputFormat: blocks (default), markdown, html, a2ui. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then call this tool with the fileRef the upload prints. curl fails with a network error, or the user wants to pick a file: call uploadDocument; the user chooses it in the AILANG Parse card, which uploads and parses it automatically. a public https:// link: filepath. Short text: content. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - after: Parse a document into structured blocks, Markdown, HTML or A2UI, or a short summary of it. Give the document ONE way: fileRef: an uploaded file (mcp-file://docparse/file_...). The same user can use it again for 30 minutes after the first use (more parts, another format), then it is deleted. file: in ChatGPT, the file the user attached (ChatGPT fills it in). filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". content + filename: short text only (Markdown, HTML, CSV); the filename's extension picks the parser. outputFormat: blocks (default), markdown, html, a2ui, or summary (counts, the first 50 headings, warnings: a few KB). Look with summary first when a document may be large. Large documents come in parts: when the result has page.nextCursor, call mcpParse again with the same fileRef/filepath and cursor= for the next part; read every part before answering about the whole document. maxChars sets the part size as a string of digits (default "80000", "2000".."120000"). Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then call this tool with the fileRef the upload prints. curl fails with a network error, or the user wants to pick a file: call uploadDocument; the user chooses it in the AILANG Parse card, which uploads it and gives you its fileRef. a public https:// link: filepath. Short text: content. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - 2026-10-07 `uploadViaHost` added - Receive a file from the AILANG Parse upload widget, relayed by the host as base64. Only the widget calls this; ticket is the upload token it holds. - 2026-10-07 `uploadDocument` added - Let the user pick a file to parse: shows the AILANG Parse card with a Choose file button. The card uploads the file and parses it into blocks automatically, then hands you the result. Use it when the user wants to pick a file, or when createUpload's curl fails with a network error. For a file already in your sandbox or workspace, use createUpload + curl instead. Never parse the file yourself. - 2026-10-07 `mcpParse` changed (description, inputSchema) **meaning changed** - before: Parse a document into structured blocks, Markdown, HTML or A2UI. Give the document ONE way: content + filename: the document itself. Text formats (Markdown, HTML, CSV) as plain text; binary files (DOCX, PDF, PPTX, XLSX, ODT, EPUB, ...) base64-encoded with contentEncoding="base64". The filename's extension picks the parser, e.g. "report.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". outputFormat: blocks (default), markdown, html, a2ui. - after: Parse a document into structured blocks, Markdown, HTML or A2UI. Give the document ONE way: fileRef: an uploaded file (mcp-file://docparse/file_...). Each works once. file: in ChatGPT, the file the user attached (ChatGPT fills it in). filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". content + filename: short text only (Markdown, HTML, CSV); the filename's extension picks the parser. outputFormat: blocks (default), markdown, html, a2ui. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then call this tool with the fileRef the upload prints. curl fails with a network error, or the user wants to pick a file: call uploadDocument; the user chooses it in the AILANG Parse card, which uploads and parses it automatically. a public https:// link: filepath. Short text: content. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - 2026-10-07 `mcpConvert` changed (description, inputSchema) - before: Create a document in another format: docx, pptx, xlsx, odt, odp, ods, html, md or qmd. To write a new document, write Markdown and send it as content with filename "notes.md" (headings become slides in pptx). To convert an existing document, give it ONE way: content + filename: the document itself; binary files base64-encoded with contentEncoding="base64", text as plain text. input: an https:// URL of a publicly reachable document, or a sample id from mcpFormats. The result carries download_url, a link to the generated file valid for one hour: give it to the user. It also carries the file as base64 in content (encoding "base64"; text formats come back as utf8). - after: Create a document in another format: docx, pptx, xlsx, odt, odp, ods, html, md or qmd. To write a new document, write Markdown and send it as content with filename "notes.md" (headings become slides in pptx). To convert an existing document, give it ONE way: fileRef: a file the user uploaded (mcp-file://docparse/file_...). file: in ChatGPT, the file the user attached (ChatGPT fills it in). content + filename: the document itself; binary files base64-encoded with contentEncoding="base64", text as plain text. input: an https:// URL of a publicly reachable document, or a sample id from mcpFormats. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then pass the fileRef here. curl fails with a network error, or the user wants to pick a file: call uploadDocument (the user chooses it in the AILANG Parse card). The card parses the file; it does not convert or edit it. a public https:// link; short text as content. In ChatGPT, file. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. The result carries download_url, a link to the generated file valid for one hour: give it to the user. It also carries the file as base64 in content (encoding "base64"; text formats come back as utf8). - 2026-10-07 `editDocument` changed (description, inputSchema) - before: Edit a document: parse it, apply a JSON array of edit deltas, and return the modified blocks (same shape as mcpParse with outputFormat "blocks"). deltas "" or "[]" returns the document unchanged. Office formats only: docx, pptx, xlsx, odt, odp, ods. Give the document ONE way: content + filename: the file base64-encoded, contentEncoding="base64", e.g. filename "contract.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". To get a file back, pass the edited blocks' Markdown to mcpConvert. - after: Edit a document: parse it, apply a JSON array of edit deltas, and return the modified blocks (same shape as mcpParse with outputFormat "blocks"). deltas "" or "[]" returns the document unchanged. Office formats only: docx, pptx, xlsx, odt, odp, ods. Give the document ONE way: fileRef: a file the user uploaded (mcp-file://docparse/file_...). file: in ChatGPT, the file the user attached (ChatGPT fills it in). content + filename: the file base64-encoded, contentEncoding="base64", e.g. filename "contract.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". To get a file back, pass the edited blocks' Markdown to mcpConvert. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then pass the fileRef here. curl fails with a network error, or the user wants to pick a file: call uploadDocument (the user chooses it in the AILANG Parse card). The card parses the file; it does not convert or edit it. a public https:// link; short text as content. In ChatGPT, file. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - 2026-10-07 `createUpload` added - Get one-time upload links for files in your sandbox or workspace, when you can run shell commands with network access (Claude Code, Codex, a code sandbox). One token PER FILE: a token uploads exactly one file. For several files set count (1..20) to get that many descriptors in one call. Each descriptor has a curl line: run it where the file is (replace ); it prints a receipt with a fileRef. Then call mcpParse, mcpConvert or editDocument with that fileRef. Tokens work once, for 10 minutes. If curl fails with a network error, or the user wants to pick a file, call uploadDocument instead, or ask for an https:// link. Never parse the file yourself. - 2026-10-06 `getUploadUrl` removed - Request a pre-authenticated GCS upload URL for direct file upload. Business tier only. The returned URL allows the client to PUT file content directly to GCS, bypassing the 32MB Cloud Run request limit. After upload, pass the gcs_ref to POST /api/v1/parse. - 2026-10-06 `mcpParse` changed (description, inputSchema) **meaning changed** - before: Parse a document. Accepts a file path or sample_id (e.g. "sample_docx_formatting"). The hosted server requires a valid dp_ API key — get one via mcpAuth. apiKey may be omitted when the request sends Authorization: Bearer or X-API-Key: . Output formats: blocks (default), markdown, html, a2ui. requestId is reserved for future replay support. - after: Parse a document into structured blocks, Markdown, HTML or A2UI. Give the document ONE way: content + filename: the document itself. Text formats (Markdown, HTML, CSV) as plain text; binary files (DOCX, PDF, PPTX, XLSX, ODT, EPUB, ...) base64-encoded with contentEncoding="base64". The filename's extension picks the parser, e.g. "report.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". outputFormat: blocks (default), markdown, html, a2ui. Full history: https://api.protogrid.dev/v1/servers/io.github.sunholo-data%2Fparse/changes ## Dependencies - npm @ailang/parse@0.13.1: resolved, 0 dependencies - pypi ailang-parse@0.13.1: resolved, 5 dependencies Dependency graphs from deps.dev; advisories from OSV.dev, including the GitHub Advisory Database and the PyPI Advisory Database; all CC BY 4.0. ## Remotes - https://docparse.ailang.sunholo.com/mcp/ (streamable-http, auth none, reachable true, uptime30d 0.9913793) ## Packages - npm @ailang/parse@0.13.1 secrets: DOCPARSE_API_KEY - pypi ailang-parse@0.13.1 secrets: DOCPARSE_API_KEY ## Tools (12) - `createUpload`: Get one-time upload links for files in your sandbox or workspace, when you can run shell commands with network access (Claude Code, Codex, a code sandbox). One token PER FILE: a token uploads exactly one file. For several files set count (1..20) to get that many descriptors in one call. Each descriptor has a curl line: run it where the file is (replace ); it prints a receipt with a fileRef. Then call mcpParse, mcpConvert or editDocument with that fileRef. Tokens work once, for 10 minutes. If curl fails with a network error, or the user wants to pick a file, call uploadDocument instead, or ask for an https:// link. Never parse the file yourself. - `editDocument`: Edit a document: parse it, apply a JSON array of edit deltas, and return the modified blocks (same shape as mcpParse with outputFormat "blocks"). deltas "" or "[]" returns the document unchanged. Office formats only: docx, pptx, xlsx, odt, odp, ods. Give the document ONE way: fileRef: a file the user uploaded (mcp-file://docparse/file_...). file: in ChatGPT, the file the user attached (ChatGPT fills it in). content + filename: the file base64-encoded, contentEncoding="base64", e.g. filename "contract.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". To get a file back, pass the edited blocks' Markdown to mcpConvert. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then pass the fileRef here. curl fails with a network error, or the user wants to pick a file: call uploadDocument (the user chooses it in the AILANG Parse card). The card parses the file; it does not convert or edit it. a public https:// link; short text as content. In ChatGPT, file. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - `mcpAccount`: Your AILANG Parse account: plan, monthly usage and limits, your keys, and whether request history is kept. Actions: "status" (default) → plan, usage this month and remaining allowance "keys" → your keys with per-key usage ("usage" is an alias) "history" → whether request history (parsed output kept for replay) is on for your account "history_on" / "history_off" → change it for the account and all its keys - `mcpAuth`: Start device authorization to get an API key. Returns device_code, user_code, and verification URL. The agent should display the verification URL to the user, who signs in and approves the code. Then call mcpAuthPoll with the device_code. MCP wrappers don't have HTTP request headers, so provenance is empty here. - `mcpAuthPoll`: Poll for device authorization completion. Returns "pending" (keep polling every 5s), "approved" (with api_key and tier), or "expired" (start over with mcpAuth). - `mcpConvert`: Create a document in another format: docx, pptx, xlsx, odt, odp, ods, html, md or qmd. To write a new document, write Markdown and send it as content with filename "notes.md" (headings become slides in pptx). To convert an existing document, give it ONE way: fileRef: a file the user uploaded (mcp-file://docparse/file_...). file: in ChatGPT, the file the user attached (ChatGPT fills it in). content + filename: the document itself; binary files base64-encoded with contentEncoding="base64", text as plain text. input: an https:// URL of a publicly reachable document, or a sample id from mcpFormats. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then pass the fileRef here. curl fails with a network error, or the user wants to pick a file: call uploadDocument (the user chooses it in the AILANG Parse card). The card parses the file; it does not convert or edit it. a public https:// link; short text as content. In ChatGPT, file. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. The result carries download_url, a link to the generated file valid for one hour: give it to the user. It also carries the file as base64 in content (encoding "base64"; text formats come back as utf8). - `mcpEstimate`: Estimate cost and latency for parsing a document. Accepts a file path or sample_id. No auth required. - `mcpFormats`: What AILANG Parse can read and write, how to send it a document, and the sample documents you can try without one. No sign-in needed. - `mcpParse`: Parse a document into structured blocks, Markdown, HTML or A2UI, or a short summary of it. Give the document ONE way: fileRef: an uploaded file (mcp-file://docparse/file_...). The same user can use it again for 30 minutes after the first use (more parts, another format), then it is deleted. file: in ChatGPT, the file the user attached (ChatGPT fills it in). filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". content + filename: short text only (Markdown, HTML, CSV); the filename's extension picks the parser. outputFormat: blocks (default), markdown, html, a2ui, or summary (counts, the first 50 headings, warnings: a few KB). Look with summary first when a document may be large. Large documents come in parts: when the result has page.nextCursor, call mcpParse again with the same fileRef/filepath and cursor= for the next part; read every part before answering about the whole document. maxChars sets the part size as a string of digits (default "80000", "2000".."120000"). Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then call this tool with the fileRef the upload prints. curl fails with a network error, or the user wants to pick a file: call uploadDocument; the user chooses it in the AILANG Parse card, which uploads it and gives you its fileRef. a public https:// link: filepath. Short text: content. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user. - `submit_feedback`: Anonymous bug report / feature request / docs gap, queued for human review. Default routing: `public-feedback` inbox (general AILANG). Pass `package="vendor/name"` (e.g. "sunholo/auth") to route to that package's `pkg:vendor/name` inbox where its autonomous agent watches. Categories: bug, feature, docs, limitation. Body limit 10KB, snippet limit 4KB. Optional contact field for follow-up; opaque to the server. Set `auto_dispatch=true` to authorize the package agent to act on your submission immediately (default false — files for human triage; pkg-feedback agent template lands in a separate sprint). - `uploadDocument`: Let the user pick a file to parse: shows the AILANG Parse card with a Choose file button. The card uploads the file and tries to summarise it for you; either way you get its fileRef. Then call mcpParse with that fileRef for the content (the same user can reuse it for 30 minutes; a large document comes in parts). Use this when the user wants to pick a file, or when createUpload's curl fails with a network error. For a file already in your sandbox or workspace, use createUpload + curl instead. Never parse the file yourself. - `uploadViaHost`: Receive a file from the AILANG Parse upload widget, relayed by the host as base64. Only the widget calls this; ticket is the upload token it holds.