The VFS (Virtual File System) server is how an external application reads, writes, edits, and searches CharmIQ content. Documents, Charms, Chats, Folders, source code, uploaded assets — everything addressable in CharmIQ is reachable here, through a single URI scheme and a small set of file-system-style tools.

If you're not sure which server you need, you probably need this one. The VFS is the entry point — almost every other server consumes URIs that VFS hands out.

Every document, folder, and asset is addressed by a 

The path portion of any CharmIQ web URL maps directly to the MCP URI — copy the path from the browser and prefix it with 

Web:  https://team.charmiq.ai/source/wGPmxb8DN3kgivtbpYSF
MCP:  charmiq://source/wGPmxb8DN3kgivtbpYSF

 (or omitting the URI) refers to the user's root folder — start there when exploring.

) are an additional admin-only scope. They appear in tool descriptions and discovery only when the calling user holds the 

Append a query string to a URI to control how content is read:

 for full RichtextMarkdown with authored and inherited CSS.

Use the same flag for reads, searches and edits. The default hides document

stylesheets, classes and inline styles while retaining prose, structure, images,

Applications and execution records. Content patches preserve hidden presentation.

Styling changes use the full view. Source documents remain literal plain text.

 argument and URI parameter are rejected.

Text pages default to 40,000 UTF-8 bytes; explicit ranges allow up to 100,000 bytes.

 arguments unchanged, concatenating only 

separators are already included. Continuations pin the document version, view and

resolved style dependencies. If a dependency changes, restart the read. Oversized

lines continue at a column offset. These are byte limits, not token guarantees.

Only a complete, contiguous whole-document read returns 

A page or scoped read cannot authorize a whole-document replacement. Patches need

no receipt. Version/style guidance is response metadata outside content coordinates;

 returns at most 1,000 UTF-8 bytes around each match and 40,000 bytes

across matches, with original line/column offsets.

 (public CSS), or a node URI. The result names winning and overridden

values, rule ownership and referenced tokens using the same cascade as the Styles

sidebar. Duplicate matches stay separate; each result includes its containing block

returns read-only Theme/import CSS and its tokens. Edit the document stylesheet

 source; an empty match creates a missing

stylesheet, and removing the complete carrier clears it. Body content and other

metadata cannot change in this scope. Concurrent content edits are retained; a

changed stylesheet requires fresh inspection. Override inherited rules in the

document stylesheet. Inspection does not change the document.

The result identifies the saved document version and every resolved dependency

version. Current permissions apply to both; inaccessible dependencies are reported

as gaps. Theme/import versions are current when inspected, even for an older

document version. Target pages include one full report and up to 20 lightweight candidate rows.

 (1–5, default 1) for more reports; paging

requires the reported document version. Dependencies can advance between calls.

The report is authored evidence, not browser-computed layout. Conditional rules,

pseudo-elements and interactive state require browser evidence. Missing required node

identities or oversized reports return an actionable refusal rather than guessed

 submissions require the complete-read receipt and authoring

version. In the default view, omitted presentation is preserved where ownership is

identifiable; ambiguous styled rewrites refuse. Use 

flag for an authoritative full-RMD replacement. The full view permits explicit

presentation removal. A submission identical to the served text returns

 and writes no Version; a different spelling of the same document

only that owner's inline color. Report elements include targets for ancestor

owners too. Copy the target of the owner whose declaration you intend to remove.

Mark targets cover the whole contiguous mark, including text across bold or italic boundaries; partial ranges refuse. Empty presentation-only marks are removed, while links and other semantic formatting remain. For shorthand rows, use the exact authored key after 

 removes the entire declaration. Template-driven styles/classes are edited through their RMD source.

Content, bold/italic, descendant styling and stylesheet rules stay intact. The

remaining cascade may reveal inherited styles; verify with 

permission is required; edits rebase through normal collaboration. A removed

or incompatible target can prevent an edit, so refresh inspection after a conflict.

Richtext tools share the selected content or full-RMD view; Source content stays plain text. There is no

 places a text summary first, followed by an MCP image block or an embedded

PDF resource when applicable. Structured output retains the original content and version,

including base64 bytes for binary assets. The client/model must support the media block.

Text reads include the version, returned range and any continuation.

 includes the complete matched chunks in both text and structured output.

 reads that exact stored version after checking current

access. Omit it for the latest version; an explicit argument overrides a valid URI version.

Version values must be non-negative safe integers; fractional or malformed values are refused.

ProseMirror positions, not offsets in RMD text. The range must be non-empty and within the

RMD preserves selected marks and ancestor structure, including canonical document-type

frontmatter. Source documents remain plain text. Historical-read failures never return

 when more content is needed. For a targeted edit, a matching page or scoped read is enough; a complete overwrite requires every page.

Content edits made by a Charm within CharmIQ retain that Charm in document history.

Access and creator identity remain those of the invoking User. Ordinary MCP calls

without Charm provenance are attributed to the User.

Three ways to edit a document; pick by what you have:

 retains its container and styling. To remove a block, include its complete structural markup, or an adjacent separator for a plain paragraph. A single deletion hunk removes complete textblocks or single-block list items without turning their separators into blank paragraphs; fully selected lists and quotes are removed with their final child. Required cell paragraphs and item markers with unselected continuations or child lists are refused. An otherwise empty document retains its required paragraph. RMD may spell an empty paragraph as 

; retaining its quote/list marker does not remove the block. Successful edits distinguish existing blocks emptied by the edit (

), excluding blocks refilled during collaboration.

 is a special case: it skips the read entirely and appends to the end. Great for log-style documents.

An existing empty paragraph can be filled using neighboring text as context,

including an empty first or last paragraph; its identity and neighbors remain intact.

Positions are ProseMirror coordinates in that Version. Match 

. Richtext ranges use RMD; Source selections remain

literal plain text. A selection excludes node/selector targets and cannot change document

attributes or structure outside its boundaries.

The Version identifies the state in which the edit is authored. Subsequent edits are

handled through ordinary document collaboration; the document need not remain unchanged.

 on the URI. Positional selections require

a Version. Without a selection, omitting the Version authors against the latest document.

Current edit access is required even when using historical content.

If collaboration drops changes, the tool returns a 

whether the replacement was not applied or only partially applied, with the document ID

and current Version. Surviving changes remain applied. Read the current document and

A paragraph split preserves the first paragraph's identity and gives the new paragraph

a fresh identity. Text outside the selection stays on its corresponding side.

 places the Charm Instructions it creates the same way). A named folder is used as given, and refused when you cannot add to it; 

 is omitted, the file goes to the folder of the document the request comes from — the document a Charm runs in, or the document hosting an Application — when you can add to that folder, and shares its permissions. Otherwise (you only view that folder, the document is at the root, or there is no document, as for an external client) it goes to your root, private to you. Each tool's 

 description says which applies to the request.

that task for future children to inherit. Only a task owned by the authenticated

user is updated. Association is best-effort: if the task is missing or unowned, the

 makes an editable document from a text file the client holds: the

Markdown becomes a Workspace document and other text (HTML, source code) a source

document, as the name and any frontmatter say. The caller needs Editor on the folder

and must be allowed the chosen type; a refused import makes nothing anywhere else. Text

that is not text throughout, a name that says binary, and text over the limit are

Each call makes a new document. If a reply is lost, the document may exist: look for it

 is for a client that holds a file's bytes. It creates the file in the

 for the top level; the caller needs Editor on the folder) and returns

PUT {upload.url}
{upload.headers}

<the file's bytes>

The URL writes only this file: its type, its exact 

never over bytes already there. The file shows as processing until its bytes arrive,

. An uploaded file stays a file, text included.

was made, for example the web page it was saved from. It is the same captured Place

extension made. A Place that names a Material is accepted only when you can read that

Material; otherwise nothing is made. A Place grants no access.

something at the same Place or to list what was made there. 

 lists the Materials you can read made at the Place and its

more specific places, newest edit first: every listable type (Notes included), or the one 

. For example, the files saved from a page:

list_dir

 returns the same way for both — if you need certainty, check the tool description before calling on an asset.

 — Manage the Charms whose System Prompts live as 

 — Run completions against Chat documents (which live in the VFS as 

 — Organize VFS content into named groups.

 — Grant or revoke per-user access to the documents, assets, and folders VFS addresses.

Read, write, edit, and search everything in a CharmIQ workspace — the entry point for almost every integration.

Scope	Content Type
`workspace`	Workspaces (rich-text documents)
`charm`	Charms / System Prompts
`chat`	Chat documents
`folder`	Folders
`note`	Notes; create, find and update through the Note MCP server
`source`	Source code documents
`file`	Uploaded assets (images, PDFs, etc.)

Tool	What It Does
`list_dir`	List folder contents, or what was made at a Place — returns names and URIs. A Chat that belongs to a Workspace is listed with `type=chat`, by name or at its Place, never among the folder's contents
`read_file`	Read a file or asset. Text with optional line ranges; native MCP image/PDF content; base64 text for other binary assets
`clear_styles`	Remove named local CSS properties or class tokens from an inspected element
`inspect_styles`	Inspect authored style ownership for text, a selector or node; retrieve document stylesheet or Theme/import CSS
`describe_file`	Name, description, parent folder, where it was made, content preview. An Asset's `storeStatus` (`storing`, `stored`, or `failed` with its `errorMessage`). A Chat that belongs to a Workspace names that Workspace as `parentDocument`. `verbose=true` returns the structural outline and the current shares (who has which role)
`create_file`	Create a new Workspace, Charm, Chat, or source document
`create_dir`	Create a new folder
`import_file`	Import a text file (Markdown, HTML, source) into a folder as an editable document
`upload_file`	Create a file in a folder and get a signed URL to PUT its bytes to
`write_file`	Rewrite a document body; omitted presentation is retained where ownership is identifiable
`append_file`	Append to the end of a document without reading it first
`replace_string`	Edit by exact text match (include 3+ lines of context)
`apply_diff`	Edit using a unified diff
`delete_file`	Delete a document (soft, recoverable) or asset (hard)
`move`	Move a document, asset, or folder to a different parent
`append_app_content`	Append text to an app-content inside an Application
`grep_search`	Fast text or regex search within a single file
`semantic_search`	Natural-language search for relevant documents. Limit it to one document `type` (`note`, `workspace`, `charm`, …), and scope it to a folder subtree (`recursive=false` for direct children only) or to `root` for documents not in any folder. Each result's `parentUri` is its folder, or the Workspace a Chat belongs to. `include: ['thumbnail', 'thumbnailDark']` adds each result's thumbnails to the structured result, for programs that show them
`search_passages`	Natural-language search for the matching text itself (content chunks). Scope to specific document URIs

Type	Delete Behavior
Documents (`workspace`, `charm`, `chat`, `source`)	Soft-delete. Recoverable from the UI.
Assets (`file`)	Hard-delete. Gone.
Folders	Soft-delete. Children move with the parent.

VFS MCP Server

The URI Scheme

Query Parameters

Reading Content and Styles

Inspect Styles

Clear Local Styles

Tools

Reading Without Re-Reading

Editing Patterns

Editing a Selected Range

Where a Create Lands

Folders Created Within Tasks

Importing a Text File

Uploading a File

Where a File Was Made

Soft vs. Hard Delete

Patterns

Next Steps