Skip to main content
Glama
Sign In
markdown-vault-mcp

markdown-vault-mcp

by pvliesdonk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Fetch to Vault

fetch
Idempotent

Download a URL on the server and save it in the vault as a note or attachment; bytes stay off the conversation, and the returned path can be passed to other tools.

Instructions

Download a URL on the server and save it in the vault as a note or attachment; returns its path, size and final_url.

The bytes never pass through the conversation, so use it for large files and then pass the path to other tools.

Input Schema

NameRequiredDescriptionDefault
urlYesAn HTTP or HTTPS URL on the public internet. Redirects are followed, so check final_url in the result when the source host matters.
pathYesDestination path, such as `"notes/report.md"` or `"assets/diagram.png"`; .md saves a note, anything else an attachment.
if_matchNoEtag from read, to replace an existing file; omit for a new file.
timeout_sNoDownload timeout in seconds (default 30); raise it for a large file from a slow host.
frontmatterNoFrontmatter for a note, such as `{"title": "Report", "source": "https://example.org/report"}`.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv6.1.0
    • changedInput schema / properties / frontmatter / description
      Previous value: -"Optional YAML frontmatter dict for .md files,\ne.g. {\"title\": \"Report\", \"source\": \"http://...\"}. Ignored\nfor attachments."New value: +"Frontmatter for a note, such as\n`{\"title\": \"Report\", \"source\": \"https://example.org/report\"}`."
    • changedInput schema / properties / if_match / description
      Previous value: -"Etag from 'read'; required by default to replace an\nexisting file. A stale etag refuses the write. Omit for new files."New value: +"Etag from read, to replace an existing file; omit for a new file."
    • changedInput schema / properties / path / description
      Previous value: -"Destination path in the vault (e.g. \"notes/report.md\"\nor \"assets/diagram.png\"). Extension determines handling:\n.md for notes, anything else for attachments."New value: +"Destination path, such as `\"notes/report.md\"` or `\"assets/diagram.png\"`; .md\nsaves a note, anything else an attachment."
    • changedInput schema / properties / timeout_s / description
      Previous value: -"Download timeout in seconds (default 30). Increase\nfor large files on slow connections."New value: +"Download timeout in seconds (default 30); raise it for a large\nfile from a slow host."
    • changedInput schema / properties / url / description
      Previous value: -"Source URL to download from. Only http:// and https://\nschemes are allowed. SSRF protection (via pvl-core's hardened\n``fetch_url``, #862): the host is resolved and rejected unless\nevery address is publicly routable (private, loopback,\nlink-local, CGNAT/shared, and reserved ranges are all\nblocked), the validated IP is pinned for the connection\n(closing DNS rebinding), and ambient HTTP(S)_PROXY / .netrc\nsettings are ignored. Redirects ARE followed (changed in\n#1116; through v3.1.0 a redirect was refused), and every hop\nrepeats the whole chain above — a ``Location`` pointing at an\ninternal target is refused exactly as a directly supplied one\nis. Because of that, the bytes need not come from the host in\n*url*: check the returned ``final_url`` when the source host\nmatters."New value: +"An HTTP or HTTPS URL on the public internet. Redirects are followed, so\ncheck final_url in the result when the source host matters."
  2. Changed1 schema field changedv5.0.0
    • changedInput schema / properties / if_match / description
      Previous value: -"Optional etag from a previous 'read' call for\noptimistic concurrency. Omit to write unconditionally."New value: +"Etag from 'read'; required by default to replace an\nexisting file. A stale etag refuses the write. Omit for new files."
  3. Addedv4.0.0

TDQS

A4/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description is consistent, describing a save operation. It adds genuinely useful context the annotations don't carry – the bytes never traverse the conversation, so this is the right path for large payloads – though it doesn't warn about overwrite semantics when a file already exists at path.

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?

Two tight sentences: the operation and its return shape first, then the reason to prefer it. No filler, and the most decision-relevant fact (bytes bypass the conversation) is front-loaded in the second sentence.

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

Completeness4/5

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

Annotations cover the safety profile and an output schema exists, so the description needn't enumerate returns; it still names the return fields for convenience. Combined with 100% schema coverage, the definition is essentially complete, with only overwrite/concurrency behavior left unaddressed.

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 url, path, if_match, timeout_s and frontmatter are already fully documented, including the .md-vs-attachment rule and the redirect/final_url caveat. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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?

States a concrete verb+resource pair: downloads a URL server-side and saves it into the vault, with the destination deciding note vs attachment via the path schema. It implicitly differentiates from the vault-only siblings like read/list_documents, but never names an alternative explicitly.

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?

"Use it for large files and then pass the path to other tools" gives a clear selection rule and a follow-on workflow, which is real usage guidance. It stops short of naming the alternative (read) for the case where the content is already in the vault, or stating when-not to use it.

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