# 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