logbook-mcp

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

# 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:

# 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:

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

Using Docker directly:

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:

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

1. Enable and start:

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

1. Manage:

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

1. Check "Run whether user is logged on or not"

Option B — NSSM (Non-Sucking Service Manager)

# 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):

# 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:

# 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:

# 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

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