Skip to main content
Glama
Sign In
Typst Web MCP

Typst Web MCP

by caphefalumi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

typst_edit_file

Apply multiple targeted edits to one Typst file in a single save, using unique oldText anchors and expectedHash to reject stale changes; invalid edits fail without saving.

Instructions

Apply all targeted edits against one original file snapshot, with one save. Prefer short unique oldText anchors and expectedHash from typst_read_file to reject stale edits. Exact matching by default (LF/CRLF resilient); matchMode='fuzzy' opts into Unicode/whitespace fallback. Malformed, ambiguous, or overlapping edits fail without saving. Summary output by default; dryRun previews a bounded diff. Unchanged characters and BOM are preserved.

Input Schema

NameRequiredDescriptionDefault
editsNoOne or more targeted non-overlapping replacements. Each oldText must be unique in the original file.
dryRunNoValidate and preview edits without saving (default: false). Returned contentHash still identifies unchanged cloud text.
outputNosummary (default): counts, new contentHash, firstChangedLine; diff: also a bounded display diff; full: also bounded patch and full metadata. dryRun defaults to diff.
newTextNoOptional replacement text for single replacement shorthand
oldTextNoOptional shorthand for a single replacement (used if edits is omitted)
filePathNoFile path/name (e.g. 'main.typ') or file ID
matchModeNoexact (default) matches source with newline normalization. fuzzy enables Unicode quote/dash/space/NFKC fallback only when an exact match is absent.
projectIdNoThe Typst project ID
expectedHashNoRecommended: contentHash from the latest read. Checked against fresh downloaded text inside the file mutation queue; stale files fail without saving.
maxDiffBytesNoByte budget per diff/patch field (default: 8192). Each also has a 100-line cap. Truncation is explicit; read affected ranges for full details.
preferWebSocketNoPush real-time TextUpdate over /editing/v3 WebSocket in addition to REST persistence (default: true)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv1.3.1
    • addedInput schema / properties / dryRun
      Added value: +{
+  "description": "Validate and preview edits without saving (default: false). Returned contentHash still identifies unchanged cloud text.",
+  "type": "boolean"
+}
    • changedInput schema / properties / edits / description
      Previous value: -"Non-overlapping exact text replacements to apply to the Yjs document"New value: +"One or more targeted non-overlapping replacements. Each oldText must be unique in the original file."
    • changedInput schema / properties / edits / items / properties / oldText / description
      Previous value: -"Exact unique substring to replace"New value: +"Unique source substring to replace. All edits match the original file, not earlier edits' results."
    • addedInput schema / properties / edits / items / properties / oldText / minLength
      Added value: +1
    • addedInput schema / properties / edits / minItems
      Added value: +1
    • addedInput schema / properties / expectedHash
      Added value: +{
+  "description": "Recommended: contentHash from the latest read. Checked against fresh downloaded text inside the file mutation queue; stale files fail without saving.",
+  "pattern": "^[a-fA-F0-9]{64}$",
+  "type": "string"
+}
    • addedInput schema / properties / matchMode
      Added value: +{
+  "description": "exact (default) matches source with newline normalization. fuzzy enables Unicode quote/dash/space/NFKC fallback only when an exact match is absent.",
+  "enum": [
+    "exact",
+    "fuzzy"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / maxDiffBytes
      Added value: +{
+  "description": "Byte budget per diff/patch field (default: 8192). Each also has a 100-line cap. Truncation is explicit; read affected ranges for full details.",
+  "maximum": 1048576,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / newText
      Added value: +{
+  "description": "Optional replacement text for single replacement shorthand",
+  "type": "string"
+}
    • addedInput schema / properties / oldText
      Added value: +{
+  "description": "Optional shorthand for a single replacement (used if edits is omitted)",
+  "type": "string"
+}
    • addedInput schema / properties / output
      Added value: +{
+  "description": "summary (default): counts, new contentHash, firstChangedLine; diff: also a bounded display diff; full: also bounded patch and full metadata. dryRun defaults to diff.",
+  "enum": [
+    "summary",
+    "diff",
+    "full"
+  ],
+  "type": "string"
+}
    • removedInput schema / required
      Removed value: -[
-  "projectId",
-  "filePath",
-  "edits"
-]
  2. First observedv1.0.2

TDQS

A4.1/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses atomic save semantics, default exact matching, LF/CRLF resilience, fuzzy fallback behavior, failure-without-saving on malformed or overlapping edits, dryRun preview behavior, and preservation of unchanged characters and BOM.

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

Conciseness5/5

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

The description is front-loaded and dense with relevant behavior in only a few sentences. Every sentence contributes either scope, matching semantics, failure behavior, output behavior, or preservation guarantees.

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?

Despite having 11 parameters and no output schema, the description covers the essential edit semantics, failure modes, output modes, and preservation guarantees an agent needs to invoke it correctly. Remaining details are well covered by the fully documented input schema.

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%, so the schema already documents all 11 parameters, including oldText, expectedHash, matchMode, output, and dryRun. The description adds some useful emphasis on short unique anchors and expectedHash freshness, but most parameter meaning is already present in 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 description states a specific verb and resource: applying targeted edits to one original file snapshot with a single save. That clearly distinguishes it from full-file writes, but it does not explicitly name or compare against the closest sibling alternatives such as typst_find_and_replace or typst_write_file.

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

Usage Guidelines3/5

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

It gives useful safety advice to prefer short unique oldText anchors and expectedHash from typst_read_file, but it does not say when to choose this tool over typst_find_and_replace or typst_write_file. Usage is implied by the multi-edit atomic-edit framing rather than stated with explicit alternatives.

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

Deploy Server

Other Tools