Public assessment

urbanmorph/mdshare (mdshare-mcp)

mdshare-mcp · v1.4.0 · scanned Aug 3, 2026

What changed in the harness

Selection accuracy 100→100, token cost up 8%, unconfirmed writes 0%→0%.

Category breakdown

Where the score comes from.

Earned points across the four signals Gradable measures. Safety and Legibility are scored out of 30; Economics and Discoverability are scored out of 20.

01Safety

0.0 / 30

0.0 out of 30

02Legibility

24.9 / 30

24.9 out of 30

03Economics

19.0 / 20

19.0 out of 20

04Discoverability

14.3 / 20

14.3 out of 20

Highest-impact fix

Estimated gain +30 points

Add explicit identity and permission preflight tools

Expose machine-readable principal/tenant confirmation and a non-mutating permission check so agents can verify both before destructive actions.

Description evidence

Defects and rewrites.

11 defects found across the exposed tool descriptions. Suggested rewrites make purpose, inputs, boundaries, and returns easier for an agent to understand.

Tool	Defect types	Suggested rewrite
`read_document`	params_unexplained	Read a markdown document from mdshare by its document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}). Returns the document's markdown content; 'key' is optional and the admin key is loaded from local storage for documents uploaded via this MCP server. PREFER output_path over inline reading for large documents — writes directly to disk and returns a small summary (saved_to, bytes) instead of the full content.
`update_document`	params_unexplained	Replace the full content of an existing mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}). Requires edit or admin permission; 'key' is optional for documents in this MCP server's local store. Use either inline 'content' or a local 'file_path' (file_path wins and is PREFERRED for files already on disk to avoid transmitting content through the conversation). For small edits to large documents, consider patch_document instead, which keeps version history granular.
`patch_document`	params_unexplained	Apply an ordered set of find/replace operations to an existing mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}), without rewriting the full content — more efficient than update_document for small edits to large documents. Pass operations inline as an array of {find, replace, replace_all?} or from a local JSON 'file_path' (file_path wins and is PREFERRED to bypass inline transmission). Each 'find' string must be unique in the document unless replace_all is set. Requires edit or admin permission; 'key' is optional for documents in this MCP server's local store.
`generate_link`	params_unexplained no_return_description	Create a new share link for an existing mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}), with the requested permission (view, edit, or comment) and an optional label. Returns the generated shareable link/URL that can be distributed to others. Requires admin access; 'key' is optional for documents in this MCP server's local store.
`list_links`	params_unexplained no_return_description	List the existing share links for an mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}). Returns each link's token, status (active/revoked), permission, and label, so you can identify which link to revoke via revoke_link. Requires admin access; 'key' is optional for documents in this MCP server's local store.
`revoke_link`	no_return_description	Revoke a share link so it becomes permanently inactive and can no longer be used to access the document. First find the link's token via list_links, and pass it as link_token along with the owning document's document_id. Requires admin access; 'key' is optional for documents in this MCP server's local store, where document_id is used to look up the admin key. Returns confirmation that the link has been revoked.
`list_comments`	params_unexplained no_return_description	List all comments on an mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}), including each comment's content, author, anchor text, replies, and resolution status. Any valid access key works; 'key' is optional for documents in this MCP server's local store.
`post_comment`	params_unexplained no_return_description	Post a comment on an mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}). Optionally anchor the comment to specific document text via anchor_text, or reply to an existing comment via parent_id (one level nesting). Requires a comment, edit, or admin key; 'key' is optional for documents in this MCP server's local store. Returns the created comment, including its comment_id for later reference.
`get_versions`	params_unexplained no_return_description	Get the edit history of an mdshare document, identified by document_id (obtainable from an upload_markdown response, list_my_documents, or an existing mdshare link of the form https://mdshare.live/d/{id}). Returns the list of past versions showing who edited, when, and via what method. Any valid access key works; 'key' is optional for documents in this MCP server's local store.
`get_admin_url`	no_return_description	Retrieve the admin URL for a document previously uploaded via this MCP server. The admin URL grants full control and is equivalent to a password, so ONLY call this tool when the user explicitly asks to see, save, or copy the admin URL — never surface it during normal upload, share, or collaboration flows. Returns the admin URL (https://mdshare.live/d/{id}?key=adm_...) for the given document_id.
`register_document`	no_return_description	Register an mdshare admin URL you already have saved (in notes, chat history, emails, etc., e.g. https://mdshare.live/d/{id}?key=adm_...) so the document can be resumed without re-pasting the key each time. Verifies the URL against the live API and stores it in ~/.mdshare-mcp/documents.json. Returns the registered document's details (such as its document_id) so it can be managed with the other tools. Only accepts admin URLs (adm_ prefix); view/comment/edit share links are rejected.

Selection evidence

Confusable tool pairs.

4 pairs where similar names or overlapping descriptions may send an agent toward the wrong tool.

Tool A	Tool B	Confidence	Why they collide
`update_document`	`patch_document`	high	Both tools modify document content and the descriptions cross-reference each other; a vague task like 'fix the typo in section 2', 'change the title', or 'update my doc' could make the agent pick full-replace update_document when patch_document is the intended targeted edit (and vice versa for full rewrites), yielding wrong granularity or content handling.
`generate_link`	`list_links`	medium	A request like 'give me the share link for my doc' or 'can I share this document?' is ambiguous: the agent may list existing links instead of generating a new one, or generate a redundant link when the user just wanted the existing one; both accept the same document_id/key inputs with admin permission.
`list_links`	`list_my_documents`	medium	list_my_documents returns share_url/share_permission for each of the user's docs, so 'show me the links to my documents' or 'what have I shared?' could wrongly send the agent to list_my_documents (no document_id targeted) when the user meant per-document list_links, or vice versa for a specific doc.
`list_my_documents`	`get_admin_url`	low	For requests blending both concepts ('find the admin URL for the doc I uploaded earlier') the agent may pick list_my_documents alone, which explicitly does not return the admin credential, or call get_admin_url with a guessed document_id; the descriptions steer strongly apart but compound phrasing still risks a single wrong choice.

Compare the field

One score is useful.
The evidence makes it actionable.

Back to the leaderboard