Suparse MCP Server

Official

by suparse

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Download Results

download_results

Destructive

Export Suparse document IDs to JSON, CSV, XLSX, or Google Sheets locally; optionally unpack ZIP files and return output paths.

Instructions

Export existing Suparse document IDs as JSON, CSV, XLSX, or Google Sheets to local disk. Returns output_path plus requested_format, artifact_format and content_type. Existing output files are overwritten: choose a new path unless replacement is intended. CSV/XLSX may return ZIP; its extension is corrected to .zip. Set unpack:true to also extract the separate files into a fresh folder and return output_paths. JSON is saved as parsed task groups. Google Sheets requires an immediate API response and saves metadata as JSON. For a known export_job_id use download_export_job to recover the original artifact. Does not delete remote documents.

Input Schema

Name	Required	Description
`format`	Yes	Export format to save locally. Use this tool for JSON, CSV, XLSX, or Google Sheets; google_sheets requires a working Google integration and saves response metadata and sheet URLs as JSON, not a spreadsheet binary.
`unpack`	No	For CSV/XLSX only: extract a returned ZIP into a new folder next to the saved archive and return output_paths. Keeps the ZIP. A single workbook or CSV is returned directly. Defaults false.
`api_url`	No
`export_type`	No	Export mode for CSV, XLSX, and Google Sheets. Defaults to unified. Accepted for JSON, which currently has the same task-group shape for either value.
`output_path`	No	Optional local file path or existing directory on the server's machine. Existing files are overwritten. Prefer an absolute path; ~ is not expanded. Omit to use the server's working directory with an API-provided or generated filename; check the returned output_path for the actual artifact, which may be ZIP.
`xlsx_layout`	No	XLSX layout. Applies only to xlsx exports and defaults to standard.
`document_ids`	Yes	Suparse document IDs to export.
`idempotency_key`	No	Optional UUID idempotency key. Retain this key and replay the identical document IDs, format, export type, and layout if submission confirmation is lost.
`wait_timeout_ms`	No	Maximum time in milliseconds to wait for an accepted export job to complete; defaults to 60000. This bounds completion waiting, including polling retries, not submission or transfer. Allow enough total time in the MCP client for all phases.

Output Schema

Name	Required	Description	Default
`format`	Yes
`export_type`	Yes
`output_path`	Yes
`xlsx_layout`	No
`content_type`	Yes
`document_ids`	Yes
`output_paths`	No
`export_job_id`	No
`artifact_format`	Yes
`idempotency_key`	No
`requested_format`	Yes
`google_sheets_metadata`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv1.5.0Oct 20, 2026

removedInput schema / properties / api_url / description

Removed value: -"Optional API base URL. Defaults to SUPARSE_API_URL or Suparse production API."

removedInput schema / properties / api_url / format
```
Removed value: -"uri"
```
addedInput schema / properties / api_url / not
```
Added value: +{}
```
removedInput schema / properties / api_url / type
```
Removed value: -"string"
```

changedInput schema / properties / export_type / description

Previous value: -"Export mode for csv, xlsx, and google_sheets. Defaults to unified."New value: +"Export mode for CSV, XLSX, and Google Sheets. Defaults to unified. Accepted for JSON, which currently has the same task-group shape for either value."

changedInput schema / properties / format / description

Previous value: -"Export format to write to local disk. Use this tool for csv and xlsx."New value: +"Export format to save locally. Use this tool for JSON, CSV, XLSX, or Google Sheets; google_sheets requires a working Google integration and saves response metadata and sheet URLs as JSON, not a spreadsheet binary."

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Optional UUID idempotency key. Retain this key and replay the identical document IDs, format, export type, and layout if submission confirmation is lost.",
+  "format": "uuid",
+  "type": "string"
+}

changedInput schema / properties / output_path / description

Previous value: -"Optional local output file path or existing directory. When omitted, writes to the current working directory using the API-provided or generated filename."New value: +"Optional local file path or existing directory on the server's machine. Existing files are overwritten. Prefer an absolute path; ~ is not expanded. Omit to use the server's working directory with an API-provided or generated filename; check the returned output_path for the actual artifact, which may be ZIP."

addedInput schema / properties / unpack

Added value: +{
+  "default": false,
+  "description": "For CSV/XLSX only: extract a returned ZIP into a new folder next to the saved archive and return output_paths. Keeps the ZIP. A single workbook or CSV is returned directly. Defaults false.",
+  "type": "boolean"
+}

addedInput schema / properties / wait_timeout_ms

Added value: +{
+  "description": "Maximum time in milliseconds to wait for an accepted export job to complete; defaults to 60000. This bounds completion waiting, including polling retries, not submission or transfer. Allow enough total time in the MCP client for all phases.",
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / xlsx_layout

Added value: +{
+  "description": "XLSX layout. Applies only to xlsx exports and defaults to standard.",
+  "enum": [
+    "standard",
+    "flat"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / artifact_format
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / content_type
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / export_job_id
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / google_sheets_metadata

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "folder_url": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "spreadsheet_id": {
+      "type": "string"
+    },
+    "spreadsheet_url": {
+      "type": "string"
+    },
+    "spreadsheets": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "spreadsheet_id": {
+            "type": "string"
+          },
+          "spreadsheet_url": {
+            "type": "string"
+          },
+          "template_group_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "template_name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "spreadsheet_id",
+          "spreadsheet_url"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / idempotency_key
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / output_paths

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / requested_format
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / xlsx_layout

Added value: +{
+  "enum": [
+    "standard",
+    "flat"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "format",
-  "export_type",
-  "output_path",
-  "document_ids"
-]New value: +[
+  "format",
+  "requested_format",
+  "artifact_format",
+  "content_type",
+  "export_type",
+  "output_path",
+  "document_ids"
+]

First observedv1.3.0Jul 30, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and openWorldHint=true, and the description sharpens that: it warns existing local output files are overwritten, explains CSV/XLSX may return a ZIP whose extension is corrected to .zip, notes Google Sheets needs an immediate API response and saves only metadata, and clarifies the destructive scope is local (does not delete remote documents). This adds real context beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded around the core export action, with overwrite and ZIP caveats in the middle and the alternative routing at the end. Nearly every sentence carries actionable detail, though the format/metadata sentences are somewhat packed and could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not required, yet the description still summarizes output_path/artifact_format. For a 9-parameter destructive export tool it covers overwrite risk, ZIP behavior, Google Sheets constraints, and the sibling alternative, leaving nothing critical implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 89%, so the schema already documents most parameters (baseline 3). The description still adds meaning on top: unpack extracting into a fresh folder with output_paths, JSON saved as parsed task groups, and CSV/XLSX ZIP behavior. It slightly exceeds the schema-only baseline but does not cover every parameter (e.g., idempotency_key, wait_timeout_ms).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Export existing Suparse document IDs as JSON, CSV, XLSX, or Google Sheets to local disk') and the scope of the operation. It also distinguishes itself from the sibling download_export_job by naming that tool for the known-export_job_id case, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to guidance (choose a new path unless replacement is intended; set unpack:true to also extract separate files) and one explicit alternative ('For a known export_job_id use download_export_job'). It also excludes delete_documents by stating it does not delete remote documents, but it does not explicitly contrast with the extraction/result siblings like get_task_results or fetch_json_results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server