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.