# Bear Notes MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Bear Notes](https://bear.app) that provides semantic search, AI summarization, and note relationship discovery capabilities.

## 🐻 What is this?

This MCP server allows AI assistants and other MCP clients to interact with your Bear Notes database, providing:

- **📖 Note Access**: Read individual notes and browse your entire collection
- **🔍 Search & Discovery**: Find notes by content with intelligent search
- **🔗 Relationship Analysis**: Discover related notes and topics (planned)
- **🤖 AI Integration**: Summarize and analyze notes with local AI models (planned)
- **⚡ Real-time Updates**: Automatically refresh when notes change

## 🏗️ Architecture

The server is built with a modular architecture:

- **Configuration System**: YAML-based config with environment overrides
- **Database Interface**: Read-only access to Bear's SQLite database
- **MCP Protocol**: Full implementation with resources and tools
- **Monitoring**: Real-time database change detection
- **Extensible Design**: Ready for semantic analysis and AI features

## 🚀 Installation

### Prerequisites

- **Python 3.11+** 
- **[uv](https://docs.astral.sh/uv/)** (recommended package manager)
- **Bear Notes 2.x** (installed on macOS)
- **Bear Database Access**: Ensure Bear has been launched at least once

### Install with uv (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd bear-mcp-python

# Install with uv (creates virtual environment automatically)
uv sync

# Install with development dependencies
uv sync --extra dev
```

### Alternative: Install with pip

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"
```

## ⚙️ Configuration

The server will auto-detect your Bear database, but you can customize settings:

```bash
# Create default configuration
uv run bear-mcp-cli create-config --output config/config.yaml

# Edit configuration as needed
# Key settings:
# - bear_db.path: Path to Bear database (auto-detected if null)
# - logging.level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)
# - mcp_server.max_resources: Limit on resources returned
```

### Environment Variables

Override any configuration with environment variables using the `BEAR_MCP_` prefix:

```bash
export BEAR_MCP_LOGGING_LEVEL=DEBUG
export BEAR_MCP_BEAR_DB_PATH="/path/to/custom/database.sqlite"
export BEAR_MCP_MCP_SERVER_MAX_RESOURCES=500
```

## 🧪 Testing & Development

### CLI Tools

The project includes CLI tools for testing and development:

#### Find Bear Database

```bash
# Locate Bear database files on your system
uv run bear-mcp-cli find-db
```

#### Test Database Connection

```bash
# Test connection to Bear database and show statistics
uv run bear-mcp-cli test-db
```

#### List Notes

```bash
# List recent notes (default: 10 notes)
uv run bear-mcp-cli list-notes

# List more notes with options
uv run bear-mcp-cli list-notes --limit 25

# Include trashed and archived notes
uv run bear-mcp-cli list-notes --include-trashed --include-archived --limit 50
```

#### Create Configuration

```bash
# Create default configuration file
uv run bear-mcp-cli create-config

# Create in custom location
uv run bear-mcp-cli create-config --output ~/.bear-mcp/config.yaml

# Force overwrite existing file
uv run bear-mcp-cli create-config --force
```

### Verify Installation

```bash
# 1. Check if Bear database can be found
uv run bear-mcp-cli find-db

# 2. Test database connection
uv run bear-mcp-cli test-db

# 3. List a few notes to verify data access
uv run bear-mcp-cli list-notes --limit 5
```

Expected output for a working setup:
```
INFO     Found database                         path=/Users/.../database.sqlite
INFO     Database connection successful
INFO     Database stats                         total_notes=150 active_notes=145 ...
```

## 🔌 MCP Server Usage

### With MCP Clients

Start the MCP server for use with MCP clients:

```bash
# Run the MCP server (stdio mode)
uv run bear-mcp
```

The server provides these MCP resources:

- `notes://all` - JSON list of all active notes with metadata
- `note:///{note_id}` - Individual note content in Markdown format

And these MCP tools:

- `get_note` - Retrieve full content of a specific note
- `search_notes` - Search notes by title and content  
- `list_notes` - List notes with filtering options
- `get_database_stats` - Get database statistics

### Integration Examples

#### Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "bear-notes": {
      "command": "uv",
      "args": ["run", "bear-mcp"],
      "cwd": "/path/to/bear-mcp-python",
      "env": {
        "BEAR_MCP_LOGGING_LEVEL": "INFO"
      }
    }
  }
}
```

#### Other MCP Clients

The server implements the standard MCP protocol over stdio, so it should work with any MCP-compatible client.

## 📁 Project Structure

```
bear_mcp/
├── config/          # Configuration management
├── bear_db/         # Bear database interface
├── mcp_server/      # MCP protocol implementation  
├── semantic/        # Semantic analysis (Phase 2)
├── ai/              # AI integration (Phase 3)
├── main.py          # Server entry point
├── cli.py           # CLI utilities
└── utils.py         # Utility functions

config/
└── config.yaml      # Default configuration

tests/               # Test suite (Phase 5)
```

## 🐛 Troubleshooting

### Bear Database Not Found

```bash
# Check if Bear is installed and has been run
uv run bear-mcp-cli find-db

# If no database found:
# 1. Launch Bear.app at least once
# 2. Create a test note
# 3. Try finding the database again
```

### Permission Issues

```bash
# Bear database is read-only by design
# If you get permission errors:
# 1. Make sure Bear.app is not running
# 2. Check file permissions on the database
# 3. Try running with different user permissions
```

### Connection Timeouts

```bash
# If database connections timeout:
# 1. Check if Bear is actively syncing
# 2. Increase timeout in configuration:
export BEAR_MCP_BEAR_DB_TIMEOUT=60.0
```

### No Notes Returned

```bash
# If no notes are returned:
# 1. Check that notes exist in Bear
# 2. Verify notes are not all trashed/archived
uv run bear-mcp-cli list-notes --include-trashed --include-archived
```

### uv Installation Issues

```bash
# If uv is not installed, install it first:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip:
pip install uv

# Then run uv sync to set up the project
uv sync
```

## 🗺️ Development Roadmap

### ✅ Phase 1: Foundation (Complete)
- Project setup and configuration
- Bear database interface
- Basic MCP server with resources and tools
- Database monitoring and caching

### 🔄 Phase 2: Semantic Analysis (Planned)
- Sentence transformer embeddings
- ChromaDB vector storage
- Semantic similarity search
- Related notes discovery

### 🤖 Phase 3: AI Integration (Planned) 
- Ollama integration for local AI
- Note summarization
- Content analysis and insights
- Intelligent tagging

### ⚡ Phase 4: Advanced Features (Planned)
- Enhanced MCP tools
- Performance optimization
- Caching improvements
- Advanced search capabilities

### 🧪 Phase 5: Testing & Polish (Planned)
- Comprehensive test suite
- Documentation and guides
- Deployment tools
- Performance benchmarks

## 🤝 Contributing

This project is in active development. Current focus is on Phase 2 implementation.

### Development Setup with uv

```bash
# Install with development dependencies
uv sync --extra dev

# Run code formatting
uv run black bear_mcp/
uv run ruff check bear_mcp/

# Run type checking  
uv run mypy bear_mcp/

# Run tests (when available)
uv run pytest
```

### Development Setup with pip

```bash
# Install with development dependencies
pip install -e ".[dev]"

# Run code formatting
black bear_mcp/
ruff check bear_mcp/

# Run type checking  
mypy bear_mcp/

# Run tests (when available)
pytest
```

## 📄 License

[Add your license here]

## 🙏 Acknowledgments

- [Bear Notes](https://bear.app) - The excellent note-taking app this server connects to
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that makes this integration possible
- [Anthropic](https://anthropic.com/) - For Claude and MCP development
- [uv](https://docs.astral.sh/uv/) - Fast Python package manager

---

**Note**: This server provides read-only access to your Bear Notes database. It never modifies your notes or database.