# Context MCP
A Model Context Protocol (MCP) server that provides persistent context management for AI agents like Cursor, Claude Code, and Claude Desktop. Uses **Upstash Vector DB** for storage and **Google AI** for embeddings.
## Features
- **Add Context**: Store text with metadata, automatically embedded and indexed
- **Query Context**: Semantic search to find relevant stored information
- **Batch Operations**: Efficiently add or delete multiple contexts
- **Metadata Filtering**: Filter queries by metadata attributes
- **Statistics**: Monitor your vector database usage
## Prerequisites
1. **Upstash Vector DB** account - [Sign up at Upstash](https://upstash.com/)
- Create a new Vector Index with dimension `768` (for Google's text-embedding-004)
- Get your REST URL and Token
2. **Google AI API Key** - [Get from Google AI Studio](https://aistudio.google.com/app/apikey)
## Installation
```bash
# Clone the repository
git clone <your-repo-url>
cd context-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## Configuration
Create a `.env` file based on `.env.example`:
```bash
cp .env.example .env
```
Fill in your credentials:
```env
UPSTASH_VECTOR_REST_URL=your_upstash_vector_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_vector_token
GOOGLE_AI_API_KEY=your_google_ai_api_key
```
## Usage with AI Agents
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"context": {
"command": "node",
"args": ["path/to/context-mcp/dist/index.js"],
"env": {
"UPSTASH_VECTOR_REST_URL": "your_url",
"UPSTASH_VECTOR_REST_TOKEN": "your_token",
"GOOGLE_AI_API_KEY": "your_key"
}
}
}
}
```
### Cursor
Add to your Cursor MCP settings:
```json
{
"mcpServers": {
"context": {
"command": "node",
"args": ["path/to/context-mcp/dist/index.js"],
"env": {
"UPSTASH_VECTOR_REST_URL": "your_url",
"UPSTASH_VECTOR_REST_TOKEN": "your_token",
"GOOGLE_AI_API_KEY": "your_key"
}
}
}
}
```
### Claude Code (Windsurf)
Add to your MCP configuration file.
## Available Tools
### `add_context`
Store a single piece of context.
**Parameters:**
- `id` (required): Unique identifier
- `content` (required): Text content to store
- `metadata` (optional): Key-value pairs for filtering
### `add_contexts_batch`
Store multiple contexts efficiently.
**Parameters:**
- `contexts` (required): Array of `{id, content, metadata}` objects
### `query_context`
Search for relevant contexts.
**Parameters:**
- `query` (required): Natural language search query
- `topK` (optional): Number of results (1-20, default: 5)
- `filter` (optional): Upstash filter expression
### `delete_context`
Delete a single context by ID.
**Parameters:**
- `id` (required): ID of context to delete
### `delete_contexts_batch`
Delete multiple contexts.
**Parameters:**
- `ids` (required): Array of IDs to delete
### `get_stats`
Get database statistics (vector count, dimensions).
## Example Usage
Once connected, you can ask your AI agent to:
```
"Add this project documentation to my context with id 'project-readme'"
"Search my context for information about authentication"
"Store these meeting notes with category 'meetings' and date '2024-01-15'"
"What relevant context do I have about the payment system?"
```
## Upstash Filter Syntax
When querying, you can filter by metadata:
```
# Exact match
category = 'meetings'
# Numeric comparison
priority > 5
# Multiple conditions
category = 'docs' AND priority >= 3
```
## Development
```bash
# Run in development mode
npm run dev
# Build for production
npm run build
# Start production server
npm start
```
## License
MIT
