A temporary inbox for raw information before it's processed into an Obsidian vault.

This service is a buffer between raw sources (email, API, messages, etc) and a personal knowledge management system.

Think of it like a to-do list for information you want to process into a

Instead of directly processing incoming content into notes, this inbox:

1. Receives raw information from multiple sources (email, API calls)
2. Stores unprocessed items temporarily with their attachments
3. Provides a simple API for clients to retrieve and process items
4. Manages the lifecycle: unprocessed → processed → auto-deleted after 30 days

This separation allows for flexible processing workflows using different clients (Claude Desktop via MCP, custom scripts, etc.).

See CLAUDE.md for AI assistant guidelines and PROJECT.md for detailed architecture.

1. Remix on Val.town

2. Run one-time setup

   Run the one-time setup script to create the database table in your val.town sqlite.

3. Configure Environment Variables

   In Val.town, set these secrets:

   • INBOX_API_TOKEN - Create a secure random token for API auth (via e.g. openssl rand -hex 32)
   • INCOMING_EMAIL_ALLOWLIST - Comma-separated email addresses allowed to send records to the inbox (e.g. name@gmail.com,name@work.org)

4. Set up MCP Server (for Claude Desktop integration)

   Create ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "inbox": {
         "command": "deno",
         "args": [
           "run",
           "--allow-net",
           "--allow-env",
           "/path/to/inbox/localMcpServer.ts"
         ],
         "env": {
           "INBOX_API_URL": "https://your-username-httphandler.web.val.run",
           "INBOX_API_TOKEN": "your-api-token"
         }
       }
     }
   }

   Alternatively, use the published val URL:

   "command": "deno",
   "args": [
     "run",
     "--allow-net",
     "--allow-env",
     "https://esm.town/v/your-username/inbox/localMcpServer.ts"
   ]

• SQLite database via standard library
• Blob storage for binary attachments
• Email sending/receiving built-in
• HTTP endpoints for API access
• Cron scheduling for cleanup tasks

obsidian-inbox/
├── server/            # Core http server logic
├── mcp/               # Model Context Protocol server
├── emailHandler.ts    # Val.town email trigger
├── httpHandler.ts     # Val.town HTTP endpoint
├── cleanupCron.ts     # Val.town cron job
├── localMcpServer.ts  # Entry point for local MCP
└── apiClient.ts       # HTTP client (used by MCP)

Via Email: Send email to your Val.town email address from an allowlisted sender. The email body and attachments are automatically saved.

Via HTTP API:

curl -X POST https://your-val.web.val.run/api/record \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "raw": "Content to process later",
    "subject": "Meeting notes",
    "from": "manual-entry",
    "date": "2025-10-21T10:00:00Z",
    "attachmentBlobIds": []
  }'

With Claude Desktop (MCP): In Claude Desktop, ask:

• "What's in my inbox?"
• "Download the attachments from inbox item XYZ"
• "Mark inbox item ABC as processed"

With Custom Scripts:

# Get unprocessed items
curl https://your-val.web.val.run/api/inbox \
  -H "Authorization: Bearer YOUR_TOKEN"

# Mark item as processed
curl -X PATCH https://your-val.web.val.run/api/record/{id}/processed \
  -H "Authorization: Bearer YOUR_TOKEN"

All endpoints require Authorization: Bearer YOUR_TOKEN header.

Schema Changes:

1. Update inboxRecordSchema in server/InboxService.ts
2. Increment table name in server/db.ts (e.g., inbox_records_2)
3. Redeploy vals to Val.town

Adding Endpoints:

1. Add route in server/app.ts
2. Add auth middleware if needed
3. Update this README

Adding MCP Tools:

1. Create tool file in mcp/tools/
2. Register in mcp/tools/index.ts
3. Test with Claude Desktop

1. Simple buffer - Not a full app, just a temporary holding area
2. Client-side processing - Complex logic lives in clients, not here
3. Stateless - Each record is independent
4. Val.town native - Leverage platform features over external services
5. Fail-fast - Let errors bubble with context

1. Send email with notes/attachments to Val.town address
2. Email handler saves to inbox
3. Ask Claude Desktop: "What's in my inbox?"
4. Claude reads items, processes into Obsidian vault
5. Claude marks items as processed
6. Auto-deleted after 30 days

1. POST content via HTTP API
2. Poll /api/inbox endpoint
3. Process items with your script
4. PATCH to mark processed
5. Auto-deleted after 30 days

Go nuts