Metadata-Version: 2.4
Name: papr-memory-mcp
Version: 0.1.0
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: 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

1. Clone this repository for Python MCP Papr Server:
```bash
git clone https://github.com/Papr-ai/papr_mcpserver
cd python-mcp
```

2. Run the setup script:
```bash
# Try python3 first (recommended for cross-platform compatibility)
python3 setup_run_mcp.py

# If python3 is not found, use python instead
python setup_run_mcp.py
```

> **Note:** If `python3` command is not found on your system, use `python` instead. This is common on Windows systems where Python 3 is installed as the default `python` command.

The setup script will guide you through the following steps:

1. **Dependencies Installation**
   - Installs `uv` if not already present
   - Creates a virtual environment (default '.venv')
   - Installs all required project dependencies

2. **API Key Configuration**
   - Prompts for your Papr API key
   - Validates the key format
   - Stores it securely in `.env` file

3. **MCP Client Selection**
   - Choose your preferred client:
     - Claude
     - Cursor AI
     - Other

4. **Client Configuration**
   - For Claude: Automatically configures `claude_desktop_config.json`
   - For Cursor AI: Automatically configures `./cursor/mcp.json`
   - For Other clients: Displays the configuration JSON in console (you'll need to manually copy this to your client's configuration)

> **Note:** If you select "Other" as your client, the script will print the MCP configuration JSON to the console. You'll need to manually copy this configuration to your client's appropriate configuration file.

The script will then:
- Start the MCP server (optional)


> **Tip:** You can always start the server later using the options described in the "Manual Server Start" section below.

## Setup Options

You can run the setup script with different options:

```bash
# Full setup with all prompts
python3 setup_run_mcp.py  # or python setup_run_mcp.py

# Skip dependency installation
python3 setup_run_mcp.py --skip-deps  # or python setup_run_mcp.py --skip-deps

# Skip setup and run server 
python3 setup_run_mcp.py --run-server  # or python setup_run_mcp.py --run-server
```

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

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


