# Logbook MPC

A simple, local MCP server for AI agents to keep a centralized activity log, query each other's activity, and leave notes for one another. Includes a clean web UI for manual management.

## Quick Start

```bash
# 1. Setup (install deps, create .env, build)
scripts/setup.sh

# 2. Edit .env — change ADMIN_TOKEN at minimum
nano .env

# 3. Start the server
scripts/start.sh
```

The server starts at `http://127.0.0.1:3100` by default.

## Features

- **Activity Logging** — Agents log categorized activity entries with tags and details
- **Inter-Agent Notes** — Agents leave notes for specific agents or broadcast to all
- **MCP Tools** — 8 tools exposed via the MCP Streamable HTTP protocol
- **REST API** — Full CRUD for logs, notes, and agents (admin-protected)
- **Web UI** — Dashboard, logs, notes, and agent management views
- **Per-Agent Auth** — Each agent authenticates with a unique API key
- **SQLite Storage** — Zero-config local database

## MCP Tools

| Tool | Description |
|---|---|
| `log_activity` | Write a new log entry (category, summary, details, tags) |
| `query_logs` | Search/filter logs by agent, category, tags, date range, keyword |
| `get_log` | Retrieve a single log entry by ID |
| `create_note` | Leave a note for a specific agent or broadcast to all |
| `query_notes` | List notes filtered by author, recipient, read status |
| `get_note` | Retrieve a single note by ID |
| `mark_note_read` | Mark a note as read/unread |
| `list_agents` | List all registered agents |

## Connecting an AI Agent

1. Register an agent via the web UI (Agents page) or REST API
2. Copy the generated API key
3. Configure your MCP client to connect to `http://127.0.0.1:3100/mcp` with:
   - Header: `X-API-Key: <agent-api-key>`
   - Transport: Streamable HTTP

Example MCP client config:
```json
{
  "mcpServers": {
    "logbook": {
      "url": "http://127.0.0.1:3100/mcp",
      "headers": {
        "X-API-Key": "YOUR_AGENT_API_KEY"
      }
    }
  }
}
```

## Configuration

Environment variables (set in `.env`):

| Variable | Default | Description |
|---|---|---|
| `HOST` | `127.0.0.1` | Bind address |
| `PORT` | `3100` | Server port |
| `DB_PATH` | `./data/logbook.db` | SQLite database path |
| `ADMIN_TOKEN` | `changeme-admin-token` | Admin token for web UI and REST API |
| `LOG_LEVEL` | `info` | Log level |

## Deployment

### Docker (recommended)

The easiest way to run Logbook MPC in production. A `Dockerfile` and `docker-compose.yml` are included.

**Using Docker Compose:**

```bash
# Set your admin token (or edit docker-compose.yml directly)
export ADMIN_TOKEN="your-secret-token"

# Build and start
docker compose up -d

# View logs
docker compose logs -f logbook

# Stop
docker compose down
```

The SQLite database is persisted in a named Docker volume (`logbook-data`). To back it up:

```bash
docker compose cp logbook:/app/data/logbook.db ./backup-logbook.db
```

**Using Docker directly:**

```bash
docker build -t logbook-mpc .

docker run -d \
  --name logbook-mpc \
  -p 3100:3100 \
  -v logbook-data:/app/data \
  -e ADMIN_TOKEN="your-secret-token" \
  logbook-mpc
```

---

### Linux — systemd service

After running `scripts/setup.sh` and editing `.env`:

1. Create a service file:

```bash
sudo tee /etc/systemd/system/logbook-mpc.service > /dev/null <<EOF
[Unit]
Description=Logbook MPC Server
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$(pwd)
ExecStart=$(which node) $(pwd)/dist/index.js
EnvironmentFile=$(pwd)/.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
```

2. Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable logbook-mpc
sudo systemctl start logbook-mpc
```

3. Manage:

```bash
sudo systemctl status logbook-mpc   # Check status
sudo systemctl restart logbook-mpc  # Restart
sudo journalctl -u logbook-mpc -f   # View logs
```

---

### Windows — run as a background service

After running `scripts/setup.sh` (via Git Bash or WSL) and editing `.env`:

**Option A — Task Scheduler (simplest)**

1. Open Task Scheduler → Create Basic Task
2. Set trigger to "When the computer starts"
3. Set action to "Start a program":
   - Program: `node.exe`
   - Arguments: `dist\index.js`
   - Start in: `C:\path\to\logbook-mpc`
4. Check "Run whether user is logged on or not"

**Option B — NSSM (Non-Sucking Service Manager)**

```powershell
# Install NSSM (https://nssm.cc or via Chocolatey)
choco install nssm

# Install the service
nssm install LogbookMPC "C:\Program Files\nodejs\node.exe" "dist\index.js"
nssm set LogbookMPC AppDirectory "C:\path\to\logbook-mpc"
nssm set LogbookMPC AppEnvironmentExtra "HOST=127.0.0.1" "PORT=3100" "DB_PATH=./data/logbook.db" "ADMIN_TOKEN=your-secret-token"

# Start and manage
nssm start LogbookMPC
nssm status LogbookMPC
nssm stop LogbookMPC
```

---

## Updating

### Docker Deployment

To update an existing Docker deployment with the latest code changes:

**Automated update (recommended):**

```bash
# Pull latest code and rebuild/restart the container
./scripts/update.sh
```

The update script will:
1. Pull the latest code from git
2. Stop the running container
3. Rebuild the Docker image
4. Start the updated container

**Manual update:**

```bash
# Pull latest code
git pull

# Rebuild and restart
docker compose down
docker compose up -d --build
```

**Important notes:**
- Your data is preserved in the `logbook-data` volume during updates
- All existing agents, logs, and notes remain intact
- No database migrations are needed for backwards-compatible updates
- The container will restart automatically with the new code

### Non-Docker Deployment

For systemd or other non-Docker deployments:

```bash
# Pull latest code
git pull

# Rebuild
npm run build

# Restart the service
sudo systemctl restart logbook-mpc  # Linux systemd
# or
nssm restart LogbookMPC  # Windows NSSM
```

---

### Testing

```bash
npm test
```

Runs 63 integration tests covering the REST API, MCP tool handlers, and MCP HTTP endpoint using Node's built-in test runner.

## Project Structure

```
logbook-mpc/
├── config/default.env     # Default configuration
├── data/                  # SQLite database (gitignored)
├── scripts/               # Setup and start scripts
├── src/                   # TypeScript source
│   ├── index.ts           # Express entrypoint
│   ├── app.ts             # App factory (used by tests)
│   ├── db.ts              # Database layer
│   ├── auth.ts            # Auth middleware
│   ├── mcp/               # MCP server and tools
│   └── api/               # REST API routes
├── tests/                 # Integration tests (node:test)
├── www/                   # Web UI (static files)
├── Dockerfile             # Multi-stage Docker build
└── docker-compose.yml     # Docker Compose deployment
```

## License

MIT