yomemoai-mcp 0.1.0__tar.gz

yomemoai_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

yomemoai_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

yomemoai_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yomemo.ai
+
+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.

yomemoai_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: yomemoai-mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for YoMemoAI - enables AI assistants to save and retrieve encrypted memories
+Author-email: lvxiangxiang <lvxiangxiang@shopline.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,cursor,mcp,mcp-server,memory,yomemoai
+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.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: mcp>=1.25.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+# yomemoai-mcp
+
+A Model Context Protocol (MCP) server for YoMemoAI, enabling AI assistants to save and retrieve encrypted memories.
+
+## Features
+
+- 🔐 **Secure Storage**: Encrypted memory storage using RSA-OAEP and AES-GCM
+- 🏷️ **Categorization**: Organize memories with handles (tags/categories)
+- 🔍 **Retrieval**: Query memories by handle or retrieve all memories
+- 🚀 **MCP Integration**: Seamlessly integrates with MCP-compatible AI assistants
+
+## Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+- YoMemoAI API key
+- RSA private key (PEM format)
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone <repository-url>
+cd yomemoai-mcp
+```
+
+2. Install dependencies using uv:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a `.env` file in the project root with the following configuration:
+
+```bash
+# YoMemoAI MCP Server Configuration
+
+# Your API key from YoMemoAI (required)
+MEMO_API_KEY=your_api_key_here
+
+# Path to your private key file (RSA private key in PEM format)
+# Default: private.pem
+MEMO_PRIVATE_KEY_PATH=private.pem
+
+# Base URL of the YoMemoAI API (optional)
+# Default: https://api.yomemo.ai
+MEMO_BASE_URL=https://api.yomemo.ai
+```
+
+**Important Configuration Notes:**
+
+1. **MEMO_API_KEY** (required): Your YoMemoAI API key. You must obtain this from your YoMemoAI account.
+
+2. **MEMO_PRIVATE_KEY_PATH**: Path to your RSA private key file. The private key should be in PEM format:
+
+   ```
+   -----BEGIN PRIVATE KEY-----
+   ...
+   -----END PRIVATE KEY-----
+   ```
+
+   Make sure this file is secure and never commit it to version control.
+
+3. **MEMO_BASE_URL** (optional): The API base URL. Defaults to `https://api.yomemo.ai` if not specified.
+
+## Usage
+
+### Running the MCP Server
+
+After configuration, you can run the MCP server using:
+
+```bash
+uv run memo-mcp
+```
+
+### Integration with Cursor/Claude Desktop
+
+Add the following configuration to your MCP settings file:
+
+**For Cursor**: `~/.cursor/mcp.json` (or `%APPDATA%\Cursor\User\mcp.json` on Windows)  
+**For Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+#### Option 1: Using `uvx` (Recommended - after publishing to PyPI)
+
+If the package is published to PyPI, you can use `uvx` to run it directly. The package provides multiple entry points:
+
+**Using `uvx yomemoai-mcp`** (recommended):
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uvx",
+      "args": ["yomemoai-mcp"],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**How `uvx` works:**
+
+- `uvx` automatically downloads the package from PyPI (if not already installed)
+- It runs the package's entry point script defined in `project.scripts`
+- The package name is `yomemoai-mcp`, so `uvx yomemoai-mcp` will automatically use the `yomemoai-mcp` entry point
+- The package also provides alternative entry points: `yomemo` and `memo-mcp` (all point to the same server)
+
+**Note**: The package must be published to PyPI before using `uvx`. If the package is not yet published, use Option 2 for local development.
+
+#### Option 2: Using local development setup
+
+For local development or if the package is not yet published, use the `uv --directory` approach:
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/yomemoai-mcp",
+        "run",
+        "yomemoai-mcp"
+      ],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**Important Notes:**
+
+- **For Option 1 (`uvx`)**: The package must be published to PyPI. `uvx` will automatically handle installation and execution.
+- **For Option 2 (local)**: Replace `/absolute/path/to/yomemoai-mcp` with the **absolute path** to this repository on your system
+- Replace `/absolute/path/to/private.pem` with the **absolute path** to your private key file
+- The `env` section in the MCP config will override any `.env` file in the project directory
+- After updating the MCP config, restart Cursor/Claude Desktop for changes to take effect
+
+### Available Tools
+
+#### `save_memory`
+
+Store important information, user preferences, or conversation context as a permanent memory.
+
+**Parameters:**
+
+- `content` (required): The actual text/information to be remembered
+- `handle` (optional): A short, unique category or tag (e.g., 'work', 'personal', 'project-x'). Defaults to 'general'
+- `description` (optional): A brief summary of what this memory is about
+
+#### `load_memories`
+
+Retrieve previously stored memories or context.
+
+**Parameters:**
+
+- `handle` (optional): Filter memories by category. If not specified, returns all memories
+
+## Development
+
+### Project Structure
+
+```
+yomemoai-mcp/
+├── src/
+│   └── yomemoai_mcp/
+│       ├── __init__.py
+│       ├── server.py      # MCP server implementation
+│       ├── client.py      # YoMemoAI API client
+│       └── py.typed       # Type hints marker
+├── pyproject.toml         # Project configuration
+├── uv.lock                # Dependency lock file
+└── README.md
+```
+
+### Dependencies
+
+- `cryptography`: For encryption/decryption operations
+- `fastmcp`: FastMCP framework for MCP servers
+- `mcp`: Model Context Protocol SDK
+- `python-dotenv`: Environment variable management
+- `requests`: HTTP client for API calls
+
+## Security Notes
+
+- **Never commit** your `.env` file or private key files to version control
+- Keep your private key secure and never share it
+- The `.env` file is already included in `.gitignore`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+[Add contribution guidelines here]
+
+## Support
+
+For issues and questions, please open an issue on the repository.

yomemoai_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,187 @@
+# Publishing Guide
+
+This document describes how to publish `yomemoai-mcp` to PyPI so that users can install it using `uvx yomemoai-mcp`.
+
+## Prerequisites
+
+1. **PyPI Account**: Create an account at [PyPI](https://pypi.org/) if you don't have one
+2. **TestPyPI Account** (recommended for testing): Create an account at [TestPyPI](https://test.pypi.org/)
+3. **API Token**: You'll need an API token to publish packages
+
+## Step 1: Create API Token
+
+1. Log in to [PyPI](https://pypi.org/)
+2. Go to **Account settings** → **API tokens**
+3. Click **Add API token**
+4. Choose scope:
+   - **Entire account**: Can publish any package (recommended for personal projects)
+   - **Project-specific**: Limited to a specific package
+5. **Important**: Copy the token immediately - it's only shown once!
+   - Format: `pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+## Step 2: Configure Authentication
+
+### Option A: Using Environment Variable (Recommended)
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### Option B: Using uv's Credential Store
+
+uv will prompt for credentials when you run `uv publish` for the first time.
+
+## Step 3: Build the Package
+
+Before publishing, build the package to ensure everything is correct:
+
+```bash
+cd python-yomemo-mcp
+uv build
+```
+
+This will create a `dist/` directory containing:
+- `yomemoai_mcp-0.1.0-py3-none-any.whl` (wheel distribution)
+- `yomemoai-mcp-0.1.0.tar.gz` (source distribution)
+
+## Step 4: Test on TestPyPI (Recommended)
+
+Before publishing to the real PyPI, test on TestPyPI:
+
+### 4.1 Create TestPyPI API Token
+
+1. Log in to [TestPyPI](https://test.pypi.org/)
+2. Create an API token (same process as PyPI)
+3. Export the token:
+   ```bash
+   export UV_PUBLISH_TOKEN=pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+   ```
+
+### 4.2 Publish to TestPyPI
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+### 4.3 Test Installation
+
+Test that the package can be installed and run:
+
+```bash
+# Test installation from TestPyPI
+uvx --index-url https://test.pypi.org/simple/ yomemoai-mcp --help
+
+# Or test in a clean environment
+uv venv test-env
+source test-env/bin/activate  # On Windows: test-env\Scripts\activate
+pip install --index-url https://test.pypi.org/simple/ yomemoai-mcp
+yomemoai-mcp --help
+```
+
+## Step 5: Publish to PyPI
+
+Once testing is successful, publish to the real PyPI:
+
+### 5.1 Set Production API Token
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 5.2 Publish
+
+```bash
+uv publish
+```
+
+Or explicitly specify the URL:
+
+```bash
+uv publish --publish-url https://upload.pypi.org/legacy/
+```
+
+## Step 6: Verify Publication
+
+After publishing, verify the package is available:
+
+### 6.1 Check Package on PyPI
+
+Visit: https://pypi.org/project/yomemoai-mcp/
+
+### 6.2 Test Installation
+
+```bash
+# Test with uvx
+uvx yomemoai-mcp --help
+
+# Or install directly
+pip install yomemoai-mcp
+yomemoai-mcp --help
+```
+
+### 6.3 Check Package Metadata
+
+```bash
+curl https://pypi.org/pypi/yomemoai-mcp/json | jq
+```
+
+## Updating the Package
+
+When you need to publish a new version:
+
+1. **Update version** in `pyproject.toml`:
+   ```toml
+   version = "0.1.1"  # or 0.2.0, 1.0.0, etc.
+   ```
+
+2. **Update CHANGELOG** (if you maintain one)
+
+3. **Build and publish**:
+   ```bash
+   uv build
+   uv publish
+   ```
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.1.0): New features, backward compatible
+- **PATCH** (0.1.1): Bug fixes, backward compatible
+
+## Troubleshooting
+
+### Error: "Package already exists"
+
+- If you're updating an existing package, make sure to increment the version number
+- If the package name is taken, you'll need to choose a different name
+
+### Error: "Invalid credentials"
+
+- Check that your API token is correct
+- Make sure you're using the right token (TestPyPI vs PyPI)
+- Tokens expire after a period of inactivity - create a new one if needed
+
+### Error: "File already exists"
+
+- The version you're trying to publish already exists
+- Increment the version number in `pyproject.toml`
+
+### Package not found after publishing
+
+- Wait a few minutes - PyPI indexing can take time
+- Check the package name is correct: `yomemoai-mcp`
+- Verify the package is published: https://pypi.org/project/yomemoai-mcp/
+
+## Security Notes
+
+- **Never commit** API tokens to version control
+- Use environment variables or credential stores
+- Rotate tokens periodically
+- Use project-specific tokens when possible (more secure than account-wide tokens)
+
+## Additional Resources
+
+- [PyPI Documentation](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/)
+- [uv Documentation](https://docs.astral.sh/uv/)
+- [Python Packaging User Guide](https://packaging.python.org/)

yomemoai_mcp-0.1.0/README.md

@@ -0,0 +1,211 @@
+# yomemoai-mcp
+
+A Model Context Protocol (MCP) server for YoMemoAI, enabling AI assistants to save and retrieve encrypted memories.
+
+## Features
+
+- 🔐 **Secure Storage**: Encrypted memory storage using RSA-OAEP and AES-GCM
+- 🏷️ **Categorization**: Organize memories with handles (tags/categories)
+- 🔍 **Retrieval**: Query memories by handle or retrieve all memories
+- 🚀 **MCP Integration**: Seamlessly integrates with MCP-compatible AI assistants
+
+## Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+- YoMemoAI API key
+- RSA private key (PEM format)
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone <repository-url>
+cd yomemoai-mcp
+```
+
+2. Install dependencies using uv:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a `.env` file in the project root with the following configuration:
+
+```bash
+# YoMemoAI MCP Server Configuration
+
+# Your API key from YoMemoAI (required)
+MEMO_API_KEY=your_api_key_here
+
+# Path to your private key file (RSA private key in PEM format)
+# Default: private.pem
+MEMO_PRIVATE_KEY_PATH=private.pem
+
+# Base URL of the YoMemoAI API (optional)
+# Default: https://api.yomemo.ai
+MEMO_BASE_URL=https://api.yomemo.ai
+```
+
+**Important Configuration Notes:**
+
+1. **MEMO_API_KEY** (required): Your YoMemoAI API key. You must obtain this from your YoMemoAI account.
+
+2. **MEMO_PRIVATE_KEY_PATH**: Path to your RSA private key file. The private key should be in PEM format:
+
+   ```
+   -----BEGIN PRIVATE KEY-----
+   ...
+   -----END PRIVATE KEY-----
+   ```
+
+   Make sure this file is secure and never commit it to version control.
+
+3. **MEMO_BASE_URL** (optional): The API base URL. Defaults to `https://api.yomemo.ai` if not specified.
+
+## Usage
+
+### Running the MCP Server
+
+After configuration, you can run the MCP server using:
+
+```bash
+uv run memo-mcp
+```
+
+### Integration with Cursor/Claude Desktop
+
+Add the following configuration to your MCP settings file:
+
+**For Cursor**: `~/.cursor/mcp.json` (or `%APPDATA%\Cursor\User\mcp.json` on Windows)  
+**For Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+#### Option 1: Using `uvx` (Recommended - after publishing to PyPI)
+
+If the package is published to PyPI, you can use `uvx` to run it directly. The package provides multiple entry points:
+
+**Using `uvx yomemoai-mcp`** (recommended):
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uvx",
+      "args": ["yomemoai-mcp"],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**How `uvx` works:**
+
+- `uvx` automatically downloads the package from PyPI (if not already installed)
+- It runs the package's entry point script defined in `project.scripts`
+- The package name is `yomemoai-mcp`, so `uvx yomemoai-mcp` will automatically use the `yomemoai-mcp` entry point
+- The package also provides alternative entry points: `yomemo` and `memo-mcp` (all point to the same server)
+
+**Note**: The package must be published to PyPI before using `uvx`. If the package is not yet published, use Option 2 for local development.
+
+#### Option 2: Using local development setup
+
+For local development or if the package is not yet published, use the `uv --directory` approach:
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/yomemoai-mcp",
+        "run",
+        "yomemoai-mcp"
+      ],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**Important Notes:**
+
+- **For Option 1 (`uvx`)**: The package must be published to PyPI. `uvx` will automatically handle installation and execution.
+- **For Option 2 (local)**: Replace `/absolute/path/to/yomemoai-mcp` with the **absolute path** to this repository on your system
+- Replace `/absolute/path/to/private.pem` with the **absolute path** to your private key file
+- The `env` section in the MCP config will override any `.env` file in the project directory
+- After updating the MCP config, restart Cursor/Claude Desktop for changes to take effect
+
+### Available Tools
+
+#### `save_memory`
+
+Store important information, user preferences, or conversation context as a permanent memory.
+
+**Parameters:**
+
+- `content` (required): The actual text/information to be remembered
+- `handle` (optional): A short, unique category or tag (e.g., 'work', 'personal', 'project-x'). Defaults to 'general'
+- `description` (optional): A brief summary of what this memory is about
+
+#### `load_memories`
+
+Retrieve previously stored memories or context.
+
+**Parameters:**
+
+- `handle` (optional): Filter memories by category. If not specified, returns all memories
+
+## Development
+
+### Project Structure
+
+```
+yomemoai-mcp/
+├── src/
+│   └── yomemoai_mcp/
+│       ├── __init__.py
+│       ├── server.py      # MCP server implementation
+│       ├── client.py      # YoMemoAI API client
+│       └── py.typed       # Type hints marker
+├── pyproject.toml         # Project configuration
+├── uv.lock                # Dependency lock file
+└── README.md
+```
+
+### Dependencies
+
+- `cryptography`: For encryption/decryption operations
+- `fastmcp`: FastMCP framework for MCP servers
+- `mcp`: Model Context Protocol SDK
+- `python-dotenv`: Environment variable management
+- `requests`: HTTP client for API calls
+
+## Security Notes
+
+- **Never commit** your `.env` file or private key files to version control
+- Keep your private key secure and never share it
+- The `.env` file is already included in `.gitignore`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+[Add contribution guidelines here]
+
+## Support
+
+For issues and questions, please open an issue on the repository.

yomemoai_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "yomemoai-mcp"
+version = "0.1.0"
+description = "Model Context Protocol (MCP) server for YoMemoAI - enables AI assistants to save and retrieve encrypted memories"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "lvxiangxiang", email = "lvxiangxiang@shopline.com" }
+]
+requires-python = ">=3.12"
+keywords = ["mcp", "mcp-server", "yomemoai", "memory", "ai", "claude", "cursor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "cryptography>=46.0.3",
+    "fastmcp>=0.1.0",
+    "mcp>=1.25.0",
+    "python-dotenv>=1.2.1",
+    "requests>=2.32.5",
+]
+
+[project.scripts]
+yomemoai-mcp = "yomemoai_mcp.server:mcp.run"
+yomemo = "yomemoai_mcp.server:mcp.run"
+memo-mcp = "yomemoai_mcp.server:mcp.run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

yomemoai_mcp-0.1.0/src/yomemoai_mcp/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from yomemoai-mcp!"