FileForge

Overview Schema Source Related Servers Discussions Admin

fileforge_file_action

Fetch, parse, and convert files, extract text from documents, and decode or inspect Data URIs. Use it for file and embedded asset processing, not HTML page scraping.

Instructions

Fetch, parse and convert files, extract text, and decode data URIs, including those in a page. Use this for documents and embedded assets, and fileforge_scrape_action for HTML pages. Fetches public URLs without your browser session; private addresses need FILEFORGE_ALLOWED_FETCH_HOSTS. Local paths need the output folders of ~/.fileforge or FILEFORGE_ALLOWED_READ_PATHS. Can write files locally.

Input Schema

Name	Required	Description	Default
`to`	No	Target format: json, csv, tsv or txt. csv and tsv need tabular input.
`run`	No	Run ID that groups output files.
`url`	No	Public http(s) URL, or a local path in an allowed folder.
`from`	No	Source format. Inferred from the URL and content type if omitted.
`name`	No	Output file name.	converted-data-uri
`limit`	No	Maximum items to return.
`store`	No	Save the result in ~/.fileforge and return a ref.
`tabId`	No	Tab ID, or "active" for the active tab.	active
`action`	Yes	What to do. Required parameters are in brackets. convert (url, to): Convert a file to another format. extract_text (url): Extract plain text from a file (PDF, DOCX, etc.). parse_data_uri (dataUri): Parse and decode a Data URI. inspect_data_uri (dataUri): Inspect a Data URI: MIME, encoding, decoded size, preview-safe text, image dimensions, and warnings. decode_data_uri (dataUri): Decode a Data URI into a local artifact and return compact metadata. extract_data_uris_from_page: Find Data URIs embedded in the active page DOM, styles, links, images, media, and scripts. convert_data_uri_image (dataUri): Convert an image Data URI to PNG, JPEG, or WebP using the browser canvas and store it as an artifact. fetch_resource (url): Fetch a resource URL and save it locally. parse_resource (url): Fetch and parse a resource (JSON, CSV, XML, etc.).
`format`	No	Image format for convert_data_uri_image, or the format to parse as for parse_resource. Inferred if omitted when parsing.	png
`dataUri`	No	Data URI to read.
`project`	No	Project name that groups stored results.	default
`quality`	No	Image quality for lossy formats.
`textPreviewLimit`	No	Maximum characters in the text preview.
`includeTextPreview`	No	Include a preview of the text.

Output Schema

Name	Required	Description
`ok`	Yes	False if the action failed or a check did not pass.
`ref`	No	Stored result ID, for fileforge_result_action.
`data`	No	The result. Its shape depends on the action.
`meta`	No	Tool, action and context.
`error`	No	Failure code and message.
`warnings`	No	Notes about a call that still ran.

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.3.0Nov 5, 2026

changedInput schema / properties / action / description

Previous value: -"The action to perform. Available actions: convert: Convert a file to another format. extract_text: Extract plain text from a file (PDF, DOCX, etc.). parse_data_uri: Parse and decode a Data URI. inspect_data_uri: Inspect a Data URI: MIME, encoding, decoded size, preview-safe text, image dimensions, and warnings. decode_data_uri: Decode a Data URI into a local artifact and return compact metadata. extract_data_uris_from_page: Find Data URIs embedded in the active page DOM, styles, links, images, media, and scripts. convert_data_uri_image: Convert an image Data URI to PNG, JPEG, or WebP using the browser canvas and store it as an artifact. fetch_resource: Fetch a resource URL and save it locally. parse_resource: Fetch and parse a resource (JSON, CSV, XML, etc.)."New value: +"What to do. Required parameters are in brackets. convert (url, to): Convert a file to another format. extract_text (url): Extract plain text from a file (PDF, DOCX, etc.). parse_data_uri (dataUri): Parse and decode a Data URI. inspect_data_uri (dataUri): Inspect a Data URI: MIME, encoding, decoded size, preview-safe text, image dimensions, and warnings. decode_data_uri (dataUri): Decode a Data URI into a local artifact and return compact metadata. extract_data_uris_from_page: Find Data URIs embedded in the active page DOM, styles, links, images, media, and scripts. convert_data_uri_image (dataUri): Convert an image Data URI to PNG, JPEG, or WebP using the browser canvas and store it as an artifact. fetch_resource (url): Fetch a resource URL and save it locally. parse_resource (url): Fetch and parse a resource (JSON, CSV, XML, etc.)."

addedInput schema / properties / dataUri / description
```
Added value: +"Data URI to read."
```

addedInput schema / properties / format / description

Added value: +"Image format for convert_data_uri_image, or the format to parse as for parse_resource. Inferred if omitted when parsing."

changedInput schema / properties / from / description

Previous value: -"Source format"New value: +"Source format. Inferred from the URL and content type if omitted."

addedInput schema / properties / includeTextPreview / description
```
Added value: +"Include a preview of the text."
```
addedInput schema / properties / limit / description
```
Added value: +"Maximum items to return."
```
addedInput schema / properties / name / description
```
Added value: +"Output file name."
```

addedInput schema / properties / project / description

Added value: +"Project name that groups stored results."

addedInput schema / properties / quality / description
```
Added value: +"Image quality for lossy formats."
```

addedInput schema / properties / run / description

Added value: +"Run ID that groups output files."

addedInput schema / properties / store / description

Added value: +"Save the result in ~/.fileforge and return a ref."

addedInput schema / properties / tabId / description

Added value: +"Tab ID, or \"active\" for the active tab."

addedInput schema / properties / textPreviewLimit / description
```
Added value: +"Maximum characters in the text preview."
```

changedInput schema / properties / to / description

Previous value: -"Target format"New value: +"Target format: json, csv, tsv or txt. csv and tsv need tabular input."

changedInput schema / properties / url / description

Previous value: -"URL or local path of the file"New value: +"Public http(s) URL, or a local path in an allowed folder."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "query_* actions return their modules as extra top-level fields.",
+  "properties": {
+    "data": {
+      "description": "The result. Its shape depends on the action."
+    },
+    "error": {
+      "description": "Failure code and message."
+    },
+    "meta": {
+      "description": "Tool, action and context."
+    },
+    "ok": {
+      "description": "False if the action failed or a check did not pass.",
+      "type": "boolean"
+    },
+    "ref": {
+      "description": "Stored result ID, for fileforge_result_action."
+    },
+    "warnings": {
+      "description": "Notes about a call that still ran."
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedv0.2.1Nov 5, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Beyond the annotations, the description discloses that fetches bypass the browser session, that private addresses require an allow-list env var, and that the tool "can write files locally" — consistent with readOnlyHint=false and destructiveHint=false. It does not mention that results are persisted by default (store=true) or any rate/size limits on remote fetches.

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?

Four front-loaded sentences with the capability summary first, then routing, then access constraints, then side effects. Dense and mostly waste-free, though the "including those in a page" clause is awkwardly attached and the write-behavior note reads as an afterthought.

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?

For a 15-parameter, multi-action tool the description covers the three things structured fields cannot: sibling routing, network/permission preconditions, and the local write side effect. Return values are handled by the existing output schema, so no further detail is required.

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

Parameters3/5

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

Schema description coverage is 100% across all 15 parameters, including per-action required-parameter hints in the action enum, so the baseline is 3. The prose adds meaning only for `url` (public http(s) vs. allowed local path) and nothing about `run`, `project`, `store`, or `limit` beyond the schema.

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

Purpose4/5

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

The opening sentence names concrete verbs and resources (fetch, parse, convert files; extract text; decode data URIs) and explicitly separates the tool from fileforge_scrape_action. The gap is that it is a nine-action bundle: inspect_data_uri and convert_data_uri_image have no counterpart in the prose, so an agent must open the schema to learn the full surface.

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

Usage Guidelines5/5

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

"Use this for documents and embedded assets, and fileforge_scrape_action for HTML pages" gives an explicit when-to-use plus the named alternative. It also states the preconditions that select or block usage: public URLs work without a browser session, private hosts require FILEFORGE_ALLOWED_FETCH_HOSTS, and local paths must sit in allowed folders.

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