mirror-vectax

The Mirror VectorX Secure Embedding MCP Server provides a unified entry point for processing text with built-in security features. It supports multiple operation modes including embed for generating text embeddings, secure for applying security measures to text and embeddings, analyze for detecting sensitive information, mask for anonymizing entities, and auto to automatically determine the appropriate operation. The server leverages the Mirror SDK to offer format-preserving encryption (FPE) for sensitive entities, vector encryption for embeddings, RBAC-based access, and entity detection for PII. You can deploy the server and interact with it through the provided Python script (mirror_vectax_server.py) or via the Claude Desktop integration described in the setup instructions. To use the capabilities, configure the required environment variables (Mirror API key/secret and server URL) and supply embedding model preferences if needed. The MCP server exposes an API that accepts text inputs and returns embeddings or secured representations based on the selected mode. It also supports batch processing for handling multiple texts efficiently and can be integrated with LangChain or other NLP pipelines for semantic search tasks.

Prerequisites:

• Python 3.10+
• uv (for environment setup) or a Python-based MCP runtime
• Mirror SDK (and optionally erotic dependencies documented by the project)
• MCP Server framework and dependencies listed in requirements.txt
• Claude Desktop (for integration, optional)

Automatic setup (recommended):

1. Clone the repository:

git clone https://github.com/your-username/mirror-vectax-mcp-server.git
cd mirror-vectax-mcp-server

2. Install uv and create a virtual environment via uv (if not already installed):

# Install uv if needed
# (Follow the uv installation guide from https://github.com/astral-sh/uv)

3. Install MCP CLI and dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv add mcp[cli] httpx
uv add -r requirements.txt

4. Install Mirror SDK packages (from dist after downloading):

# Example placeholders; replace with actual file names/versions
uv add .\dist\mirror_sdk-<version>.whl
uv add .\dist\mirror_enc-<version>.whl

5. Set up environment variables (examples):

export MIRROR_API_KEY="your-mirror-api-key"
export MIRROR_SECRET="your-mirror-secret"
export MIRROR_SERVER_URL="https://your-mirror-server-url/v1"
export EMBEDDING_MODEL="nomic-ai/nomic-embed-text-v1.5"  # Optional
export EMBEDDING_DEVICE="cpu"  # or "cuda" for GPU

6. Start the server (see below for the recommended run script):

python mirror_vectax_server.py

Manual installation (alternative):

1. Clone the repository (as above).
2. Create and activate a virtual environment with uv:

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install mcp CLI and dependencies as above.
4. Install Mirror SDK wheels into the environment as above.
5. Configure environment variables as above and run the server with the Python script.

Notes:

• Ensure requirements.txt is up-to-date and all dependencies are installed.
• The server expects valid Mirror API credentials and a reachable server URL.
• If you plan to run via a Docker-based flow or Node.js tooling, adapt the mcp_config accordingly.

Tips and common issues:

• Ensure the Mirror API key/secret and server URL are correct and accessible from your runtime environment.
• If embeddings fail to generate, verify that the EMBEDDING_MODEL is supported by your Mirror SDK version and that the device (CPU/GPU) is available.
• For RBAC, define appropriate roles in your environment or configuration to enforce access policies.
• When using the uv-based setup, make sure the uv executable is on PATH and that virtual environments activate correctly across shells.
• If Claude Desktop integration is used, point Claude to the absolute path of the uv runner and ensure the mirror_vectax_server.py path is correct in the claude_desktop_config.json.
• For debugging, keep a log file (setup_log.txt) as described in the installation notes and consult it for errors during setup or runtime.