Skip to main content
Glama
cornelcroi

bookmark-lens

by cornelcroi
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

title: Bookmark Lens emoji: šŸ”– colorFrom: indigo colorTo: blue sdk: docker pinned: false license: mit short_description: Semantic bookmark engine for MCP-enabled AI agents tags:

  • building-mcp-track-consumer

  • building-mcp-track-creative

Bookmark Lens

Your AI assistant remembers everything you've saved.

PyPI version Python 3.10+ License: MIT

What is Bookmark Lens?

Tired of losing bookmarks in browser folders? Searching for "that article about React hooks" but can't remember if it mentioned "hooks" or "useState" or "functional components"?

Bookmark Lens solves this with semantic search. Find bookmarks by what they're about, not just exact keywords. Search "authentication tutorials" and get results about login systems, OAuth, JWT - even if they never mention the word "authentication."

Traditional bookmarks: Folders ā†’ Subfolder ā†’ Where did I save it? ā†’ Give up, Google it again With Bookmark Lens: "Find that React tutorial from last week" ā†’ Found instantly

All processing happens locally on your machine. Your bookmarks stay private.

Related MCP server: mcp-bookmark-server

See It In Action

Demo coming soon - intelligent bookmark search in action

Features

  • šŸ§  Semantic Search ā€“ Find bookmarks by meaning, not just keywords

  • šŸ†“ Completely Free ā€“ No API keys required for core features

  • šŸ¤– LLM-Enhanced (Optional) ā€“ If your LLM uses this MCP tool, it can generate summaries, auto-tags, and topic classifications

  • Semantic Search - Find bookmarks by meaning, not just keywords

  • Rich Metadata - Automatic extraction of titles, descriptions, and content

  • Smart Tagging - Manual tags + auto-generated tags (Smart Mode)

  • Topic Classification - Automatic categorization (Smart Mode)

  • Date Filtering - Search by time ranges (natural language supported via LLM)

  • MCP Native - Works with Claude Desktop and other MCP clients

  • Fast - Local embeddings with sentence-transformers

Quick Setup

Claude Desktop (stdio mode)

  1. Open your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add bookmark-lens to the mcpServers section:

{
  "mcpServers": {
    "bookmark-lens": {
      "command": "uvx",
      "args": ["bookmark-lens"]
    }
  }
}

  1. Restart Claude Desktop

That's it! No installation, no setup, no configuration needed.

Other MCP Clients

For other MCP-compatible clients, use:

uvx bookmark-lens

HTTP Mode (Self-Hosted)

Bookmark Lens also supports Streamable HTTP transport for web-based integrations. This requires self-hosting as there is no hosted version available.

# Run HTTP server on default port (8000)
bookmark-lens --transport http

# Server available at: http://127.0.0.1:8000/mcp

# Custom port
bookmark-lens --transport http --port 8080

Multi-User Support

HTTP mode supports multiple users via the X-User-Id header. Each user's bookmarks are completely isolated:

# User "alice" saves a bookmark
curl -H "X-User-Id: alice" http://localhost:8000/mcp

# User "bob" saves a bookmark
curl -H "X-User-Id: bob" http://localhost:8000/mcp

# Alice and Bob have separate bookmark collections

  • Default: If no X-User-Id header is provided, defaults to dev-user

  • Isolation: Each user can only access their own bookmarks, tags, and statistics

  • Single Instance: One server can serve multiple users with complete data isolation

šŸ“– Self-hosting guide: See DEPLOYMENT.md for detailed instructions on running your own HTTP server, Docker deployment, multi-user setup, and security considerations.

Example Conversations

Research Workflow

You: Save https://arxiv.org/abs/2401.12345 with note "Interesting paper on attention mechanisms"

Claude: Saved! I've extracted:
- Title: "Efficient Attention: A Survey"
- Description: Comprehensive review of attention mechanisms...
- Auto-generated tags: #ai #research #attention #transformers

You: Find papers about attention from this month

Claude: Found 3 bookmarks:
1. "Efficient Attention: A Survey" (arxiv.org) - Today
   Tags: ai, research, attention, transformers

2. "Flash Attention Implementation" (github.com) - 3 days ago
   Tags: pytorch, optimization, gpu

3. "Attention is All You Need - Annotated" (nlp.seas.harvard.edu) - 1 week ago
   Tags: tutorial, transformers, nlp

Learning Path

You: I'm learning React. Save good tutorials as I find them with tag #react-learning

Claude: Great! I'll tag them for you.

You: [Later] Show me all my React learning resources

Claude: You have 12 React bookmarks:

**Fundamentals (4 bookmarks):**
- Official React Docs - react.dev
- React Tutorial for Beginners - youtube.com
- Thinking in React - beta.reactjs.org

**Advanced (5 bookmarks):**
- Custom Hooks Patterns - usehooks.com
- React Performance Optimization - web.dev
...

You: Which ones cover hooks?

Claude: 8 of your bookmarks discuss hooks:
[Semantic search finds all hook-related content even without "hooks" in title]

Content Curation

You: Show me my GitHub bookmarks by topic

Claude: Here's the breakdown:

**AI/ML (15 bookmarks)**
- Transformer models
- LLM training techniques
- Embedding systems

**Frontend (23 bookmarks)**
- React ecosystem
- Build tools
- State management

**DevOps (8 bookmarks)**
- Kubernetes guides
- CI/CD pipelines

You: What are my top 3 most-saved domains?

Claude:
1. github.com - 47 bookmarks
2. medium.com - 23 bookmarks
3. dev.to - 18 bookmarks

More examples: See USAGE_GUIDE.md for detailed workflows and advanced query patterns.

Architecture

bookmark-lens/
ā”œā”€ā”€ src/bookmark_lens/
ā”‚   ā”œā”€ā”€ server.py              # MCP server (stdio + HTTP/SSE)
ā”‚   ā”œā”€ā”€ config.py              # Configuration management
ā”‚   ā”œā”€ā”€ database/
ā”‚   ā”‚   ā”œā”€ā”€ duckdb_client.py   # Relational data (bookmarks, tags)
ā”‚   ā”‚   ā””ā”€ā”€ lancedb_client.py  # Vector embeddings
ā”‚   ā”œā”€ā”€ models/
ā”‚   ā”‚   ā””ā”€ā”€ bookmark.py        # Pydantic models
ā”‚   ā””ā”€ā”€ services/
ā”‚       ā”œā”€ā”€ content_fetcher.py # Web page fetching
ā”‚       ā”œā”€ā”€ embedding_service.py # Text ā†’ vectors
ā”‚       ā”œā”€ā”€ bookmark_service.py # Orchestration
ā”‚       ā””ā”€ā”€ search_service.py  # Hybrid search
ā”œā”€ā”€ data/                      # Local databases (gitignored)
ā””ā”€ā”€ tests/
    ā””ā”€ā”€ manual_test.py         # End-to-end testing

Technology Stack

  • FastMCP - Model Context Protocol with dual transport (stdio + HTTP/SSE)

  • DuckDB - Relational database (bookmarks, metadata, tags)

  • LanceDB - Vector database (embeddings for semantic search)

  • sentence-transformers - Local embedding model (all-MiniLM-L6-v2)

  • readability-lxml - Content extraction from web pages

  • Pydantic - Data validation and serialization

Technical deep-dive: See TECHNICAL.md for hybrid search architecture, performance benchmarks, and implementation details.

FAQ

How is this different from browser bookmarks? Browser bookmarks use folders and exact name matching. Bookmark Lens uses AI to understand meaning. Search "authentication" and find bookmarks about login, OAuth, JWT - even if they never use that word.

What about Raindrop.io or Pocket? They're cloud-based (your data on their servers) and require subscriptions for advanced features. Bookmark Lens is 100% local and free. Your data never leaves your machine.

Do I need an API key? No! Core features (save, search, tag) work completely offline with no API keys. Smart Mode (auto-summaries, auto-tags) is optional and uses your own LLM API key.

How much does Smart Mode cost? With Claude Haiku: ~$0.0005 per bookmark (half a cent). Process 1000 bookmarks for $0.50. It's optional - core features are free.

Is my data private? 100% private. Everything runs locally. Core features don't use the internet at all. Smart Mode only sends bookmark content to your chosen LLM (not to us).

What if I have thousands of bookmarks? Bookmark Lens handles thousands easily. Vector search is fast even with large collections. The sentence-transformer model runs locally on your CPU.

Why semantic search instead of keywords? Keywords fail when you don't remember exact words. "Find that authentication tutorial" won't find "OAuth guide for beginners." Semantic search understands they're about the same topic.

Can I export my bookmarks? Not yet (roadmap feature). Currently, data is in local DuckDB + LanceDB databases. You can access them directly if needed.

Can I self-host this with HTTP access? Yes! Bookmark Lens supports streamable HTTP transport. See DEPLOYMENT.md for self-hosting instructions. Note: There is no hosted version - you must run your own server.

Does it support multiple users? Yes! In HTTP mode, Bookmark Lens supports multiple users via the X-User-Id header. Each user's bookmarks are completely isolated - they can only access their own data. One server instance can serve many users with complete data separation. stdio mode is single-user only (defaults to dev-user).

MCP Tools

save_bookmark

Save a URL with optional note and tags.

Parameters:

  • url (required): URL to bookmark

  • note (optional): Context or reason for saving

  • tags (optional): List of tags

Example:

{
  "url": "https://example.com/article",
  "note": "Great explanation of embeddings",
  "tags": ["ai", "ml", "tutorial"]
}

search_bookmarks

Search bookmarks semantically with optional filters.

Parameters:

  • query (required): What to search for

  • domain (optional): Filter by domain (e.g., "github.com")

  • tags (optional): Filter by tags

  • from_date (optional): ISO 8601 date string

  • to_date (optional): ISO 8601 date string

  • limit (optional): Max results (default: 10)

Example:

{
  "query": "machine learning tutorials",
  "domain": "github.com",
  "tags": ["python"],
  "from_date": "2024-11-07T00:00:00Z",
  "limit": 5
}

get_bookmark

Get full details about a bookmark by ID.

Parameters:

  • id (required): Bookmark ID

update_bookmark

Update note and/or tags for a bookmark.

Parameters:

  • id (required): Bookmark ID

  • note (optional): New note

  • tags (optional): Tags to add/replace

  • tag_mode (optional): "replace" or "append" (default: "replace")

delete_bookmark

Delete a bookmark and all its associated data.

Parameters:

  • id (required): Bookmark ID

Example:

{
  "id": "bkm_abc123"
}

list_tags

List all tags with their usage counts.

Parameters: None

Example Response:

{
  "success": true,
  "count": 5,
  "tags": [
    {"tag": "ai", "count": 20},
    {"tag": "python", "count": 15},
    {"tag": "tutorial", "count": 8}
  ]
}

get_bookmark_stats

Get statistics about your bookmark collection with optional filters.

Parameters:

  • stat_type (optional): Type of statistics

    • "total" - Total count (default)

    • "by_domain" - Breakdown by domain

    • "by_topic" - Breakdown by topic

    • "by_tag" - Breakdown by tag

    • "by_date" - Activity over time

  • domain (optional): Filter by domain

  • topic (optional): Filter by topic

  • tags (optional): Filter by tags

  • from_date (optional): Filter after date (ISO 8601)

  • to_date (optional): Filter before date (ISO 8601)

  • limit (optional): For breakdown stats, top N results (default: 10)

Examples:

Total bookmarks:

{
  "stat_type": "total"
}

Bookmarks saved this week:

{
  "stat_type": "total",
  "from_date": "2024-11-07T00:00:00Z"
}

Top domains:

{
  "stat_type": "by_domain",
  "limit": 5
}

AI bookmarks by domain:

{
  "stat_type": "by_domain",
  "topic": "AI"
}

Configuration

All configuration is via environment variables (.env file):

# Database paths
BOOKMARK_LENS_DUCKDB_PATH=./data/bookmark_lens.db
BOOKMARK_LENS_LANCEDB_PATH=./data/embeddings.lance

# Embedding model
EMBEDDING_MODEL_NAME=all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384

# Content fetching
BOOKMARK_LENS_FETCH_TIMEOUT=30
BOOKMARK_LENS_USER_AGENT=bookmark-lens/0.1.0
MAX_CONTENT_LENGTH=50000

Installation Options

Reduce Installation Size (CPU-only PyTorch):

By default, PyTorch may install with CUDA support (~3GB). For most deployments, CPU-only is sufficient and much smaller (~200MB):

# Install CPU-only PyTorch first
pip install torch --index-url https://download.pytorch.org/whl/cpu

# Then install bookmark-lens
pip install bookmark-lens

This is recommended for Docker containers, serverless deployments, or any environment where you don't need GPU acceleration.

Smart Mode (LLM Enhancements)

Enable Smart Mode to get automatic summaries, tags, and topic classification for your bookmarks.

Setup

  1. Choose an LLM model (see LiteLLM providers)

  2. Get an API key from your provider

  3. Add to .env:

    LLM_MODEL=claude-3-haiku-20240307
LLM_API_KEY=your-api-key-here

  4. Restart the server

Recommended Models

  • claude-3-haiku-20240307 - Fast, cheap, good quality (Anthropic) [Recommended]

  • gpt-4o-mini - Fast, cheap (OpenAI)

  • gpt-4o - Better quality, more expensive (OpenAI)

  • claude-3-5-sonnet-20241022 - Best quality (Anthropic)

See LiteLLM documentation for 100+ supported models.

What Smart Mode Adds

  • Auto-summaries: Short (1-2 sentences) and long (1 paragraph) summaries

  • Auto-tags: 3-5 relevant tags automatically generated

  • Topic classification: High-level category (AI, Cloud, Programming, Data, Security, DevOps, Design, Business, Science, Other)

  • Better search: Summaries and topics included in embeddings for improved relevance

  • Markdown extraction: Full content extracted as Markdown (preserves structure)

Cost Estimate

With claude-3-haiku-20240307: ~$0.0005 per bookmark (very cheap!)

Performance

  • Core Mode (no LLM): Fast saves, only title/description extracted

  • Smart Mode (with LLM): Slower saves (~5-10s), full content + enhancements

Note: Smart Mode is completely optional. All core features work without any LLM configuration.

Embedding Models

Default: all-MiniLM-L6-v2 (384 dimensions, fast, good quality)

Alternatives:

  • all-mpnet-base-v2 (768 dimensions, better quality, slower)

  • paraphrase-multilingual-MiniLM-L12-v2 (384 dimensions, multilingual)

Change in .env:

EMBEDDING_MODEL_NAME=all-mpnet-base-v2
EMBEDDING_DIMENSION=768

How It Works

Saving a Bookmark

  1. Fetch - Downloads the web page

  2. Extract - Pulls out title, description, main content (Markdown in Smart Mode)

  3. Enhance - Generates summaries, tags, topic (Smart Mode only)

  4. Embed - Converts text to vector using local model

  5. Store - Saves to DuckDB (metadata) and LanceDB (vector)

Searching Bookmarks

  1. Embed Query - Converts search text to vector

  2. Vector Search - Finds similar bookmarks (LanceDB)

  3. Filter - Applies domain/tag/date filters (DuckDB)

  4. Rank - Sorts by similarity score

  5. Return - Top N results with relevance scores

Natural Language Dates

The LLM (via the bookmark_search_guide prompt) converts natural language to ISO dates:

  • "yesterday" ā†’ 2024-11-13T00:00:00Z

  • "last week" ā†’ 2024-11-07T00:00:00Z

  • "last month" ā†’ 2024-10-14T00:00:00Z

The server only accepts ISO 8601 format - the LLM does the conversion.

Development

Want to contribute? See CONTRIBUTING.md for setup instructions.

Running Tests

# Clone the repository
git clone https://github.com/yourusername/bookmark-lens.git
cd bookmark-lens

# Install in development mode
pip install -e ".[dev]"

# Run tests
python tests/test_simple.py

Troubleshooting

"Model not found" error

The first run downloads the embedding model (~80MB). This is normal and happens once.

"Database locked" error

Close any other processes using the database. DuckDB doesn't support concurrent writes.

Search returns no results

  • Check if bookmarks were saved successfully

  • Try a broader query

  • Verify embedding model loaded correctly

Slow first search

The embedding model loads on first use. Subsequent searches are fast.

Roadmap

Phase 2 (Smart Mode - Future)

  • LLM-powered summaries

  • Auto-tagging

  • Topic classification

  • Query expansion

Future Features

  • Browser history import

  • Browser extension

  • Export/import bookmarks

  • Bookmark collections

  • Sharing capabilities

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please:

  1. Check TASKS.md for current status

  2. Follow existing code style (minimal, focused implementations)

  3. Add tests for new features

  4. Update documentation

Credits

Built with:

Available Tools

8 tools
delete_bookmarkB

Delete a bookmark and all its associated data.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe bookmark ID to delete

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It implies destructive action but does not disclose irreversibility, side effects, permissions, or error scenarios.

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?

Single sentence with no unnecessary words, directly conveying the purpose. Efficiently structured.

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

Completeness2/5

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

Despite having an output schema, the description lacks details on irreversibility, failure modes, or authorization needs. With no annotations, it should provide more context.

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% with a clear description for the 'id' parameter. Description adds no meaning beyond the schema, warranting baseline 3.

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?

Description clearly states 'Delete a bookmark and all its associated data,' specifying the verb and resource, and distinguishes it from siblings like get_bookmark, update_bookmark, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives, no prerequisites or exclusions mentioned. The description only states the action without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bookmarkA

Get full details about a specific bookmark by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe bookmark ID

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

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

No annotations exist; description only states 'Get full details' without disclosing error behavior for non-existent IDs, authorization needs, or any side effects. Lacks essential behavioral context for safe use.

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?

Single, front-loaded sentence with zero wasted words, efficiently conveying the tool's core function.

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?

With an output schema present, return values need no elaboration. However, missing information about error handling (e.g., ID not found) prevents full completeness for a simple tool.

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% with parameter description 'The bookmark ID'. Description adds no extra meaning beyond 'by ID', so it meets baseline but doesn't enhance understanding.

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?

Description clearly states 'Get full details about a specific bookmark by ID', specifying verb, resource, scope, and method of identification, distinguishing it from sibling tools like delete_bookmark or get_bookmark_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies use when a bookmark ID is known and full details are needed, but no explicit guidance on when not to use or alternatives provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bookmark_contentA

Get the full content of a bookmark in Markdown format.

Use this tool when the user wants to:

  • Read the full article content

  • Get a summary of the bookmark (you will summarize the returned content)

  • Analyze or discuss the bookmark content in detail

  • Quote specific parts of the article

  • Get fresh content from the URL

After calling this tool, YOU should summarize or analyze the content based on what the user asked.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe bookmark ID

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It states the output is in Markdown format and implies fresh content from the URL. It also tells the agent to summarize. However, it does not disclose whether the tool is read-only, destructive, requires authentication, or has rate limits. The overall behavior is clear but could be more explicit about safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise at about six lines. It front-loads the main purpose and includes helpful usage guidance. However, it contains meta-instructions to the agent ('you will summarize') which adds some redundancy. Still efficient overall.

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?

With one parameter, high schema coverage, and an output schema, the description is fairly complete. It covers the output format (Markdown) and various use cases. It lacks error handling details or prerequisites, but given the output schema likely documents return values, it is adequate.

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?

The only parameter 'id' is described in the schema as 'The bookmark ID' with 100% coverage. The description does not add extra meaning beyond the schema, such as how to obtain the ID or its format. Baseline is 3 due to high schema coverage.

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?

The description clearly states the tool gets the full content of a bookmark in Markdown format. It uses a specific verb ('Get') and resource ('bookmark content'), and distinguishes from siblings like 'get_bookmark' (which likely returns metadata) by specifying it returns full article content.

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?

The description explicitly lists when to use the tool: reading full article, getting a summary, analyzing or discussing content, quoting parts, or getting fresh content from the URL. It also instructs the agent to summarize after calling. However, it does not mention when NOT to use or mention alternatives like 'get_bookmark' for metadata.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bookmark_statsA

Get statistics about your bookmark collection with optional filters.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNoFilter by tags
limitNoFor 'by_*' stats, limit to top N results (default: 10)
topicNoFilter by topic
domainNoFilter by domain (e.g., 'github.com')
to_dateNoFilter bookmarks before this date (ISO 8601 format)
from_dateNoFilter bookmarks after this date (ISO 8601 format)
stat_typeNoType of statistics: 'total' (count), 'by_domain' (top domains), 'by_topic' (topic breakdown), 'by_tag' (tag distribution), 'by_date' (activity over time)total

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It mentions 'optional filters' but does not disclose behavior such as performance implications, data freshness, or effect on other data. The existence of an output schema mitigates the need to describe return values.

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?

The description is a single sentence that immediately conveys the tool's purpose. No wasted words, and the most important information is front-loaded.

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?

With 7 parameters fully described in the schema and an output schema present, the description is sufficient for basic understanding. Some additional context about what kind of statistics (e.g., counts, distributions) is provided by the 'stat_type' parameter schema, so completeness is high.

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 baseline is 3. The description adds no extra meaning beyond what the schema provides; it simply states 'with optional filters', which is redundant with the schema's 'description' fields.

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?

The description clearly states 'Get statistics about your bookmark collection with optional filters', which is a specific verb+resource combination. It distinguishes from siblings like search_bookmarks (which returns individual results) and list_tags (which lists tags).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for aggregate statistics, but does not explicitly state when to use this tool versus alternatives. It lacks guidance on when not to use it or mention of any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsA

List all tags with their usage counts.

Returns: List of tags with counts

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It correctly states it lists all tags with counts, implying a read-only operation. It could mention if results are ordered or paginated, but the simplicity of the tool makes this sufficient.

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?

The description is extremely conciseā€”two short sentences with no fluff. Every sentence adds value: the first states the action, the second describes the return format.

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

Completeness5/5

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

Given the tool's simplicity (no parameters, no complex behavior) and the existence of an output schema, the description is complete. It exhaustively covers what the tool does and returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters and schema description coverage is 100%. For a 0-parameter tool, the baseline is 4, and the description does not need to add parameter information.

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?

The description clearly states 'List all tags with their usage counts', specifying the verb (list), resource (tags), and additional context (usage counts). There are no sibling tag tools, so differentiation is not needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives. Since sibling tools are all bookmark-related, confusion is unlikely, but explicit when-to-use instructions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_bookmarkA

Save a bookmark to the user's bookmark collection.

IMPORTANT: Use this tool whenever the user asks to:

  • "Save this URL"

  • "Bookmark this"

  • "Add to bookmarks"

  • "Remember this page"

  • Or any similar request to save a URL

After saving, consider helping the user by:

  1. Calling get_bookmark_content(id) to fetch the article

  2. Summarizing the content for them

  3. Calling update_bookmark(id, note=summary) to save the summary

This provides a helpful summary without requiring an API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to bookmark
noteNoOptional note explaining why you saved this or context
tagsNoOptional tags to categorize this bookmark

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It describes the action of saving but does not disclose return value behavior, duplicate handling, permissions, or rate limits. The post-save workflow hints at return of an ID but not explicitly. Adequate but could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and uses structured lists for examples and post-save workflow. It is clear but contains some extraneous detail about post-save actions that could be part of user guidance rather than tool description. Still, overall concise and well-organized.

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?

Given the tool's simplicity (3 parameters, output schema exists), the description covers primary use well. It lacks discussion of error scenarios or duplicate handling, but for a straightforward 'save' tool it is largely complete.

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 parameters are fully documented in the schema. The description does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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?

The description clearly states the tool saves a bookmark to the user's bookmark collection, with specific verb+resource. Examples of user requests ('Save this URL', 'Bookmark this') further clarify purpose. It is well distinguished from siblings which focus on other operations like deletion or updates.

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?

The description provides explicit when-to-use triggers with example phrases. It also suggests a post-save workflow. However, it does not mention when to avoid using this tool (e.g., for updating existing bookmarks) or explicitly differentiate from other sibling tools like update_bookmark.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_bookmarksA

Search the user's bookmark collection using semantic search.

IMPORTANT: Use this tool whenever the user asks to:

  • "Find bookmarks about..."

  • "Search my bookmarks for..."

  • "Show me bookmarks..."

  • "Do I have any bookmarks about..."

  • Or any similar request to find saved bookmarks

Supports semantic search (meaning-based) with optional filters for domain, tags, and dates.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNoFilter by tags
limitNoMax results to return (1-100)
queryYesWhat to search for (semantic search)
domainNoFilter by domain (e.g., 'github.com')
to_dateNoFilter bookmarks before this date (ISO 8601 format: '2024-11-14T23:59:59Z')
from_dateNoFilter bookmarks after this date (ISO 8601 format: '2024-11-14T00:00:00Z')

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. Discloses semantic search capability and optional filters. Does not mention any destructive side effects, which aligns with its read-only nature. Missing details on result behavior (e.g., empty results) but sufficient.

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?

Concise yet complete: one sentence for purpose, bullet list for use cases, one sentence for features. No redundant wording. Front-loaded with key information.

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?

Given output schema exists, return values are covered. Description covers purpose, when to use, and available filters. Missing details on pagination or sorting but acceptable for a search tool.

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 description adds little beyond schema. It restates that filters include domain, tags, and dates, which is already in parameter descriptions. No additional semantics or constraints provided.

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?

The description specifies 'Search the user's bookmark collection using semantic search,' clearly indicating the action and resource. It distinguishes from sibling tools like 'get_bookmark' or 'save_bookmark' by focusing on search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use cases in bullet points (e.g., 'Find bookmarks about...'), guiding the agent on when to invoke this tool versus others. Also notes support for filters and semantic search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_bookmarkB

Update note and/or tags for an existing bookmark.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe bookmark ID
noteNoNew note (replaces existing)
tagsNoTags to add or replace
tag_modeNoWhether to 'replace' or 'append' tagsreplace

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full burden. It states it updates the bookmark, implying mutation, but does not disclose side effects, error handling (e.g., if ID not found), authorization needs, or return behavior.

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?

The description is a single concise sentence that efficiently conveys the tool's purpose, with no unnecessary words.

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

Completeness3/5

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

Given the tool's simplicity and the presence of a full input schema and output schema, the description is adequate but incomplete. It does not mention the output or behavior on error, which are not covered by schema alone.

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 the baseline is 3. The description adds no extra meaning beyond what is in the schema, merely echoing 'note and/or tags'.

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?

The description clearly states it updates note and/or tags for an existing bookmark, using the verb 'update' with a specific resource. However, it does not differentiate from sibling tools like 'save_bookmark' which might also modify a bookmark.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of 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.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a unique and clearly distinct purpose: delete, get details, get content, get stats, list tags, save, search, update. No overlapping functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, such as save_bookmark, delete_bookmark, search_bookmarks. The pattern is predictable and uniform.

Tool Count5/5

With 8 tools, the server covers essential CRUD operations, search, stats, and tags without excess or deficiency. The scope fits a bookmark management service well.

Completeness4/5

Core operations (save, get, update, delete, search, stats) are covered. The only minor gap is the lack of an explicit 'list all bookmarks' tool, though search may partially fulfill that role.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Bookmark Geni MCP Server

    droidnext
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic search across browser bookmarks from Chrome, Firefox, Edge, Opera, and other browsers using natural language queries. Extracts and indexes bookmark content and metadata into a vector database for intelligent retrieval.
    1
    Apache 2.0

  • mcp-bookmark-server

    preedew17
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to save and search bookmarks using OpenAI's RAG capabilities for intelligent bookmark management and retrieval.
    MIT

  • mcp-bookmark

    pree-dew
    A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to save and search bookmarks with semantic search using OpenAI, allowing storage of URLs with metadata and intelligent retrieval across collections.
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cornelcroi/bookmark-lens'

If you have feedback or need assistance with the MCP directory API, please join our Discord server