Metadata-Version: 2.4
Name: mcp-personal-assistant
Version: 0.2.2
Summary: Personal Assistant MCP Server with SQLite/TinyDB support for status tracking, project management, todos, calendar functionality, and document storage
Project-URL: Homepage, https://github.com/swapnilsurdi/mcp-pa
Project-URL: Repository, https://github.com/swapnilsurdi/mcp-pa
Project-URL: Issues, https://github.com/swapnilsurdi/mcp-pa/issues
Project-URL: Documentation, https://github.com/swapnilsurdi/mcp-pa#readme
Author: MCP Personal Assistant Contributors
Maintainer: MCP Personal Assistant Contributors
License: MIT License
        
        Copyright (c) 2025 Swapnil
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: calendar,claude,mcp,model-context-protocol,personal-assistant,productivity,project-management,sqlite,todo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: System Shells
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: tinydb>=4.8.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: http
Requires-Dist: fastapi>=0.104.0; extra == 'http'
Requires-Dist: psycopg2-binary>=2.9.7; extra == 'http'
Requires-Dist: redis>=5.0.0; extra == 'http'
Requires-Dist: uvicorn>=0.24.0; extra == 'http'
Description-Content-Type: text/markdown

# MCP Personal Assistant

A comprehensive MCP (Model Context Protocol) server for personal productivity management, including status tracking, project management, todos, calendar functionality, and document storage.

## Features

### 🔍 Status Management
- Track your current location, laptop details, and system permissions
- View a dashboard of active projects and upcoming tasks
- Update your personal information and system status

### 📋 Project Management
- Create and manage projects with customizable status and priority
- Add tasks to projects with due dates and priorities
- Track project progress with percentage completion
- Filter projects by status (not started, in progress, on hold, completed, cancelled)

### ✅ Todo Management
- Create and manage todos with due dates and reminders
- Set priority levels (low, medium, high, urgent)
- Mark todos as completed
- Filter todos by completion status

### 📅 Calendar Management
- Create calendar events with start/end times
- Set event locations and attendee lists
- Configure reminder notifications
- View events within date ranges

### 📄 Document Management
- Upload and store documents (PDFs, images, text files, etc.)
- Create references to external documents (cloud storage links)
- Tag and organize documents
- Support for encrypted storage
- Automatic file type detection and categorization

## Installation & Setup

### Prerequisites
- Python 3.10 or higher
- Claude Desktop application

### Installation Options

#### Option 1: Install from PyPI (Recommended)

**Using uvx (recommended):**
```bash
uvx install mcp-personal-assistant
```

**Using pipx:**
```bash
pipx install mcp-personal-assistant
```

**Using pip:**
```bash
pip install mcp-personal-assistant
```

#### Option 2: Install from Source (Development)

**Step 1: Clone the Repository**
```bash
git clone <repository-url>
cd mcp-pa
```

**Step 2: Create Virtual Environment**
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

**Step 3: Install Dependencies**
```bash
pip install -r requirements.txt
pip install -e .  # Install in development mode
```

## Configuration

The MCP server can be configured using environment variables:

### Database Configuration
- `MCP_PA_DB_TYPE`: Database type (`sqlite` or `tinydb`, default: `sqlite`)
- `MCP_PA_DB_PATH`: Custom database file path
- `MCP_PA_ENCRYPTION_KEY`: Encryption key for database (optional)

### Storage Configuration
- `MCP_PA_DOCS_DIR`: Directory for document storage
- `MCP_PA_MAX_FILE_SIZE_MB`: Maximum file size in MB (default: 100)

### Default Locations
- **macOS**: `~/Library/Application Support/mcp-pa/`
- **Linux**: `~/.config/mcp-pa/`
- **Windows**: `%APPDATA%\mcp-pa\`

To use specific settings:
```bash
export MCP_PA_DB_TYPE=sqlite
export MCP_PA_ENCRYPTION_KEY=mysecretkey
export MCP_PA_DOCS_DIR=/path/to/documents
```

## Claude Desktop Configuration

1. **Locate your Claude Desktop configuration file:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add the MCP server configuration:**

### For PyPI Installation (uvx/pipx/pip):
```json
{
  "mcpServers": {
    "personal-assistant": {
      "command": "uvx",
      "args": ["mcp-personal-assistant"],
      "env": {
        "MCP_PA_DB_TYPE": "sqlite"
      }
    }
  }
}
```

### For Source Installation:
```json
{
  "mcpServers": {
    "personal-assistant": {
      "command": "/path/to/your/mcp-pa/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/your/mcp-pa",
      "env": {
        "MCP_PA_DB_TYPE": "sqlite"
      }
    }
  }
}
```

**Notes for Source Installation:**
- Use the **full path** to your virtual environment's Python executable
- Use the **full path** to your project directory in the `cwd` field
- On Windows, use forward slashes or escaped backslashes in paths

3. **Restart Claude Desktop** for the configuration to take effect

## Usage Examples

Once configured, the MCP Personal Assistant integrates seamlessly with Claude Desktop. Here are some examples of how it works:

### Claude Desktop Settings
![Claude Settings](examples/claude_settings.png)

You can configure Claude with custom instructions to automatically use the MCP Personal Assistant tools for status updates and project management.

### MCP Server Status
![MCP Server Configuration](examples/mcp_server_status.png)

The server appears in Claude Desktop's developer settings, showing it's running and properly configured.

### Creating Projects
![Creating a Project](examples/creating_project.png)

You can ask Claude to create projects, and it will use the MCP Personal Assistant tools to manage your project data.

### Managing Project Data
![Managing Projects](examples/managing_projects.png)

The assistant can update project status, add tasks, and maintain detailed project information with automatic data persistence.

### Intelligent Assistance
![Travel Recommendations](examples/travel_recommendations.png)

Claude can access your status and project history to provide personalized recommendations and assistance based on your stored preferences and travel history.

### Verification

After restarting Claude Desktop, you should see the MCP Personal Assistant tools available. You can verify the setup by:

1. Asking Claude to use the `get_status` tool
2. Creating a test project with `create_project`
3. Viewing the dashboard with `get_dashboard`

If you encounter issues, check the Claude Desktop logs at:
- **macOS**: `~/Library/Logs/Claude/mcp-server-personal-assistant.log`

## Quick Start Examples

### 🚀 **PyPI Installation Quick Start**
```bash
# Install the package
uvx install mcp-personal-assistant

# Copy the Claude Desktop config template (update paths as needed)
cp examples/claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop
```

### 🧪 **Test the Installation**
```bash
# Test the console script
mcp-personal-assistant --help

# Run the basic usage example to verify everything works
python examples/basic_usage.py
```

### 📁 **Template Files**
The `examples/` directory contains ready-to-use templates and scripts:
- `claude_desktop_config.json` - Template configuration for Claude Desktop
- `basic_usage.py` - Standalone script to test functionality
- Usage screenshots showing the MCP in action

## Available Tools

### Status Management

#### `get_status`
Get your current status including location, laptop details, permissions, and system information.

#### `update_status`
Update your status information.

### Project Management

#### `create_project`
Create a new project with name, description, status, priority, dates, and tags.

#### `list_projects`
List all projects or filter by status.

#### `get_project`
Get detailed information about a specific project.

#### `update_project`
Update project information including status, priority, and progress.

#### `add_project_task`
Add a task to a project.

### Todo Management

#### `create_todo`
Create a new todo with title, description, due date, priority, and tags.

#### `list_todos`
List all todos with optional completion status filter.

#### `complete_todo`
Mark a todo as completed.

### Calendar Management

#### `create_calendar_event`
Create a calendar event with start/end times, location, and attendees.

#### `list_calendar_events`
List calendar events within a date range.

### Document Management

#### `upload_document`
Upload a document with base64 encoded content.
```
Parameters:
- title: Document filename
- content_base64: Base64 encoded file content
- description: Optional description
- tags: Optional tags array
```

#### `create_external_document`
Create a reference to an external document.
```
Parameters:
- title: Document title
- external_url: URL to external document
- description: Optional description
- tags: Optional tags array
```

#### `list_documents`
List all documents with optional tag filtering.

#### `get_document`
Get detailed information about a specific document.

### Dashboard

#### `get_dashboard`
Get a comprehensive dashboard view of all activities.

## Database Support

### SQLite (Default)
- Better performance for larger datasets
- ACID compliance with transaction support
- Thread-safe with connection pooling
- Efficient concurrent access
- Supports database encryption

### TinyDB
- Simple JSON-based storage
- Human-readable database file
- Supports encryption via Fernet
- Good for smaller datasets
- Easy to backup and inspect

## Document Storage

The document manager supports:
- Automatic file type detection
- SHA-256 checksum calculation
- File size validation
- Metadata tagging
- External document references

Supported document types:
- PDF files
- Images (JPEG, PNG, etc.)
- Text files
- Spreadsheets (Excel, CSV)
- Presentations (PowerPoint)
- Other file types

## Security Features

### Database Encryption
- SQLite: Can use SQLCipher for encryption (if available)
- TinyDB: Uses Fernet symmetric encryption
- Encryption key configurable via environment variable

### Document Security
- Files stored with unique IDs
- Original filenames preserved in metadata
- Checksum verification for integrity
- File size limits enforced

## Advanced Usage

### Using with Multiple Instances
The server supports concurrent access from multiple clients:
- SQLite uses connection pooling
- TinyDB uses thread-safe locking
- Both handle concurrent read/write operations

### Custom Database Location
```bash
export MCP_PA_DB_PATH=/custom/path/database.sqlite
```

### Encrypted Database
```bash
export MCP_PA_ENCRYPTION_KEY=your-secure-key-here
```

## Project Structure

```
mcp-personal-assistant/
├── README.md                  # Main documentation
├── pyproject.toml            # Package configuration
├── requirements.txt          # Core dependencies
├── LICENSE                   # License file
├── pytest.ini              # Test configuration
├── Makefile                 # Build automation
│
├── src/                     # Source code
│   ├── __init__.py
│   ├── server.py            # Main MCP server
│   ├── config.py            # Configuration management
│   ├── models.py            # Data models
│   ├── database_interface.py
│   ├── database_factory.py
│   ├── sqlite_database.py
│   ├── tinydb_database.py
│   ├── document_manager.py
│   └── config/              # Configuration modules
│
├── examples/                # Usage examples
│   ├── README.md
│   ├── claude_desktop_config.json
│   └── basic_usage.py
│
├── docs/                    # Documentation
│   ├── quickstart.md
│   ├── architecture.md
│   ├── cloud-architecture.md
│   ├── security.md
│   └── development-notes.md
│
├── tests/                   # Test files
│
├── scripts/                 # Utility scripts
│   ├── check_performance_regression.py
│   ├── run_http_server.py
│   ├── run_tests.sh
│   └── test_framework_validation.py
│
├── deployment/              # Deployment files
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── init-db.sql
│
└── archive/                 # Development artifacts
    ├── old requirements files
    └── development reports
```

### Running Tests
```bash
python test_server.py
```

### Building the Package
```bash
pip install build
python -m build
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Troubleshooting

### Common Setup Issues

1. **"ModuleNotFoundError: No module named 'src'"**
   - Ensure you've installed the package in development mode: `pip install -e .`
   - Verify you're using the virtual environment's Python: `/path/to/venv/bin/python`

2. **"spawn python ENOENT"**
   - Use the full path to Python executable in Claude Desktop config
   - Don't use just `python` - use `/path/to/your/mcp-pa/venv/bin/python`

3. **"Server disconnected" errors**
   - Check that all dependencies are installed: `pip install -r requirements.txt`
   - Verify the `cwd` path points to your project directory
   - Check Claude Desktop logs for specific error messages

4. **"Unknown resource" errors**
   - This usually indicates a configuration issue
   - Restart Claude Desktop after making config changes
   - Ensure the server is properly installed with `pip install -e .`

### Log Files

Check these log files for debugging:

- **macOS**: `~/Library/Logs/Claude/mcp-server-personal-assistant.log`
- **Linux**: `~/.config/Claude/logs/mcp-server-personal-assistant.log`
- **Windows**: `%APPDATA%\Claude\logs\mcp-server-personal-assistant.log`

### Testing the Server Directly

You can test the server functionality outside of Claude Desktop:

```bash
# Activate virtual environment
source venv/bin/activate

# Test basic imports
python -c "import src.server; print('Server imports successfully')"

# Test database connection
python -c "from src.database_factory import get_database; db = get_database(); print('Database connected')"
```

### Other Common Issues

1. **Database Connection Errors**
   - Ensure the database directory exists
   - Check file permissions
   - Verify encryption key if using encryption

2. **Document Upload Failures**
   - Check file size limits
   - Ensure documents directory is writable
   - Verify base64 encoding is correct

3. **Configuration Problems**
   - Check environment variables
   - Verify the configuration file syntax
   - Ensure all required directories exist

## Future Enhancements

- [ ] File preview generation
- [ ] Full-text search across documents
- [ ] Automatic backup system
- [ ] OAuth integration for cloud storage
- [ ] Web interface for direct access
- [ ] Plugin system for extensibility
- [ ] Real-time notifications
- [ ] Database migration tools

## Support

For issues and feature requests, please create an issue in the GitHub repository.
