Metadata-Version: 2.4
Name: papr-memory-mcp
Version: 0.1.8
Summary: Papr Memory API integration for MCP (Model Context Protocol) servers
Home-page: https://github.com/Papr-ai/papr_mcpserver
Author: Papr Team
Author-email: Papr Team <support@papr.ai>
Maintainer-email: Papr Team <support@papr.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Papr-ai/papr_mcpserver
Project-URL: Documentation, https://github.com/Papr-ai/papr_mcpserver/tree/main/python-mcp
Project-URL: Repository, https://github.com/Papr-ai/papr_mcpserver
Project-URL: Issues, https://github.com/Papr-ai/papr_mcpserver/issues
Project-URL: Changelog, https://github.com/Papr-ai/papr_mcpserver/blob/main/python-mcp/CHANGELOG.md
Keywords: mcp,memory,ai,papr,model-context-protocol,fastmcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Communications
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.10.5
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: papr-memory>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: mcp>=1.10.1
Provides-Extra: dev
Requires-Dist: debugpy; extra == "dev"
Requires-Dist: flask>=2.0.0; extra == "dev"
Requires-Dist: flask-cors>=3.0.0; extra == "dev"
Requires-Dist: flask-socketio>=5.0.0; extra == "dev"
Requires-Dist: python-socketio>=5.0.0; extra == "dev"
Requires-Dist: eventlet>=0.30.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Provides-Extra: ml
Requires-Dist: numpy>=1.24.0; extra == "ml"
Requires-Dist: scipy>=1.11.0; extra == "ml"
Requires-Dist: langchain-community>=0.0.10; extra == "ml"
Requires-Dist: ollama>=0.1.6; extra == "ml"
Requires-Dist: sentence-transformers>=2.2.2; extra == "ml"
Requires-Dist: transformers>=4.36.0; extra == "ml"
Requires-Dist: langchain>=0.1.0; extra == "ml"
Provides-Extra: all
Requires-Dist: papr-memory-mcp[dev,ml,test]; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Papr MCP Server

A FastAPI-based MCP (Memory Control Protocol) server implementation for integrating with Papr's memory services (https://papr.ai).

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](../LICENSE) file for details.

## Prerequisites

- Python 3.10 or higher
- **Get your API key:** You can find it in the settings section of **[papr.ai](https://papr.ai)**. You'll need to create a developer account on Papr to get your API key.

## Quick Start (Recommended)

Run the universal setup script and follow the prompts:

```bash
python setup_mcp.py
```

What this does:
- Lets you choose your application (Cursor, Claude, or Other)
- Uses the PyPI package `papr-memory-mcp` with `uv` for automatic installation
- Prompts for your Papr API key
- Creates/updates the MCP configuration in the correct location
- For "Other", prints the JSON you can copy into your client's config

After setup, restart your selected application.

> **Note:** This method uses the published PyPI package `papr-memory-mcp` which is automatically installed and managed by `uv`. No local code changes needed.

## Alternative: Run Locally (Developer Mode)

If you prefer to run the MCP server locally from source:

1) Clone and enter the repo
```bash
git clone https://github.com/Papr-ai/papr_mcpserver
cd papr_mcpserver/python-mcp
```

2) Create and activate a virtual environment (recommended)
```bash
uv venv
source .venv/bin/activate    # macOS/Linux
# or on Windows PowerShell
.venv\Scripts\Activate.ps1
```

3) Install dependencies
```bash
uv pip install -e .[dev]
```

4) Set your API key
```bash
export PAPR_API_KEY=your_api_key_here        # macOS/Linux
setx PAPR_API_KEY your_api_key_here          # Windows (new shells)
$env:PAPR_API_KEY="your_api_key_here"       # Windows PowerShell (current shell)
```

5) Start the server
```bash
uv run python paprmcp.py
# or for interactive development
fastmcp dev paprmcp.py
```

6) Point your client to the server
- Use the JSON from the README (or run `python setup_mcp.py` and pick "Other") to configure your client’s `mcp.json`.

## Start Server Directly

If you chose not to start the server during setup, you can start it manually:

**On macOS/Linux:**
```bash
# Using uv directly
source .venv/bin/activate
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
source .venv/bin/activate
fastmcp dev paprmcp.py
```

**On Windows:**
```cmd
# Using uv directly
.venv\Scripts\activate
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
.venv\Scripts\activate
fastmcp dev paprmcp.py
```

**On Windows PowerShell:**
```powershell
# Using uv directly
.venv\Scripts\Activate.ps1
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
.venv\Scripts\Activate.ps1
fastmcp dev paprmcp.py
```

Note: Using the setup script with `--run-server` is recommended as it ensures the correct virtual environment is used and proper configuration is loaded.

## Created Configuration

The setup script creates two main configuration files:

1. `.env` file in the project root:
   - Contains your Papr API key
   - Sets the memory server URL (default is memory.papr.ai)

2. MCP configuration file (location depends on your OS and chosen client):
   - macOS: 
     - Claude: `~/Library/Application Support/claude/claude_desktop_config.json`
     - Cursor: `./cursor/mcp.json`
   - Windows:
     - Claude: `%APPDATA%/claude/claude_desktop_config.json`
     - Cursor: `./cursor/mcp.json`
   - Linux:
     - Claude: `~/.config/claude/claude_desktop_config.json`
     - Cursor: `./cursor/mcp.json`

## Testing

The project includes a comprehensive test suite that validates all MCP server functionality:

### Running Tests

**Quick Test (Recommended):**
```bash
python run_tests.py
```

**Direct Test Execution:**
```bash
python tests/test_mcp_comprehensive.py
```

**Using pytest (if installed):**
```bash
pytest tests/ -v
```

### Test Coverage

The comprehensive test validates:
- ✅ **Server Startup**: MCP server initialization and tool registration
- ✅ **MCP Protocol**: Real client-server communication via MCP protocol
- ✅ **CRUD Operations**: Complete Create, Read, Update, Delete workflow
- ✅ **API Integration**: Papr Memory API connectivity and responses
- ✅ **Error Handling**: Parameter validation and error propagation
- ✅ **Tool Availability**: All 8 tools properly registered and callable

### Test Structure

```
tests/
├── test_mcp_comprehensive.py  # Main comprehensive test
└── TESTING.md                 # Detailed testing documentation
```

The test suite merges multiple testing approaches:
- **CI/CD Testing**: Internal validation and error handling
- **MCP Protocol Testing**: Real client-server communication
- **Server Validation**: Command-line and import testing

## Development

The project uses `pyproject.toml` for dependency management with the following extras:
- `dev`: Development tools (debugpy, Flask, etc.)
- `test`: Testing tools (pytest, coverage, etc.)
- `all`: All of the above

To install specific extras:
```bash
uv pip install ".[dev]"  # Development dependencies
uv pip install ".[test]"  # Testing dependencies
uv pip install ".[all]"  # All dependencies
```
### Debugging with VS Code

1. Install debugpy:
```bash
uv pip install ".[dev]" 
```

2. **For MCP Inspector (optional):** Install Node.js to get npx:
```bash
# On Windows (using winget)
winget install OpenJS.NodeJS
# After installation, refresh PATH in PowerShell:
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User")

# Also ensure uv is properly installed and in PATH:
$env:PATH = "C:\Users\$env:USERNAME\.local\bin;$env:PATH"

# On macOS (using Homebrew)
brew install node

# On Linux (using package manager)
# Ubuntu/Debian:
sudo apt update && sudo apt install nodejs npm
# Or using NodeSource repository for latest version:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

3. Start the server as well as mcp inspector in debug mode:

**On macOS/Linux:**
```bash
source .venv/bin/activate
python -m debugpy --wait-for-client --listen 5678 .venv/bin/fastmcp dev paprmcp.py
```

**On Windows:**
```cmd
.venv\Scripts\activate
python -m debugpy --wait-for-client --listen 5678 .venv\Scripts\fastmcp.exe dev paprmcp.py
```

**On Windows PowerShell:**
```powershell
.venv\Scripts\Activate.ps1
python -m debugpy --wait-for-client --listen 5678 .venv\Scripts\fastmcp.exe dev paprmcp.py
```

4. In VS Code:
   - Go to Run and Debug view (Ctrl+Shift+D or Cmd+Shift+D)
   - Select "Python: Attach to FastMCP"
   - Click the green play button or press F5
   - Set breakpoints in your code by clicking in the left margin
   - The debugger will stop at breakpoints when the code is executed

5. **Using MCP Inspector (alternative to VS Code debugging):**
   - After starting the server with `fastmcp dev paprmcp.py`, you can use the MCP inspector
   - The inspector will automatically connect to your running MCP server
   - This provides a web-based interface to test and interact with your MCP tools


## Troubleshooting

If you encounter any issues:

1. **Python command not found:**
   - If `python3` is not found, try using `python` instead
   - Check your Python installation: `python --version` or `python3 --version`
   - On Windows, Python 3 is often installed as `python` rather than `python3`

2. **Windows-specific issues:**
   - **PowerShell execution policy:** If you get execution policy errors, run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
   - **Virtual environment activation:** Use `.venv\Scripts\activate` in Command Prompt or `.venv\Scripts\Activate.ps1` in PowerShell
   - **Path issues:** Ensure `uv` is in your PATH. It's typically installed to `%USERPROFILE%\.cargo\bin` or `%LOCALAPPDATA%\uv\bin`

3. **General issues:**
   - Check the logs for detailed error messages
   - Ensure your Papr API key is correctly set in the `.env` file
   - Verify the virtual environment is activated
   - Make sure all dependencies are installed correctly

For additional help, please contact support or open an issue in the repository.


