# Pocketbase MCP Server

MCP (Model Context Protocol) server for Pocketbase - enables AI assistants to interact with Pocketbase backend through a clean, type-safe API.

## Features

- 🔐 **Silent Authentication** - Automatic authentication with retry logic
- 📦 **Full CRUD Operations** - Complete record management
- 🔍 **Advanced Querying** - Filtering, sorting, pagination, field selection
- 📊 **Collections Management** - List and inspect collections
- 📝 **Logs Access** - Query system logs with filters
- 🛡️ **Type Safety** - Full TypeScript support with Zod validation
- 🏗️ **Clean Architecture** - Layered design for easy maintenance

## Installation

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build
```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
POCKETBASE_URL=https://your-pocketbase-instance.com
POCKETBASE_IDENTITY=your-email@example.com
POCKETBASE_PASSWORD=your-password
```

### MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "https://your-pocketbase-instance.com",
        "POCKETBASE_IDENTITY": "your-email@example.com",
        "POCKETBASE_PASSWORD": "your-password"
      }
    }
  }
}
```

## Available Tools

### 1. `pocketbase_auth` (Optional)
Authenticate with Pocketbase. **Note**: Authentication is handled automatically for other tools.

```typescript
pocketbase_auth({
  pocketbaseUrl?: string,
  identity?: string,
  password?: string
})
```

### 2. `pocketbase_list_collections`
List all collections from Pocketbase.

```typescript
pocketbase_list_collections({
  page?: number,        // default: 1
  perPage?: number,     // default: 500
  skipTotal?: number    // default: 1
})
```

### 3. `pocketbase_list_records`
List records from a collection with filtering and pagination.

```typescript
pocketbase_list_records({
  collection: string,   // required
  page?: number,
  perPage?: number,     // default: 30, max: 500
  sort?: string,        // e.g., "-created,name"
  filter?: string,      // e.g., 'status="active"'
  expand?: string,      // e.g., "user,category"
  fields?: string,      // e.g., "id,name,email"
  skipTotal?: number
})
```

### 4. `pocketbase_get_record`
Get a single record by ID.

```typescript
pocketbase_get_record({
  collection: string,   // required
  id: string,          // required
  expand?: string,
  fields?: string
})
```

### 5. `pocketbase_create_record`
Create a new record in a collection.

```typescript
pocketbase_create_record({
  collection: string,   // required
  data: object,        // required - record data
  expand?: string,
  fields?: string
})
```

### 6. `pocketbase_update_record`
Update an existing record.

```typescript
pocketbase_update_record({
  collection: string,   // required
  id: string,          // required
  data: object,        // required - fields to update
  expand?: string,
  fields?: string
})
```

### 7. `pocketbase_delete_record`
Delete a record from a collection.

```typescript
pocketbase_delete_record({
  collection: string,   // required
  id: string           // required
})
```

### 8. `pocketbase_list_logs`
Query system logs with filtering and pagination.

```typescript
pocketbase_list_logs({
  page?: number,
  perPage?: number,     // default: 50, max: 500
  sort?: string,
  filter?: string,      // e.g., '(message ~ "error")'
  skipTotal?: number    // default: 1
})
```

## Architecture

The project follows a clean, layered architecture:

```
src/
├── index.ts              # MCP server entry point
├── config/               # Environment configuration
├── types/                # TypeScript type definitions
├── schemas/              # Zod validation schemas
├── utils/                # Error handling & response formatting
├── client/               # HTTP client & authentication manager
├── repositories/         # Data access layer
├── services/             # Business logic layer
├── handlers/             # MCP request handlers
└── tools/                # Tool definitions registry
```

### Design Patterns

- **Repository Pattern**: Separates data access from business logic
- **Service Pattern**: Encapsulates business logic
- **Singleton Pattern**: For HTTP client and auth manager
- **Template Method**: Base classes for common functionality
- **Dependency Injection**: Services injected into handlers

## Development

```bash
# Run in development mode
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start
```

## License

ISC