Source of @markpin/mcp 0.9.0: an MCP server that lets Claude, Cursor and other AI clients search and read the web pages and highlights you saved with Markpin, a Chrome extension that keeps them as Markdown files in a folder you own.
Usage and setup: mcp-server/README.md.
mcp-server/ — the server (stdio, read-only unless --allow-write).
shared/ — the Markpin file format (parse/serialize), also used by the extension. Bundled into the npm package.
glama.json, glama/Dockerfile — for the Glama directory only.
This repository is published from Markpin's main repository on every release, so pull requests are applied there by hand. Issues are welcome here.
yarn install && yarn build && yarn testMIT License.
Returns one page in full: metadata, tags, summary, the reader's one-line note (note), reading state (bookmark, readAt or skimmedAt — at most one), extracted content, every clip with its note, highlight color and reaction mark (kind), the absolute path of the Markdown file, and absolute paths of clip images. Accepts a page id or its URL.
| Name | Required | Description | Default |
|---|---|---|---|
| idOrUrl | Yes | Page id (UUID) or the page URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already establishes this is a safe read, and the description goes further by disclosing the payload's invariants, notably that bookmark, readAt and skimmedAt are mutually exclusive ('at most one'). It also flags that absolute filesystem paths for the Markdown file and clip images are returned, which is non-obvious behavioral context. It stops short of describing error or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action followed by a well-ordered enumeration of returned fields. The single sentence is long and slightly run-on, but every clause conveys distinct payload information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of describing return values and does so thoroughly across metadata, tags, reading state, clips and file paths. The main omission is failure/no-result behavior for an unresolvable id or URL, which for a single-item fetch tool is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is a single parameter, so the schema already documents idOrUrl fully. The description's 'Accepts a page id or its URL' merely restates the schema description without adding format, validation, or lookup-precedence detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource, 'Returns one page in full', and enumerates exactly what a page contains. It implicitly distinguishes itself from list_recent, search and list_tags by retrieving a single page rather than a collection, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer this is the tool for fetching full details of one known page, since it accepts 'a page id or its URL'. There is no explicit statement of when to prefer this over search or list_recent, and no mention of what happens when the id/URL does not resolve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the most recently updated pages, newest first. With bookmarked=true, lists pages with a reading bookmark, newest bookmark first.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | How many pages to return. Default 20. | |
| bookmarked | No | Only pages with a reading bookmark. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the result ordering (newest first) and the fact that ordering switches to bookmark time when bookmarked=true. It doesn't mention pagination or result shape, but that is a minor gap against the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the primary behavior, then the conditional mode. No filler or restated title text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete enough for a simple two-param read tool: purpose, both parameter effects, and ordering are all stated, and there is no output schema whose return values would need narrating. Pagination/limit interplay with the default of 20 is left to the schema, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. However, the description adds meaning the schema lacks: with bookmarked=true the sort key changes to 'newest bookmark first' rather than newest update, which the boolean's own description ('Only pages with a reading bookmark') does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Lists the most recently updated pages') with a clear ordering, plus a distinct mode for bookmarked pages. It doesn't explicitly contrast itself with siblings like search or get_page, but the recent-list semantics are clearly separable from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description explains what bookmarked=true does but never says when to reach for this tool versus search or list_tags. An agent can infer the context (browse-by-recency) but there are no explicit conditions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every tag in use with the number of pages carrying it, most used first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by stating that results include page counts and are sorted most-used-first, though it does not cover pagination or result limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant or filler content. Every clause contributes useful information about the resource, return data, and ordering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with no output schema, the description is sufficiently complete. It explains what is returned (tags with page counts) and how results are ordered, giving the agent enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty and requires no parameter explanation. The description does not add parameter semantics because there are none, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it lists every tag in use, reports usage count, and specifies ordering. This clearly distinguishes it from siblings like list_recent, search, and get_page, which operate on pages rather than tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose strongly implies when to use it: when you need an overview of tags and their usage counts. However, it does not explicitly state when to choose this over alternatives or when not to use it, leaving usage guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over pages saved with Markpin (title, extracted content, clipped text, notes, tags). Returns page summaries ranked by relevance with a short snippet around the first match. With an empty query, lists the most recently updated pages (optionally filtered by tags). Summaries include readAt (when the user marked the page read) and bookmark (a reading bookmark: when it was set and, if placed inside the page, the sentence it points at).
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Only return pages that carry every one of these tags. | |
| limit | No | Maximum number of results. Default 10. | |
| query | No | Search terms. Prefix matching is on, so "type" also matches "typescript". | |
| bookmarked | No | Only pages with a reading bookmark (saved to read later or being read). With an empty query they come newest bookmark first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description is consistent with a read-only search. It adds useful behavioral context beyond annotations—relevance ranking, snippet generation, and the presence of readAt/bookmark fields—but does not disclose pagination, result limits beyond the schema, or ordering rules for ranked searches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences are densely packed but well ordered: capability, return format, empty-query mode, and result fields. Each sentence carries information, with only minor redundancy in the final field-explanation sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully explains the return shape (page summaries, snippets, readAt, bookmark). It is largely self-sufficient for a read-only search tool, though it omits ordering/pagination detail and explicit sibling routing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the schema, including prefix matching and tag AND-semantics. The description adds only the empty-query fallback behavior, which is a usage note rather than parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (full-text search) and resource (saved pages), and enumerates the searchable fields (title, content, clipped text, notes, tags). It is clearly distinguishable from get_page and list_tags, though it does not explicitly name how it differs from list_recent despite the empty-query behavior overlapping that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implied usage: empty query lists recently updated pages, and the bookmarked/tags filters narrow results. However, it never says when to prefer this tool over list_recent (which appears to serve the same recent-pages purpose) or when to use get_page for full content, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_pagelist_recentlist_tagssearchScored across 4 tools
Each tool targets a distinct retrieval axis: recency (list_recent), relevance/full-text (search), single-page detail (get_page), and tag aggregation (list_tags). The one fuzzy boundary is that search with an empty query duplicates list_recent's behavior, but the descriptions call this out explicitly enough that an agent can still choose correctly.
Three of four tools follow a clean verb_noun pattern (list_recent, get_page, list_tags); `search` is a bare verb, a minor deviation from the pattern but unambiguous. No style mixing (camelCase vs snake_case) or chaotic variants.
Four tools is slim but proportionate for what appears to be a read-only retrieval companion to a browser bookmarking extension. Each tool covers a genuinely different access path, so none feels redundant padding, though the surface is close to thin.
The read side is thorough — pages, tags, notes, clips, reading state, and two listing orders are all reachable. However, there is no write path at all: an agent cannot save a page, add a note or clip, tag anything, or set read/bookmark state, which are the core lifecycle actions the descriptions imply exist in the underlying product.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search, save, and set reminders in your personal MarkIt library of links, posts, and notes.
Personal context for every AI: search, read, and write back to your private Markdown library.
Search your Glasp web and Kindle highlights, notes, and AI memories from any MCP client. Read-only.
