Librarian

A knowledge management MCP server for AI coding assistants. Capture insights, search with semantic understanding, and access a library of developer knowledge.

Installation

Plugin (full experience)

Includes MCP tools, slash commands, and hooks.

/plugin marketplace add telvokdev/librarian
/plugin install librarian@librarian

MCP only

claude mcp add librarian -- npx @telvok/librarian-mcp

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Add to your MCP config:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Or install globally:

npm install -g @telvok/librarian-mcp

Quick Start

// Search before making decisions
brief({ query: "stripe webhook handling" })

// Capture what you learned
record({
  insight: "Stripe retries webhooks but doesn't dedupe - always check idempotency key",
  context: "payments, webhooks"
})

// Mark helpful entries to boost their ranking
mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })

// Browse the library
library_search({ query: "react patterns" })

API Reference (Beta)

Local Knowledge

| Tool | Purpose | |------|---------| | brief(query?, limit?) | Semantic search across your library | | record(insight, ...) | Capture knowledge worth keeping | | adopt(path, title?) | Copy imported entry to local library | | mark_hit(path) | Mark an entry as helpful (increases ranking) | | import_memories(format, path) | Import from other AI tools | | rebuild_index(force?) | Rebuild semantic search embeddings | | delete(path?, query?, confirm?) | Delete entries from local library |

Library

Browse and publish books at telvok.com. Free and paid content supported.

| Tool | Purpose | |------|---------| | library_search(query, filters?) | Search Telvok library | | library_download(slug) | Download a free book locally | | library_publish(name, attestation, ...) | Publish entries as a book | | my_books(filter?) | View published and downloaded books | | sync(slug?, force?) | Check for updates to owned books | | rate_book(slug, rating, ...) | Rate a book (1-5 stars) | | seller_analytics() | View download stats for your books |

Bounties

| Tool | Purpose | |------|---------| | bounty_create(title, ...) | Post a knowledge request | | bounty_list(query?, tags?, status?) | Browse available bounties | | bounty_claim(bounty_id) | Claim a bounty to fulfill | | bounty_submit(bounty_id, book_slug) | Submit fulfillment | | my_bounties(role?) | View your bounties |

Account

| Tool | Purpose | |------|---------| | auth(action) | Login, logout, status, complete | | help(topic?) | Get help on any tool | | feedback(message, type?) | Send feedback |

How Search Works

Librarian uses local AI embeddings for semantic search:

You saved:   "Stripe webhooks need idempotency checks"
You search:  "handling duplicate payment events"
→ It finds it.

• all-MiniLM-L6-v2 model (384-dim embeddings)
• ~30MB download on first run, cached locally
• No API calls — fully offline

Results ranked by semantic similarity, recency (60%), and hit count (40%).

Import Formats

| Format | Sources | |--------|---------| | jsonl | Anthropic MCP Memory, mcp-knowledge-graph | | markdown | Obsidian, Basic Memory MCP | | cursor | Cursor Memory Bank | | json | Simple memory servers | | sqlite | mcp-memory-service, SQLite-vec |

Authentication

1. auth({ action: "login" }) — returns code + URL
2. Visit telvok.com/device, enter the code
3. auth({ action: "complete" }) — saves API key locally

Keys stored in .librarian/.auth, expire after 90 days.

Library Structure

.librarian/
├── local/        # Your entries
├── imported/     # Downloaded books
├── packages/     # Purchased content
├── archived/     # Stale but searchable
├── index.json    # Semantic embeddings
├── models/       # Cached embedding model
└── .auth         # API key (git-ignored)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit changes (git commit -m 'Add my feature')
4. Push (git push origin feature/my-feature)
5. Open a Pull Request

License

MIT - Telvok