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

markdown-vault-mcp

by pvliesdonk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Note Diff

get_diff
Read-onlyIdempotent

Show how a note or attachment changed since a commit or timestamp as a unified diff, or one diff per commit.

Instructions

Return how a note or attachment changed from an earlier commit to now, as one unified diff or one per commit.

Pass exactly one of since_sha and since_timestamp; find commits with get_history. A vault without git history returns an empty diff.

Input Schema

NameRequiredDescriptionDefault
pathYesA note or attachment path, such as `"notes/alpha.md"`; a binary attachment returns a summary of size and renames instead of a patch.
limitNoWith per_commit, how many of the most recent commits to include, 1 to 100; omit for all.
since_shaNoA commit SHA to diff from, such as from get_history; at least 4 hex digits.
per_commitNoTrue for one diff per commit since the starting point, newest first; default false for a single diff.
since_timestampNoAn ISO 8601 time; diffs from the latest commit at or before it.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv6.1.0
    • changedInput schema / properties / limit / description
      Previous value: -"When per_commit=True, cap the number of intervening commits\nreturned to the `limit` most recent ones. Clamped to [1, 100].\nDefaults to null (unbounded — still bounded by the underlying\nsince..HEAD range). Ignored when per_commit=False. Useful for\nkeeping per-commit responses within context budgets when\nauditing long histories."New value: +"With per_commit, how many of the most recent commits to include, 1 to\n100; omit for all."
    • changedInput schema / properties / path / description
      Previous value: -"Vault-relative path of the note or attachment to diff (e.g.\n\"notes/alpha.md\" or \"assets/diagram.png\"). May be a `.md`\nnote or a configured attachment extension (png, pdf, svg, …).\nA binary attachment returns a `--stat` size/rename summary\ninstead of a full unified patch; a text attachment (e.g.\n`.svg`, `.csv`) returns a full unified diff. `.md` notes are\nunchanged. An unsupported extension is rejected."New value: +"A note or attachment path, such as `\"notes/alpha.md\"`; a binary attachment\nreturns a summary of size and renames instead of a patch."
    • changedInput schema / properties / per_commit / description
      Previous value: -"When False (default), return a single unified diff from\nthe reference point to HEAD. When True, return one diff per\nintervening commit."New value: +"True for one diff per commit since the starting point, newest\nfirst; default false for a single diff."
    • changedInput schema / properties / since_sha / description
      Previous value: -"A commit SHA (full or abbreviated, at least 4 hex digits)\nto diff from. Mutually exclusive with since_timestamp."New value: +"A commit SHA to diff from, such as from get_history; at least 4 hex\ndigits."
    • changedInput schema / properties / since_timestamp / description
      Previous value: -"ISO 8601 datetime string, resolved via\n`git rev-list --before=<ts> -1 HEAD` to the most recent\ncommit at or before that instant. Boundary is\n**inclusive**: a commit whose committer date equals\nsince_timestamp IS the resolved ref. Mutually exclusive\nwith since_sha."New value: +"An ISO 8601 time; diffs from the latest commit at or before\nit."
  2. First observedv3.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description still adds the mutual-exclusion rule the schema does not enforce and the empty-diff edge case for vaults without git history. It also discloses the per-commit vs unified output shape, though it says nothing about binary-vs-text beyond what the schema documents.

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?

Three short sentences with the core behavior front-loaded, then the constraint, then the edge case. No restated title, no filler, and the constraint is placed where an agent will read it before building arguments.

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?

Output schema and annotations carry the return format and safety profile, and the description covers the one genuine trap (specifying both since_sha and since_timestamp). Minor gaps remain: no mention of how limit interacts with per_commit default semantics, though the schema covers that.

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 coverage is 100%, so the schema already explains path, limit, since_sha, since_timestamp and per_commit in detail. The description's only addition is the exactly-one-of constraint between the two since_* parameters, which is a meaningful but small increment over the structured data.

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

Purpose5/5

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

Names a specific verb and resource ('Return how a note or attachment changed from an earlier commit to now') and immediately states the output shape (one unified diff or one per commit). This cleanly separates it from get_history, which the description routes to for finding commits.

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?

Gives an explicit precondition ('Pass exactly one of since_sha and since_timestamp') and names get_history as the way to obtain a SHA, which is real routing guidance. It stops short of saying when to prefer this over reading the note's current contents, but the core alternatives are covered.

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