librarian-mcp (1.0.0)

Published 2026-02-07 21:08:07 +00:00 by ahknight

To install the package using pip, run the following command:

pip install --index-url  --extra-index-url https://pypi.org/simple librarian-mcp

For more information on the PyPI registry, see the documentation.

MCP server for document indexing and semantic search

Librarian MCP Server

A semantic knowledge graph server implementing the Model Context Protocol (MCP). Librarian transforms your markdown files into a persistent, queryable knowledge base with semantic annotations, full-text search, and graph-based context building.

Features

Semantic Annotations: Categorized observations and typed relations create a knowledge graph
Full-Text Search: SQLite FTS5 with BM25 ranking for fast, relevant searches
Multi-Project Support: Manage multiple isolated knowledge bases
Real-Time Sync: File watcher automatically indexes external changes
MCP Resources: Notes exposed as standard MCP resources with URI-based navigation
MCP Tools: 12 tools for creating, editing, searching, and analyzing knowledge
MCP Prompts: 6 pre-built workflows for common knowledge management tasks
Local-First: All data stored in plain markdown files you own

Quick Start

Installation

Requires Python 3.12+ and uv.

# Install from the package registry
uv pip install librarian-mcp --index-url https://code.movq.us/api/packages/movq/pypi/simple/

# Or install with pip
pip install librarian-mcp --index-url https://code.movq.us/api/packages/movq/pypi/simple/

Development Setup

# Clone the repository
git clone https://code.movq.us/movq/librarian-mcp.git
cd librarian-mcp

# Install with dev dependencies
uv sync --extra dev

Initialize Your First Project

# Initialize a project from an existing directory of markdown files
uv run librarian init ~/Documents/notes --set-default

# Or create a new project
mkdir -p ~/knowledge-base
uv run librarian init ~/knowledge-base --name main --set-default

Start the MCP Server

# Start with stdio transport (for Claude Desktop)
uv run librarian mcp

# Start with HTTP transport for network access
uv run librarian mcp --transport http --host 0.0.0.0 --port 4242

Configure Your MCP Client

Claude Desktop

Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "librarian": {
      "command": "uvx",
      "args": [
        "--index-url", "https://code.movq.us/api/packages/movq/pypi/simple/",
        "librarian-mcp",
        "mcp"
      ]
    }
  }
}

Usage

Creating Notes with Semantic Annotations

Librarian recognizes two types of semantic annotations in your markdown:

Observations

Categorized facts within notes:

## Observations
- [decision] Chose PostgreSQL for ACID compliance #database #architecture
- [requirement] Must support 10k concurrent users #scale
- [technique] Use connection pooling with pgbouncer #performance

Standard categories: idea, decision, fact, technique, requirement, question, insight

Relations

Directional links between notes using WikiLink syntax:

## Relations
- implements [[System Architecture]]
- requires [[Database Schema]]
- relates_to [[Performance Requirements]]

Standard relation types: relates_to, implements, requires, extends, part_of, contrasts_with, preceded_by, influenced_by

Using MCP Tools

Available Tools

write_note - Create or update a markdown note
edit_note - Modify existing notes (append, prepend, find_replace, replace_section)
delete_note - Remove notes or directories
move_note - Relocate notes while maintaining WikiLink references
search_notes - Full-text search with filtering and pagination
search - Cross-project search returning URIs
build_context - Graph traversal to gather related entities
recent_activity - View recent changes across projects
canvas - Create visual knowledge maps (Obsidian-compatible)
list_projects - Show all configured projects
create_project - Register a new project
delete_project - Remove a project from configuration

Example: Creating a Note

// Via MCP tool call
{
  "tool": "write_note",
  "arguments": {
    "title": "API Design Decisions",
    "directory": "projects",
    "project": "main",
    "content": `# API Design Decisions

## Context
Evaluated options for the new service API.

## Observations
- [decision] REST over GraphQL for simplicity #api
- [requirement] Must support pagination #api
- [technique] Use OpenAPI 3.0 for documentation

## Relations
- implements [[System Architecture]]
- requires [[Authentication]]`
  }
}

Using MCP Resources

Notes are exposed as standard MCP Resources with URI-based navigation:

librarian://notes/{project}/{permalink}           # Full note
librarian://notes/{project}/{permalink}#Section   # Specific section
librarian://notes/{project}/{permalink}?page=2    # Paginated

Example: Reading a Note Section

{
  "method": "resources/read",
  "params": {
    "uri": "librarian://notes/main/api-design#Observations"
  }
}

Using MCP Prompts

Prompts provide pre-built workflows for common tasks:

restore - Restore session context from the knowledge base
consolidate - Extract knowledge from current conversation
done - End session: consolidate + append to journal
search - Search with guided follow-up instructions
connect - Find potential connections for a note (TF-IDF keyword extraction)
review - Surface maintenance issues (orphaned notes, unresolved references, stale content)

Example: Using the Review Prompt

{
  "method": "prompts/get",
  "params": {
    "name": "review",
    "arguments": {
      "project": "main",
      "days_stale": 90
    }
  }
}

Configuration

Project Management

# List all projects
uv run librarian project list

# Add a new project
uv run librarian project add work ~/work/knowledge-base --default

# Set custom database location
uv run librarian project add shared ~/team/kb \
  --database-url sqlite:////var/data/shared-kb.db

# Remove a project (files are not deleted)
uv run librarian project remove old-project

# Get/set default project
uv run librarian project default           # Show current default
uv run librarian project default main      # Set 'main' as default

Configuration Files

Located at ~/.config/librarian/ (or ~/Library/Application Support/librarian/ on macOS):

config.toml:

default_project_mode = false

projects.toml:

default_project = "main"

[[projects]]
name = "main"
path = "~/Documents/notes"
# database_url defaults to {path}/.librarian/index.db

[[projects]]
name = "work"
path = "~/work/knowledge-base"
database_url = "sqlite:////var/data/work-kb.db"

Project-Level Database

Each project stores its index in {project_path}/.librarian/index.db by default. Add this to your .gitignore:

.librarian/

The database is regenerated from markdown files, so it doesn't need to be version controlled.

Development

Setup

# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=librarian --cov-report=term-missing

# Type checking
uv run basedpyright

# Linting and formatting
uv run ruff check src tests
uv run ruff format src tests

# Run pre-commit hooks on all files
uv run pre-commit run --all-files

Running Tests

The project has 701+ tests covering:

Domain models (Note, Observation, Relation)
Database operations (CRUD, indexing, FTS5)
Search and graph traversal
MCP tools, resources, and prompts
File watching and synchronization
Error handling and edge cases

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_models.py

# Run with verbose output
uv run pytest -v

# Run with coverage
uv run pytest --cov=librarian --cov-report=html
open htmlcov/index.html

Project Structure

librarian/
├── src/librarian/
│   ├── models/              # Domain models (Note, Observation, Relation)
│   ├── database/            # SQLAlchemy ORM and repository
│   ├── indexer/             # File-to-database synchronization
│   ├── search/              # Full-text search and graph traversal
│   ├── project/             # Project and note lifecycle management
│   ├── mcp/                 # MCP interface layer
│   │   ├── tools/           # Tool implementations
│   │   ├── resources.py     # Resource handlers
│   │   └── prompts/         # Prompt implementations
│   ├── watcher.py           # File system monitoring
│   ├── server.py            # FastMCP server setup
│   └── cli.py               # Command-line interface
├── tests/                   # Comprehensive test suite
├── CLAUDE.md                # Development instructions
├── librarian-spec.md        # Complete specification
└── PLAN.md                  # Implementation plan

Architecture

Librarian follows a layered architecture with dependency injection:

Domain Layer: Pure Python models (Note, Observation, Relation) that own their markdown syntax
Database Layer: Repository pattern with SQLAlchemy ORM and FTS5 integration
Indexer Layer: Bridges markdown files and database
Project Layer: Coordinates note lifecycle and cross-note operations
Search Layer: Graph traversal and semantic search
MCP Layer: Thin wrappers exposing domain layer via MCP protocol

This design enables:

Testability: All layers use dependency injection
Separation of Concerns: Each layer has a single responsibility
Maintainability: Clear boundaries between components

Troubleshooting

Server won't start

# Check if port is already in use (HTTP transport)
lsof -i :4242

# Verify project configuration
uv run librarian project list

# Check logs
uv run librarian mcp --log /tmp/librarian.log --loglevel DEBUG
tail -f /tmp/librarian.log

Notes not indexing

# Verify file permissions
ls -la ~/Documents/notes

# Check database exists
ls -la ~/Documents/notes/.librarian/

# Force re-index (delete database and restart server)
rm -rf ~/Documents/notes/.librarian/
uv run librarian mcp

Search not finding notes

Ensure notes have been indexed (check .librarian/index.db exists)
Verify FTS5 is enabled in your SQLite build: sqlite3 :memory: "pragma compile_options;"
Check that your search terms match note content, titles, or tags

Contributing

Contributions are welcome! Please:

Read CLAUDE.md for development guidelines
Follow the existing code style (enforced by pre-commit hooks)
Add tests for new features
Update documentation as needed
Run the full test suite before submitting PRs

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

FastMCP - MCP server framework
SQLAlchemy - Database ORM
Click - CLI framework
Loguru - Logging
Watchfiles - File system monitoring

Requires Python: >=3.12

Details

PyPI

2026-02-07 21:08:07 +00:00

Adam Knight

307 KiB

Assets (2)

librarian_mcp-1.0.0-py3-none-any.whl 106 KiB

librarian_mcp-1.0.0.tar.gz 201 KiB

Versions (3) View all

1.0.0b4

2026-02-15

1.0.0

2026-02-07

1.0.0b2

2026-02-07

librarian-mcp (1.0.0)

Installation

About this package

Librarian MCP Server

Features

Quick Start

Installation

Development Setup

Initialize Your First Project

Start the MCP Server

Configure Your MCP Client

Claude Desktop

Usage

Creating Notes with Semantic Annotations

Observations

Relations

Using MCP Tools

Available Tools

Example: Creating a Note

Using MCP Resources

Example: Reading a Note Section

Using MCP Prompts

Example: Using the Review Prompt

Configuration

Project Management

Configuration Files

Project-Level Database

Development

Setup

Running Tests

Project Structure

Architecture

Troubleshooting

Server won't start

Notes not indexing

Search not finding notes

Contributing

License

Links

Acknowledgments

Requirements