VFS MCP Server
Read, write, edit, and search everything in a CharmIQ workspace — the entry point for almost every integration.
|
|
https://api.charmiq.ai/mcp/vfsThe URI Scheme
charmiq:// URI:charmiq://{scope}/{id}[?format=...&version=...]
charmiq://.Web: https://team.charmiq.ai/source/wGPmxb8DN3kgivtbpYSF MCP: charmiq://source/wGPmxb8DN3kgivtbpYSF
workspace | |
charm | |
chat | |
folder | |
source | |
file |
root (or omitting the URI) refers to the user's root folder — start there when exploring.For Developers — Platform Pages ( charmiq://platform-page/…) are an additional admin-only scope. They appear in tool descriptions and discovery only when the calling user holds thePlatformPagePublishAdminrole.
Query Parameters
format | markdown, plain, html | markdown for Workspaces/Charms, plain for source code |
version |
charmiq://workspace/abc123?format=html&version=4.Tools
list_dir | |
read_file | |
describe_file | verbose=true returns the structural outline |
create_file | |
create_dir | |
write_file | |
append_file | |
replace_string | |
apply_diff | |
delete_file | |
move | |
append_app_content | |
grep_search | |
semantic_search |
Reading Without Re-Reading
Use describe_filebeforeread_file. It returns the name, description, parent folder, and a content preview. For Workspaces,verbose=truereturns the structural outline (headings, lists, embedded applications). Often the outline is enough.Use grep_searchfor known text,semantic_searchfor unknown. Grep is fast and exact (case-insensitive, regex optional). Semantic is broader but costs an embedding call.
Editing Patterns
write_file— you want to overwrite everything. Cleanest, but loses unsaved cursors.replace_string— you have an exact snippet to swap. Include three or more lines of surrounding context so the match is unique.apply_diff— you have a unified diff. Best when you're producing diffs from an LLM that's already trained on the format.
append_file is a special case: it skips the read entirely and appends to the end. Great for log-style documents.Soft vs. Hard Delete
workspace, charm, chat, source) | |
file) | |
delete_file returns the same way for both — if you need certainty, check the tool description before calling on an asset.Patterns
Always discover before you write. Call list_dironrootor a known folder to confirm parent IDs before creating new content. URIs are stable, but folder structures change.Prefer describe_fileoverread_filefor orientation. Cheap, structural, enough to decide whether to read deeply.Use semantic_searchsparingly. It's powerful and not free. Cache results when the user is exploring one topic over multiple calls.Pin a version when correctness matters. If your application reasons about a specific version, pass ?version=Non the URI. Otherwise you'll race the user's own edits.
Next Steps
charmiq://charm/… URIs.charmiq://chat/…).