mem-brain-mcp 1.0.0__tar.gz

mem_brain_mcp-1.0.0/.dockerignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Documentation
+*.md
+!README.md
+!docker/**
+
+# AWS
+aws/
+*.json.bak
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Other
+*.bak
+tmp/
+temp/
+

mem_brain_mcp-1.0.0/.env

@@ -0,0 +1,10 @@
+# API Configuration
+API_BASE_URL=http://localhost:8000
+API_KEY=k5Gn9XCKA7qxjzlgBjN9Wiel1H3gQeaeR052Q7kgDPE
+
+# MCP Server Configuration (optional)
+MCP_SERVER_HOST=0.0.0.0
+MCP_SERVER_PORT=8100
+
+# Logging (optional)
+LOG_LEVEL=INFO

mem_brain_mcp-1.0.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.db
+*.sqlite
+*.sqlite3
+tmp/
+*.pkl
+*.pickle
+
+# Logs
+*.log
+
+
+
+

mem_brain_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mem-brain-mcp
+Version: 1.0.0
+Summary: MCP Server for Mem-Brain API - Exposes memory operations as MCP tools
+Keywords: ai,claude,cursor,llm,mcp,memory,model-context-protocol
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.10
+Requires-Dist: fastmcp<3.0.0,>=2.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mem-Brain MCP Server
+
+MCP (Model Context Protocol) server that exposes Mem-Brain API functionality as standardized tools for AI agents. Built with [FastMCP](https://gofastmcp.com) for production-ready HTTP/SSE transport.
+
+## Features
+
+- **Memory Management**: Create, read, update, and delete memories
+- **Semantic Search**: Search memories using vector similarity
+- **Graph Operations**: Find paths and neighborhoods in the memory graph
+- **Statistics**: Get insights about your memory system
+- **Link Management**: Link and unlink memories
+- **HTTP/SSE Transport**: Run independently, accessible remotely
+- **CLI Interface**: Packaged for easy global execution
+
+## Instant Execution (Recommended)
+
+You can run the MCP server instantly without manual installation using `uv`:
+
+```bash
+# Run using uvx (loads environment from .env or shell)
+uvx mem-brain-mcp
+
+# Run with custom API URL
+export API_BASE_URL=http://your-api-alb-url.com
+uvx mem-brain-mcp
+```
+
+## Installation
+
+### From Source
+
+1. Install using `uv` (recommended) or `pip`:
+
+```bash
+cd mem-brain-mcp
+uv pip install .
+```
+
+2. Run globally:
+
+```bash
+mem-brain-mcp
+```
+
+## Configuration
+
+The server reads configuration from environment variables or a `.env` file in the current working directory:
+
+```env
+# API Configuration
+API_BASE_URL=http://localhost:8000
+# NOTE: API_KEY is optional here - per-user API keys are configured in MCP clients
+API_KEY=your_api_key_here  # Optional: fallback for single-user scenarios
+
+# MCP Server Configuration
+MCP_SERVER_HOST=0.0.0.0
+MCP_SERVER_PORT=8100
+
+# Logging
+LOG_LEVEL=INFO
+```
+
+## Per-User API Key Configuration
+
+Each user must configure their own API key in their MCP client for proper user isolation. The server extracts tokens from request headers.
+
+### Cursor IDE (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "url": "http://localhost:8100/mcp",
+      "headers": {
+        "Authorization": "Bearer your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+#### Option 1: Native Remote (Pro/Team plans)
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "url": "http://your-deployed-url/mcp",
+      "headers": {
+        "Authorization": "Bearer your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: via CLI (Any plan)
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "command": "uvx",
+      "args": ["mem-brain-mcp"],
+      "env": {
+        "API_BASE_URL": "http://your-deployed-url",
+        "JWT_SECRET_KEY": "your-secret"
+      }
+    }
+  }
+}
+```
+
+## AWS ECS Deployment
+
+The MCP server can be deployed to AWS ECS (Fargate) with an Application Load Balancer.
+
+### Quick Start
+
+1. **Set up security groups** (see [aws/security-groups.md](./aws/security-groups.md))
+2. **Deploy using the script:**
+
+```bash
+cd mem-brain-mcp/aws
+./deploy.sh ap-south-1 membrain-mcp membrain-cluster membrain-mcp
+```
+
+For detailed instructions, see [aws/DEPLOYMENT.md](./aws/DEPLOYMENT.md).
+
+## Development
+
+### Running Tests
+```bash
+pytest
+```
+
+### Build and Publish
+```bash
+# Build the wheel
+python3 -m build
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## License
+
+Same as Mem-Brain API project.

mem_brain_mcp-1.0.0/README.md

@@ -0,0 +1,150 @@
+# Mem-Brain MCP Server
+
+MCP (Model Context Protocol) server that exposes Mem-Brain API functionality as standardized tools for AI agents. Built with [FastMCP](https://gofastmcp.com) for production-ready HTTP/SSE transport.
+
+## Features
+
+- **Memory Management**: Create, read, update, and delete memories
+- **Semantic Search**: Search memories using vector similarity
+- **Graph Operations**: Find paths and neighborhoods in the memory graph
+- **Statistics**: Get insights about your memory system
+- **Link Management**: Link and unlink memories
+- **HTTP/SSE Transport**: Run independently, accessible remotely
+- **CLI Interface**: Packaged for easy global execution
+
+## Instant Execution (Recommended)
+
+You can run the MCP server instantly without manual installation using `uv`:
+
+```bash
+# Run using uvx (loads environment from .env or shell)
+uvx mem-brain-mcp
+
+# Run with custom API URL
+export API_BASE_URL=http://your-api-alb-url.com
+uvx mem-brain-mcp
+```
+
+## Installation
+
+### From Source
+
+1. Install using `uv` (recommended) or `pip`:
+
+```bash
+cd mem-brain-mcp
+uv pip install .
+```
+
+2. Run globally:
+
+```bash
+mem-brain-mcp
+```
+
+## Configuration
+
+The server reads configuration from environment variables or a `.env` file in the current working directory:
+
+```env
+# API Configuration
+API_BASE_URL=http://localhost:8000
+# NOTE: API_KEY is optional here - per-user API keys are configured in MCP clients
+API_KEY=your_api_key_here  # Optional: fallback for single-user scenarios
+
+# MCP Server Configuration
+MCP_SERVER_HOST=0.0.0.0
+MCP_SERVER_PORT=8100
+
+# Logging
+LOG_LEVEL=INFO
+```
+
+## Per-User API Key Configuration
+
+Each user must configure their own API key in their MCP client for proper user isolation. The server extracts tokens from request headers.
+
+### Cursor IDE (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "url": "http://localhost:8100/mcp",
+      "headers": {
+        "Authorization": "Bearer your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+#### Option 1: Native Remote (Pro/Team plans)
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "url": "http://your-deployed-url/mcp",
+      "headers": {
+        "Authorization": "Bearer your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: via CLI (Any plan)
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "command": "uvx",
+      "args": ["mem-brain-mcp"],
+      "env": {
+        "API_BASE_URL": "http://your-deployed-url",
+        "JWT_SECRET_KEY": "your-secret"
+      }
+    }
+  }
+}
+```
+
+## AWS ECS Deployment
+
+The MCP server can be deployed to AWS ECS (Fargate) with an Application Load Balancer.
+
+### Quick Start
+
+1. **Set up security groups** (see [aws/security-groups.md](./aws/security-groups.md))
+2. **Deploy using the script:**
+
+```bash
+cd mem-brain-mcp/aws
+./deploy.sh ap-south-1 membrain-mcp membrain-cluster membrain-mcp
+```
+
+For detailed instructions, see [aws/DEPLOYMENT.md](./aws/DEPLOYMENT.md).
+
+## Development
+
+### Running Tests
+```bash
+pytest
+```
+
+### Build and Publish
+```bash
+# Build the wheel
+python3 -m build
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## License
+
+Same as Mem-Brain API project.

mem_brain_mcp-1.0.0/TROUBLESHOOTING.md

@@ -0,0 +1,140 @@
+# Troubleshooting Mem-Brain MCP Server
+
+## Common Issues
+
+### Issue: `add_memory` fails with "content parameter not being passed correctly"
+
+**Symptoms:**
+- Error message suggests parameters aren't formatted properly
+- Tool call fails even with valid content
+
+**Solutions:**
+
+1. **Ensure content is a string, not an object:**
+   ```python
+   # ✅ Correct
+   add_memory(content="I love Python programming")
+   
+   # ❌ Wrong - don't pass as object
+   add_memory({"content": "I love Python"})
+   ```
+
+2. **Use named parameters:**
+   ```python
+   # ✅ Correct
+   add_memory(
+       content="User prefers dark mode",
+       tags=["preferences", "ui"],
+       category="settings"
+   )
+   
+   # ⚠️ May work but not recommended
+   add_memory("User prefers dark mode", ["preferences"], "settings")
+   ```
+
+3. **Check parameter types:**
+   - `content`: Must be a **string** (required)
+   - `tags`: Must be a **list of strings** or `None` (optional)
+   - `category`: Must be a **string** or `None` (optional)
+
+4. **Example correct calls:**
+   ```python
+   # Minimal call
+   add_memory(content="User loves TypeScript")
+   
+   # With tags
+   add_memory(
+       content="User prefers Python over JavaScript",
+       tags=["coding", "preferences"]
+   )
+   
+   # Full call
+   add_memory(
+       content="User works primarily with backend systems",
+       tags=["coding", "backend"],
+       category="interests"
+   )
+   ```
+
+### Issue: Authentication errors
+
+**Symptoms:**
+- "Authentication failed" errors
+- "No authentication token provided"
+
+**Solutions:**
+
+1. **Make sure you've logged in:**
+   ```python
+   login(email="your@email.com", password="yourpassword")
+   ```
+
+2. **Or configure token in MCP client:**
+   ```json
+   {
+     "mcpServers": {
+       "mem-brain": {
+         "url": "http://localhost:8100/mcp",
+         "headers": {
+           "Authorization": "Bearer YOUR_JWT_TOKEN"
+         }
+       }
+     }
+   }
+   ```
+
+3. **Token expired?** Tokens expire after 30 minutes. Call `login` again.
+
+### Issue: Search returns no results
+
+**Possible causes:**
+- No memories match your query
+- Memories exist but don't match semantically
+- Try broader queries
+
+**Solutions:**
+- Try different search terms
+- Check if memories exist: `get_stats()`
+- Use `get_memories()` to see what's stored
+
+### Issue: Connection refused
+
+**Check:**
+1. API server is running: `curl http://localhost:8000/health`
+2. MCP server is running: `curl http://localhost:8100/health`
+3. Ports are correct in configuration
+
+## Debug Mode
+
+Enable debug logging to see what's happening:
+
+```bash
+export LOG_LEVEL=DEBUG
+uv run python -m mem_brain_mcp
+```
+
+This will show:
+- All tool calls with parameters
+- API requests and responses
+- Authentication details
+- Error stack traces
+
+## Testing Tools Manually
+
+You can test the API directly to verify it's working:
+
+```bash
+# Login
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com", "password": "TestPassword123"}'
+
+# Add memory (use token from login)
+curl -X POST http://localhost:8000/api/v1/memories \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{"content": "Test memory", "tags": ["test"]}'
+```
+
+If this works but MCP doesn't, the issue is in the MCP tool definition or parameter passing.
+