Context MCP Server

A CloudFlare Workers-based Model Context Protocol (MCP) server that provides semantic memory and journal capabilities with zero-setup user experience.

Features

Zero-Setup Experience: Users get unique URLs with no local installation required
Semantic Search: BGE-Base-EN-v1.5 embeddings with vector similarity search
User Isolation: Complete data privacy with user-specific access control
Real-Time Communication: Server-Sent Events (SSE) for live MCP protocol communication
Scalable Architecture: Built on CloudFlare's serverless infrastructure

Core Tools

addMemory: Store memories with semantic search capabilities
searchMemory: Find relevant memories using semantic similarity
addJournal: Create journal entries with optional titles and tags
searchJournals: Search journal entries semantically
getRecentActivity: Get recent memories and journal entries

Architecture

CloudFlare Workers: Serverless compute for the MCP server
D1 Database: SQLite-based storage for structured data
Vectorize: Vector database for semantic search
CloudFlare AI: BGE-Base-EN-v1.5 embeddings generation
KV Store: Session management and caching

Quick Start

Prerequisites

Node.js 18+ installed
CloudFlare account with Workers, D1, and Vectorize access
Wrangler CLI installed and authenticated

npm install -g wrangler
wrangler login

Setup

Clone and Install

git clone <repository-url>
cd context-mcp
npm install

Database Setup

npm run setup

This script will:

Create D1 database and update wrangler.toml
Set up database schema with proper indexes
Create Vectorize index for embeddings
Configure KV namespace for sessions

Deploy

npm run deploy

Test the Deployment

# Health check
curl https://your-worker.workers.dev/health

# Generate a user ID
curl https://your-worker.workers.dev/generate-user

Optional: Seed Test Data

npm run seed [USER_ID]

Usage

For MCP Clients

Connect to your deployed worker using the SSE endpoint:

https://your-worker.workers.dev/{USER_ID}/sse

Example with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "context": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sse", "https://your-worker.workers.dev/{USER_ID}/sse"]
    }
  }
}

Direct HTTP API

You can also use HTTP POST requests to the MCP endpoint:

curl -X POST https://your-worker.workers.dev/{USER_ID} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "addMemory",
      "arguments": {
        "content": "Learning about MCP protocol implementation",
        "tags": ["learning", "mcp"]
      }
    }
  }'

Tool Reference

addMemory

Store a new memory with semantic search capabilities.

{
  "name": "addMemory",
  "arguments": {
    "content": "The memory content to store",
    "tags": ["optional", "tags"]
  }
}

searchMemory

Search memories using semantic similarity.

{
  "name": "searchMemory", 
  "arguments": {
    "query": "Search query text",
    "limit": 5,
    "tags": ["optional", "filter"]
  }
}

addJournal

Create a new journal entry.

{
  "name": "addJournal",
  "arguments": {
    "title": "Optional title",
    "content": "Journal entry content", 
    "tags": ["optional", "tags"]
  }
}

searchJournals

Search journal entries semantically.

{
  "name": "searchJournals",
  "arguments": {
    "query": "Search query text",
    "limit": 5,
    "tags": ["optional", "filter"] 
  }
}

getRecentActivity

Get recent memories and journal entries.

{
  "name": "getRecentActivity",
  "arguments": {
    "days": 7,
    "limit": 10
  }
}

Development

Local Development

npm run dev

This starts a local development server with hot reloading.

Database Operations

# Execute SQL file
npm run db:execute -- --file=schema.sql

# Run SQL command
npm run db:query -- "SELECT COUNT(*) FROM memories;"

# View logs
npm run logs

Type Checking

npm run build

Project Structure

context-mcp/
├── src/
│   ├── worker.ts          # Main CloudFlare Worker
│   ├── mcp-handler.ts     # MCP protocol implementation
│   ├── sse-handler.ts     # Server-Sent Events handler
│   └── types.ts           # TypeScript type definitions
├── scripts/
│   ├── setup-database.js  # Database setup automation
│   └── seed-data.js       # Test data seeding
├── schema.sql             # Database schema
├── wrangler.toml          # CloudFlare configuration
└── package.json           # Dependencies and scripts

Configuration

Environment Variables

Set in wrangler.toml under [vars]:

[vars]
NODE_ENV = "production"
# Add custom variables here

Bindings

The worker uses these CloudFlare bindings:

DB: D1 Database for structured data
VECTORIZE: Vector search index
AI: BGE embeddings generation
SESSIONS: KV namespace for sessions

Security

User Isolation: All data is scoped to user IDs
UUID Validation: Proper user ID format validation
CORS Headers: Configured for cross-origin requests
Error Handling: No sensitive data exposed in errors

Performance

Vector Search: Sub-100ms semantic similarity queries
Database Queries: Optimized with proper indexing
Connection Management: Automatic cleanup of stale SSE connections
Heartbeat: 30-second intervals to maintain connections

Monitoring

Health Check

curl https://your-worker.workers.dev/health

Connection Status

The SSE handler provides connection monitoring capabilities for debugging.

Logs

npm run logs

View real-time CloudFlare Worker logs.

Troubleshooting

Common Issues

Database not found: Run npm run setup to create database
Embedding errors: Ensure CloudFlare AI binding is configured
SSE connection issues: Check browser console for connection errors
Vector search returning no results: Verify data was added with embeddings

Debug Steps

Check health endpoint: https://your-worker.workers.dev/health
Verify user ID format (must be valid UUID)
Check CloudFlare dashboard for binding configuration
Review worker logs: npm run logs

Contributing

Fork the repository
Create a feature branch
Make changes and test thoroughly
Submit a pull request

License

MIT License - see LICENSE file for details.

Roadmap

Enhanced metadata filtering for vector search
File attachment support for journal entries
Export/import functionality
Advanced analytics and insights
Multi-language embedding support
Real-time collaboration features

Built with ❤️ using CloudFlare Workers and the Model Context Protocol.