pocket-agent-mcp 0.1.2
MCP based Pocket Agent in vector db ( chroma) as storage
Requires Python: >=3.11

# Pocket Assistant MCP Server

A Model Context Protocol (MCP) server that provides pocket assistance capabilities with ChromaDB vector storage. This server enables AI assistants to save, retrieve, and manage research content efficiently using vector embeddings.

## Features

- **Vector Storage**: Uses ChromaDB for efficient storage and retrieval
- **Topic Organization**: Organize research content by topics
- **Deduplication**: Automatic content deduplication using hashing
- **Semantic Search**: Query research content using natural language
- **Multiple Topics**: Manage multiple research topics simultaneously
- **OpenAI Embeddings**: Uses OpenAI's text-embedding-3-small model

## Installation

### Using uvx (Recommended)

```bash
uvx pocket-agent-mcp
```

### Using uv

```bash
uv pip install pocket-agent-mcp
```

### Using pip

```bash
pip install pocket-agent-mcp
```

### From Source

```bash
git clone https://github.com/VikashS/pocket_agent_mcp.git
cd pocket-agent-mcp
uv pip install -e .
```

## Configuration

### Environment Variables

Required:
- `OPENAI_API_KEY` - Your OpenAI API key for embeddings
- `RESEARCH_DB_PATH` - Base path for storing research databases
  - A `pocket_chroma_dbs` directory will be created inside this path
  - Example: `/path/to/data` (will create `/path/to/data/pocket_chroma_dbs`)
  - Example: `~/.pocket-agent-mcp` (will create `~/.pocket-agent-mcp/pocket_chroma_dbs`)

Create a `.env` file with your configuration:

```bash
OPENAI_API_KEY=your-api-key-here
RESEARCH_DB_PATH=/path/to/data
```

### Claude Desktop Configuration

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "research-assistant": {
      "command": "uvx",
      "args": ["pocket-agent-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "POCKET_DB_PATH": "/path/to/data"
      }
    }
  }
}
```

Note: Both `OPENAI_API_KEY` and `POCKET_DB_PATH` are required. The database will be stored in `POCKET_DB_PATH/pocket_chroma_dbs/`.

## Available Tools

### 1. save_research_data

Save research content to vector database for future retrieval.

**Parameters:**
- `content` (List[str]): List of text content to save
- `topic` (str): Topic name for organizing the data (creates separate DB)

**Example:**
```
Save these research findings about AI to the "artificial-intelligence" topic
```

### 2. query_research_data

Query saved research content using natural language.

**Parameters:**
- `query` (str): Natural language query
- `topic` (str): Topic to search in (default: "default")
- `k` (int): Number of results to return (default: 5)

**Example:**
```
Query the "artificial-intelligence" topic for information about transformers
```

### 3. list_topics

List all available research topics and their document counts.

**Example:**
```
List all available research topics
```

### 4. delete_topic

Delete a research topic and all its associated data.

**Parameters:**
- `topic` (str): Topic name to delete

**Example:**
```
Delete the "old-research" topic
```

### 5. get_topic_info

Get detailed information about a specific topic.

**Parameters:**
- `topic` (str): Topic name

**Example:**
```
Get information about the "artificial-intelligence" topic
```

## Usage Examples

Once configured with Claude Desktop or another MCP client, you can:

- "Save this article about machine learning to my 'ml-research' topic"
- "Query my 'ml-research' for information about neural networks"
- "List all my research topics"
- "Get information about the 'quantum-computing' topic"
- "Delete the 'old-notes' topic"

## Technical Details

- **Protocol**: Model Context Protocol (MCP)
- **Transport**: stdio
- **Vector Database**: ChromaDB
- **Embeddings**: OpenAI text-embedding-3-small
- **Storage**: Local filesystem at `POCKET_DB_PATH/pocket_chroma_dbs/`

## Requirements

- Python 3.11 or higher
- OpenAI API key
- Dependencies: chromadb, langchain, fastmcp, openai

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/VikashS/pocket_agent_mcp.git
cd pocket_agent_mcp

# Install with development dependencies
uv pip install -e .
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Author

**Vikash Singh**
- Email: vikash.singh@linuxmail.org
- GitHub: https://github.com/vikashs

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Uses [ChromaDB](https://www.trychroma.com/) for vector storage
- Powered by [LangChain](https://www.langchain.com/)
- Implements the [Model Context Protocol](https://modelcontextprotocol.io)