Capture API

A personal capture API designed for saving quick notes, links, and thoughts from Apple Shortcuts. Built with Bun, Hono, and SQLite for persistence.

Overview

This API serves as a personal inbox for capturing anything from my iPhone via Apple Shortcuts. It provides:

1. REST API - Simple endpoints for saving and retrieving captures
2. API Key Auth - Bearer token authentication for security
3. SQLite Storage - Persistent local database
4. MCP Server - Access captures from Claude via MCP protocol

Features

Core Capture API

1. Create Capture - POST /api/captures

   • Accept text content, optional title, optional URL
   • Auto-generate timestamp
   • Support tags (comma-separated)
   • Return created capture with ID

2. List Captures - GET /api/captures

   • Return all captures, newest first
   • Support ?limit=N query param
   • Support ?tag=tagname filtering
   • Support ?search=term full-text search

3. Get Single Capture - GET /api/captures/:id

   • Return single capture by ID
   • 404 if not found

4. Delete Capture - DELETE /api/captures/:id

   • Soft delete (mark as deleted)
   • 404 if not found

Authentication

1. API Key Setup

   • Generate API key on first run (save to .env)
   • Read from CAPTURE_API_KEY env var
   • Require Authorization: Bearer <key> header

2. Auth Middleware

   • Validate bearer token on all /api/* routes
   • Return 401 for missing/invalid token
   • Skip auth for health check endpoint

Health & Status

1. Health Check - GET /health

   • No auth required
   • Return { status: "ok", timestamp: "..." }

2. Stats Endpoint - GET /api/stats

   • Total capture count
   • Captures this week
   • Top tags

MCP Server

1. List Captures Tool

   • list_captures - Get recent captures
   • Parameters: limit (optional), tag (optional)

2. Search Captures Tool

   • search_captures - Full-text search
   • Parameters: query (required)

3. Create Capture Tool

   • create_capture - Add new capture
   • Parameters: content (required), title, url, tags

Tech Stack

• Runtime: Bun
• Framework: Hono (lightweight web framework)
• Database: SQLite via bun:sqlite
• Auth: Bearer token (API key)
• MCP: @modelcontextprotocol/sdk

Database Schema

CREATE TABLE captures (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  title TEXT,
  url TEXT,
  tags TEXT,  -- JSON array
  created_at TEXT NOT NULL,
  deleted_at TEXT
);

CREATE INDEX idx_captures_created ON captures(created_at DESC);
CREATE INDEX idx_captures_deleted ON captures(deleted_at);

API Examples

Create a capture (from Apple Shortcuts)

curl -X POST http://localhost:3000/api/captures \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Interesting article about AI agents",
    "url": "https://example.com/article",
    "tags": ["reading", "ai"]
  }'

List recent captures

curl http://localhost:3000/api/captures?limit=10 \
  -H "Authorization: Bearer $API_KEY"

Search captures

curl http://localhost:3000/api/captures?search=ai \
  -H "Authorization: Bearer $API_KEY"

Project Structure

capture-api/
├── src/
│   ├── index.ts          # Main entry, server setup
│   ├── routes/
│   │   ├── captures.ts   # Capture CRUD routes
│   │   └── health.ts     # Health check route
│   ├── middleware/
│   │   └── auth.ts       # API key validation
│   ├── db/
│   │   ├── schema.ts     # Database initialization
│   │   └── queries.ts    # Database operations
│   └── mcp/
│       └── server.ts     # MCP server implementation
├── tests/
│   ├── captures.test.ts  # API tests
│   └── auth.test.ts      # Auth tests
├── package.json
├── tsconfig.json
└── README.md

Running

# Development
bun run dev

# Production
bun run src/index.ts

# Run MCP server
bun run src/mcp/server.ts

Environment Variables

CAPTURE_API_KEY=<generated-on-first-run>
CAPTURE_DB_PATH=./captures.db
PORT=3000