Metadata-Version: 2.4
Name: kavi-research-assistant-mcp
Version: 0.1.1
Summary: A Model Context Protocol server for research assistance with ChromaDB vector storage by kavi.ai
Project-URL: Homepage, https://github.com/machhakiran/kavi-research-assistant-mcp
Project-URL: Repository, https://github.com/machhakiran/kavi-research-assistant-mcp
Project-URL: Issues, https://github.com/machhakiran/kavi-research-assistant-mcp
Author-email: Laxmi Kant Tiwari <info@kgptalkie.com>
License-File: LICENSE
Keywords: ai,chromadb,kavi.ai,langchain,mcp,research,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: chromadb>=1.1.0
Requires-Dist: fastapi>=0.116.1
Requires-Dist: fastmcp>=2.12.3
Requires-Dist: langchain-chroma>=0.2.6
Requires-Dist: langchain-community>=0.3.29
Requires-Dist: langchain-mcp-adapters>=0.1.9
Requires-Dist: langchain-ollama>=0.3.8
Requires-Dist: langchain-openai>=0.3.33
Requires-Dist: langchain>=0.3.27
Requires-Dist: langgraph>=0.6.7
Requires-Dist: matplotlib>=3.10.6
Requires-Dist: mcp-use[search]>=1.3.10
Requires-Dist: mcp[cli]>=1.14.0
Requires-Dist: numpy>=2.3.3
Requires-Dist: openai>=1.108.1
Requires-Dist: pandas>=2.3.2
Requires-Dist: pypdf2>=3.0.1
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: requests>=2.32.5
Requires-Dist: scipy>=1.16.2
Description-Content-Type: text/markdown

# Kavi Research Assistant MCP Server

A Model Context Protocol (MCP) server that provides research assistance capabilities with ChromaDB vector storage by **kavi.ai**. 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 kavi-research-assistant-mcp
```

### Using uv

```bash
uv pip install kavi-research-assistant-mcp
```

### Using pip

```bash
pip install kavi-research-assistant-mcp
```

### From Source

```bash
git clone https://github.com/machhakiran/kavi-research-assistant-mcp.git
cd kavi-research-assistant-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 `research_chroma_dbs` directory will be created inside this path
  - Example: `/path/to/data` (will create `/path/to/data/research_chroma_dbs`)
  - Example: `~/.research_assistant_mcp` (will create `~/.research_assistant_mcp/research_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": {
    "kavi-research-assistant": {
      "command": "uvx",
      "args": ["kavi-research-assistant-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "RESEARCH_DB_PATH": "/path/to/data"
      }
    }
  }
}
```

Note: Both `OPENAI_API_KEY` and `RESEARCH_DB_PATH` are required. The database will be stored in `RESEARCH_DB_PATH/research_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 `RESEARCH_DB_PATH/research_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/machhakiran/kavi-research-assistant-mcp.git
cd kavi-research-assistant-mcp

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

## Trademarks

**kavi.ai** and related logos are trademarks of **kavi.ai**.

## License

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

## Author

**Laxmi Kant Tiwari**
- Email: info@kgptalkie.com
- GitHub: https://github.com/machhakiran

## 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)
