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 marketplace add telvokdev/librarian
/plugin install librarian@librarian

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

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

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

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

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

Library

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

Bounties

Account

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

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