# MyAIGist MCP Server
MCP server providing document intelligence and knowledge management for Claude Desktop and other MCP-compatible clients. Process documents, answer questions with RAG, and maintain a persistent knowledge base - all running locally.
## Overview
**MyAIGist MCP** provides 10 powerful tools for document intelligence and knowledge management:
- **Document Processing**: PDF, DOCX, TXT, URLs, file attachments, and batch processing
- **Q&A System**: RAG-powered question answering across multiple documents
- **Knowledge Management**: Persistent vector storage with document tracking
## Features
✅ **MCP-compatible** - Works with Claude Desktop, Cursor, and other MCP clients
✅ **Claude-powered** - Uses Claude Sonnet 4.5 for summarization and Q&A
✅ **Local execution** - Runs on your machine with no external infrastructure
✅ **Persistent storage** - Single vector store survives across sessions
✅ **Multi-document RAG** - Unlimited documents in knowledge base
✅ **Simple setup** - Install dependencies, configure API keys, and go
## Installation
### Prerequisites
- Python 3.8+
- Anthropic API key (for Claude text generation)
- OpenAI API key (for embeddings)
- MCP-compatible client (Claude Desktop, Cursor, etc.)
### Setup
1. **Install dependencies:**
```bash
cd /path/to/myaigist_mcp
pip install -r requirements.txt
```
2. **Configure environment:**
```bash
cp .env.example .env
# Edit .env and add both API keys:
# - ANTHROPIC_API_KEY (for Claude)
# - OPENAI_API_KEY (for embeddings)
```
3. **Configure your MCP client:**
**Claude Desktop** - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"myaigist": {
"command": "python3",
"args": ["/path/to/myaigist_mcp/server.py"]
}
}
}
```
**Cursor** - Add to your Cursor MCP settings:
```json
{
"mcpServers": {
"myaigist": {
"command": "python3",
"args": ["/path/to/myaigist_mcp/server.py"]
}
}
}
```
**Other MCP clients** - Refer to your client's documentation for MCP server configuration.
4. **Restart your MCP client**
The MCP server will start automatically when you open your client.
## Architecture
```
myaigist_mcp/ # MCP server (this project)
├── server.py # Main MCP server with 10 tools
├── mcp_agents/ # All agent code (local, self-contained)
│ ├── document_processor.py # PDF/DOCX/TXT extraction
│ ├── summarizer.py # 3-level summarization (Claude)
│ ├── embeddings.py # OpenAI embeddings
│ ├── url_crawler.py # Web content extraction
│ ├── claude_client.py # Anthropic client factory
│ ├── openai_client.py # OpenAI client factory
│ ├── qa_agent.py # Q&A with RAG (Claude)
│ └── vector_store.py # Vector storage
└── data/ # Persistent vector storage
└── vector_store.pkl # Created at runtime
```
**Architecture Notes:**
- All agents are self-contained in `mcp_agents/`
- No external dependencies on other projects
- Single-user design (no session/user isolation)
- Persistent vector storage with unlimited documents
- **Claude Sonnet 4.5** for text generation (summarization, Q&A)
- **OpenAI** for embeddings (RAG)
## Available Tools (10 Total)
### Content Processing (5 tools)
#### 1. `process_document`
Process a document from LOCAL FILE PATH (PDF, DOCX, TXT) and add to knowledge base.
**Parameters:**
- `file_path` (string, required): LOCAL filesystem path (e.g., /Users/mike/file.pdf)
- `title` (string, optional): Document title (defaults to filename)
- `summary_level` (string, optional): `quick`, `standard`, or `detailed`
**Example:**
```
"Process /Users/mike/contract.pdf as a detailed summary"
```
**Compatibility:** Works with all MCP clients.
#### 2. `process_uploaded_document`
Process a document attached to Claude Desktop (optimized for Claude Desktop file uploads).
**Parameters:**
- `content` (string, required): Text content extracted by Claude
- `filename` (string, required): Original filename
- `summary_level` (string, optional): `quick`, `standard`, or `detailed`
**Example:**
```
[Attach PDF file in Claude Desktop]
"Process this document with MyAIGist"
```
**Compatibility:** Designed for Claude Desktop. Other clients should use `process_document` with file paths.
#### 3. `process_text`
Process raw text and add to knowledge base.
**Example:**
```
"Process this text: [paste long article]"
```
**Compatibility:** Works with all MCP clients.
#### 4. `process_url`
Crawl web URL, extract content, and add to knowledge base.
**Example:**
```
"Process https://example.com/article"
```
**Compatibility:** Works with all MCP clients.
#### 5. `process_batch`
Process multiple files and generate unified summary.
**Example:**
```
"Process all files in /Users/mike/research/ and give me a unified summary"
```
**Compatibility:** Works with all MCP clients.
### Q&A System (1 tool)
#### 6. `ask_question`
Ask questions about stored documents using RAG.
**Example:**
```
"What are the main findings in the research papers?"
```
**Compatibility:** Works with all MCP clients.
### Document Management (3 tools)
#### 7. `list_documents`
List all documents in knowledge base with metadata.
**Example:**
```
"Show me all my documents"
```
**Compatibility:** Works with all MCP clients.
#### 8. `delete_document`
Delete specific document by ID.
**Example:**
```
"Delete document abc123xyz"
```
**Compatibility:** Works with all MCP clients.
#### 9. `clear_all_documents`
Clear entire knowledge base.
**Example:**
```
"Clear all my documents"
```
**Compatibility:** Works with all MCP clients.
### Utility Tools (1 tool)
#### 10. `get_status`
Get system status and knowledge base statistics.
**Example:**
```
"What's my system status?"
```
**Compatibility:** Works with all MCP clients.
## Common Workflows
### File Upload (Claude Desktop)
```
User: [Attaches PDF to Claude Desktop]
User: "Process this document with MyAIGist"
Claude: ✅ Processed with summary
User: "What are the key points?"
Claude: "The key points are..."
```
### Single Document Q&A (Any MCP Client)
```
User: "Process /Users/mike/contract.pdf"
AI: ✅ Processed with summary
User: "What are the payment terms?"
AI: "The payment terms are net 30..."
```
### Multi-Document Research (Any MCP Client)
```
User: "Process these 3 research papers: paper1.pdf, paper2.pdf, paper3.pdf"
AI: ✅ Processed all 3 with unified summary
User: "What are the common findings across all papers?"
AI: "The common findings are..."
```
## Configuration
### Environment Variables (.env)
```bash
# Anthropic API Key (required - for Claude text generation)
ANTHROPIC_API_KEY=sk-ant-your-key-here
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
# OpenAI API Key (required - for embeddings)
OPENAI_API_KEY=sk-your-key-here
OPENAI_EMBED_MODEL=text-embedding-3-large
```
### Model Selection
**Current Configuration:**
- **Claude Sonnet 4.5** (`claude-sonnet-4-5-20250929`) - Summarization and Q&A
- **text-embedding-3-large** - Higher accuracy for RAG vector search
**Why Two API Keys?**
- **Anthropic Claude**: Text generation (summarization, Q&A) - excellent quality
- **OpenAI**: Embeddings (Claude doesn't provide embeddings)
### Storage
**Vector Store:**
- Path: `data/vector_store.pkl`
- Format: Pickle with numpy arrays
- Persistence: Survives server restarts
- Capacity: Unlimited documents
## API Costs
**Usage-based pricing:**
- **Claude Sonnet 4.5**: $3/$15 per 1M tokens (input/output)
- **OpenAI Embeddings**: $0.13 per 1M tokens
**Typical monthly usage:**
- 100 documents processed: ~$5-10
- 500 questions answered: ~$2-5
- **Total: ~$10-15/month**
## Troubleshooting
### Server won't start
```bash
# Check if Python can find dependencies
python3 -c "import mcp; print('✅ MCP installed')"
# Check syntax
python3 -m py_compile server.py
# Check logs (Claude Desktop example)
tail -f ~/Library/Logs/Claude/mcp-server-myaigist.log
```
### Import errors
```bash
# Test agent imports
cd /path/to/myaigist_mcp
python3 -c "from mcp_agents.summarizer import Summarizer; print('✅ Imports work')"
python3 -c "from mcp_agents.qa_agent import QAAgent; print('✅ QAAgent works')"
```
### API Key errors
```bash
# Check environment variables are set
python3 -c "import os; print('Anthropic:', bool(os.getenv('ANTHROPIC_API_KEY'))); print('OpenAI:', bool(os.getenv('OPENAI_API_KEY')))"
```
### Empty knowledge base after restart
- Check `data/vector_store.pkl` exists
- Verify file permissions (readable/writable)
- Check for errors in server logs
### File upload not working
- **Claude Desktop**: Use `process_uploaded_document` for file attachments
- **Other clients**: Use `process_document` with local filesystem paths
- See tool descriptions for compatibility details
## Development
### Running Tests
```bash
# Test agent imports
python3 -c "from mcp_agents.qa_agent import QAAgent; qa = QAAgent(); print('✅ QAAgent works')"
# Test document processing
cd /path/to/myaigist_mcp
python3 -c "from mcp_agents.document_processor import DocumentProcessor; dp = DocumentProcessor(); print('✅ DocumentProcessor works')"
```
### Debugging
```bash
# Run server manually to see output
python3 /path/to/myaigist_mcp/server.py
```
## Project Structure
```
myaigist_mcp/
├── server.py # Main MCP server (10 tools)
├── requirements.txt # Python dependencies
├── .env # Environment variables (not in git)
├── .env.example # Template
├── README.md # This file
├── mcp_agents/ # MCP-adapted agents
│ ├── __init__.py
│ ├── claude_client.py # Anthropic client factory
│ ├── summarizer.py # Modified: uses Claude
│ ├── qa_agent.py # Modified: uses Claude, single-user
│ ├── vector_store.py # Modified: no user filtering
│ ├── document_processor.py
│ ├── embeddings.py
│ ├── url_crawler.py
│ └── openai_client.py
└── data/ # Persistent storage
└── vector_store.pkl # Vector embeddings and metadata
```
## MCP Client Compatibility
### Tested Clients
- ✅ **Claude Desktop** - Full support including file attachments
- ⚠️ **Cursor** - Core functionality works (use file paths instead of attachments)
- ❓ **Other MCP clients** - Should work with file path-based tools
### Compatibility Notes
- All tools work with standard file paths
- `process_uploaded_document` is optimized for Claude Desktop's file attachment behavior
- Other clients should use `process_document` with local file paths
- Standard MCP protocol (stdio transport, JSON-RPC)
## License
MIT License
## Support
For issues or questions:
1. Check troubleshooting section above
2. Review MCP server logs (location varies by client)
3. Verify environment variables in `.env`
4. Test agent imports individually
---
**Last Updated:** 2026-01-19
**Project Status:** ✅ Production ready - 10 core tools implemented and tested
**Models:** Claude Sonnet 4.5 (text) + OpenAI (embeddings)
**Focus:** Document intelligence (text-based content only)
**Compatibility:** Claude Desktop, Cursor, and other MCP-compatible clients
