{"id":47936645,"url":"https://github.com/tangle-network/mem0-mcp-blueprint","last_synced_at":"2026-04-04T07:44:32.380Z","repository":{"id":314521666,"uuid":"1053324580","full_name":"tangle-network/mem0-mcp-blueprint","owner":"tangle-network","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-09T09:43:41.000Z","size":818,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T07:44:30.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tangle-network.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T09:41:28.000Z","updated_at":"2025-09-15T12:42:39.000Z","dependencies_parsed_at":"2025-09-13T01:10:32.229Z","dependency_job_id":"c924f550-f53c-46c3-a48c-d318ab0fb22c","html_url":"https://github.com/tangle-network/mem0-mcp-blueprint","commit_stats":null,"previous_names":["tangle-network/mem0-blueprint-template","tangle-network/mem0-mcp-blueprint"],"tags_count":0,"template":false,"template_full_name":"tangle-network/blueprint-template","purl":"pkg:github/tangle-network/mem0-mcp-blueprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tangle-network%2Fmem0-mcp-blueprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tangle-network%2Fmem0-mcp-blueprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tangle-network%2Fmem0-mcp-blueprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tangle-network%2Fmem0-mcp-blueprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tangle-network","download_url":"https://codeload.github.com/tangle-network/mem0-mcp-blueprint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tangle-network%2Fmem0-mcp-blueprint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T07:44:31.700Z","updated_at":"2026-04-04T07:44:32.367Z","avatar_url":"https://github.com/tangle-network.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Blueprint for Tangle Network 🌐\n\n## � Project Overview \u0026 Purpose\n\nThis project is a blueprint for Tangle Network, designed to run remote MCPs (Model Context Protocol) services. When requesting a new instance of this blueprint, users get a new service instance with a specified configuration file that enables seamless MCP server deployment and management.\n\nBlueprints are specifications for \u003cabbr title=\"Actively Validated Services\"\u003eAVS\u003c/abbr\u003es on the Tangle Network. An AVS is an off-chain service that runs arbitrary computations for a user-specified period of time. This MCP Blueprint provides a powerful abstraction for deploying and managing MCP servers across different runtime environments, allowing developers to create reusable MCP service infrastructures.\n\nFor more details about Tangle Network Blueprints, please refer to the [project documentation](https://docs.tangle.tools/developers/blueprints/introduction).\n\n## ⚙️ Configuration Details\n\nThe blueprint supports configurations for various runtimes with automatic port management. All runtimes are internally converted to SSE (Server-Sent Events) for HTTP-based communication:\n\n### Supported Runtimes\n\n- **STDIO transport in JavaScript (bun runtime)**: Executes MCP servers using `bunx` with automatic bun installation if needed\n- **STDIO transport in Python (python3)**: Executes MCP servers using `uvx` with automatic uv installation if needed\n- **Docker containers**: Runs MCP servers in Docker containers with intelligent port discovery, automatic port allocation, and environment variable injection\n- **Mem0 Memory Server**: Self-hosted mem0 memory layer with PostgreSQL (pgvector), Neo4j graph database, and optional OpenMemory MCP server using Docker Compose\n\n### Port Management \u0026 Transport Conversion\n\nThe blueprint automatically manages port allocation and converts all runtime configurations to SSE transport:\n\n**Automatic Port Management:**\n\n- Ports are automatically allocated using the system's available port detection\n- The `PORT` environment variable is automatically injected into all MCP servers\n- MCP servers **must** bind to the port specified in the `PORT` environment variable\n- No manual port configuration required in blueprint requests\n\n**Transport Conversion:**\n\n- HTTP-based communication for web clients\n- Bidirectional message forwarding between STDIO and SSE transports\n- Real-time streaming via Server-Sent Events\n- POST endpoint for client message submission\n\n## 🔐 Authentication Workflow\n\nThe authentication workflow uses the script [`generate-auth-token.ts`](generate-auth-token.ts) to generate an access token through a challenge-response mechanism:\n\n1. **Challenge Request**: Client sends public key and key type to `/v1/auth/challenge`\n2. **Challenge Response**: Server returns a cryptographic challenge with expiration\n3. **Signature Generation**: Client signs the challenge using their private key\n4. **Token Verification**: Client submits signature to `/v1/auth/verify` endpoint\n5. **Access Token**: Server returns a time-limited access token\n\nAuthentication is performed via an `Authorization` header when accessing the MCP server URL. The token format is `{token_id}|{token_string}`.\n\n## 📋 Changelog \u0026 Breaking Changes\n\n**⚠️ Breaking Changes**: Recent updates introduce automatic port management. See [`CHANGELOG.md`](CHANGELOG.md) for detailed migration instructions and examples.\n\n**Key Changes:**\n\n- Removed `portBindings` field from configuration\n- Added automatic `PORT` environment variable injection\n- MCP servers must now read port from `PORT` environment variable\n\n## 🚀 Usage Examples \u0026 Demos\n\n### Sample Configurations\n\nThe [`fixtures`](fixtures) directory contains sample configurations for different runtime types:\n\n- **[`fixtures/00_mcp_python3.json`](fixtures/00_mcp_python3.json)**: Python MCP server configuration\n- **[`fixtures/01_mcp_js.json`](fixtures/01_mcp_js.json)**: JavaScript MCP server with Context7 package\n- **[`fixtures/02_mcp_local_docker.json`](fixtures/02_mcp_local_docker.json)**: Local Docker MCP server with Redis environment\n- **[`fixtures/03_tangle_mcp_docker.json`](fixtures/03_tangle_mcp_docker.json)**: Tangle-specific Docker MCP configuration\n- **[`fixtures/04_mem0_basic.json`](fixtures/04_mem0_basic.json)**: Basic mem0 memory server configuration with MCP server enabled\n- **[`fixtures/05_mem0_custom.json`](fixtures/05_mem0_custom.json)**: Custom mem0 configuration with different ports and database settings\n- **[`fixtures/06_mem0_api_only.json`](fixtures/06_mem0_api_only.json)**: Mem0 API server only (without OpenMemory MCP server)\n\n\u003e **Note**: All sample configurations use the new format without `portBindings`. Port allocation is handled automatically by the blueprint.\n\n### Local Setup\n\nTo run the setup locally, follow the detailed instructions in [`DEMO.md`](DEMO.md). The demo covers:\n\n1. Starting Tangle network locally\n2. Spawning the blueprint service\n3. Requesting a new blueprint instance\n4. Accepting the service request\n5. Starting the MCP server\n6. Generating authentication tokens\n7. Testing with MCP Inspector\n\n### Internal Workflow\n\nFor a detailed understanding of the internal workflow, see [`mcp-blueprint-flowchart.md`](mcp-blueprint-flowchart.md), which provides a comprehensive flowchart showing:\n\n- User request flow and configuration processing\n- Runtime detection and package management\n- Transport conversion from STDIO to SSE\n- Server initialization and endpoint provision\n- Authentication and client connection handling\n\n## 🔄 Workflow Description\n\nThe blueprint process follows this high-level workflow:\n\n1. **Request Reception**: Receives a remote MCP request with configuration parameters\n2. **Configuration Processing**: Analyzes runtime type, package/image, and environment variables\n3. **Port Allocation**: Automatically allocates an available port and injects it as `PORT` environment variable\n4. **Runtime Initialization**:\n   - **Python**: Installs/uses `uv` for package management and execution\n   - **JavaScript**: Installs/uses `bun` for package management and execution\n   - **Docker**: Pulls images, inspects for exposed ports, and creates containers with intelligent port binding\n   - **Mem0**: Creates Docker Compose configuration and starts PostgreSQL, Neo4j, and mem0 API services with optional OpenMemory MCP server\n5. **Transport Setup**: Converts STDIO communication to SSE for HTTP compatibility\n6. **Endpoint Exposure**: Provides HTTP URL with `/sse` and `/message` endpoints\n7. **Authentication**: Secures access through token-based authentication system\n8. **Client Interaction**: Enables MCP clients to connect and communicate via HTTP/SSE\n\n## 📋 Prerequisites\n\nBefore you can run this project, you will need to have the following software installed on your machine:\n\n- [Rust](https://www.rust-lang.org/tools/install)\n- [Forge](https://getfoundry.sh)\n- [Node.js](https://nodejs.org/) (for running the authentication token generator)\n- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) (required for mem0 runtime)\n\nYou will also need to install [cargo-tangle](https://crates.io/crates/cargo-tangle), our CLI tool for creating and deploying Tangle Blueprints:\n\nTo install the Tangle CLI, run the following command:\n\n\u003e Supported on Linux, MacOS, and Windows (WSL2)\n\n```bash\ncargo install cargo-tangle --git https://github.com/tangle-network/blueprint\n```\n\n## ✨ Key Features\n\n### Automatic Port Management\n\n- **Zero Configuration**: No need to specify port bindings in configuration files\n- **Conflict Prevention**: Automatic port allocation prevents port conflicts\n- **Environment Injection**: `PORT` environment variable automatically provided to MCP servers\n- **Universal Compatibility**: Works across all runtime types (Python, JavaScript, Docker)\n- **Intelligent Docker Handling**: Automatically discovers exposed ports from Docker images and configures port mapping only when needed\n\n### Enhanced Security \u0026 Reliability\n\n- **Simplified Configuration**: Reduced attack surface through automatic port management\n- **Process Lifecycle**: Proper cleanup and container management\n- **Error Handling**: Comprehensive error handling for port allocation failures\n\n## 🛠️ Development\n\nOnce you have the prerequisites installed, you can build and deploy the project:\n\n```sh\ncargo build\n```\n\nto build the project, and\n\n```sh\ncargo tangle blueprint deploy\n```\n\nto deploy the blueprint to the Tangle network.\n\n### Quick Reference for MCP Server Developers\n\nWhen developing MCP servers for this blueprint:\n\n1. **Read Port from Environment**: Always use `process.env.PORT` (JS) or `os.environ['PORT']` (Python)\n2. **Bind to All Interfaces**: Use `0.0.0.0` or `127.0.0.1` as the host\n3. **No Port Configuration**: Remove any hardcoded ports from your server\n4. **Test Locally**: Set `PORT=3000` environment variable for local testing\n\n```bash\n# Testing your MCP server locally\nexport PORT=3000\nyour-mcp-server-command\n```\n\n## 🧠 Mem0 Memory Server\n\nThe mem0 runtime provides a self-hosted memory layer for AI assistants with persistent, contextual memory capabilities.\n\n### Architecture\n\nThe mem0 runtime deploys a complete memory infrastructure using Docker Compose:\n\n- **PostgreSQL with pgvector**: Vector database for storing embeddings and semantic search\n- **Neo4j**: Graph database for relationship-based memory storage\n- **Mem0 API Server**: REST API for memory operations (add, search, update, delete memories)\n- **OpenMemory MCP Server** (optional): MCP-compatible interface for tools like Cursor and Claude Desktop\n\n### Configuration\n\nMem0 requires additional configuration parameters in the `mem0Config` field:\n\n```json\n{\n  \"config\": {\n    \"runtime\": \"mem0\",\n    \"package\": \"mem0ai/mem0:latest\",\n    \"mem0Config\": {\n      \"openaiApiKey\": \"your-openai-api-key\",\n      \"enableMcpServer\": true,\n      \"postgresConfig\": {\n        \"database\": \"mem0\",\n        \"user\": \"mem0user\", \n        \"password\": \"mem0pass\",\n        \"port\": 5432\n      },\n      \"neo4jConfig\": {\n        \"user\": \"neo4j\",\n        \"password\": \"mem0pass\",\n        \"port\": 7687\n      },\n      \"apiConfig\": {\n        \"port\": 8888,\n        \"host\": \"0.0.0.0\"\n      }\n    }\n  }\n}\n```\n\n### Key Features\n\n- **Persistent Memory**: Memories are stored across sessions and survive restarts\n- **Semantic Search**: Find relevant memories using natural language queries\n- **Graph Relationships**: Understand connections between different pieces of information\n- **MCP Integration**: Compatible with MCP clients for seamless integration\n- **REST API**: Full HTTP API for programmatic memory management\n\n### Memory Operations\n\nThe mem0 server supports standard memory operations:\n\n- `POST /memories` - Add new memories\n- `GET /memories` - List all memories\n- `GET /memories/search` - Search memories by query\n- `PUT /memories/{id}` - Update existing memory\n- `DELETE /memories/{id}` - Delete memory\n- `DELETE /memories` - Clear all memories\n\n### Usage with MCP Clients\n\nWhen `enableMcpServer` is true, the OpenMemory MCP server is available for MCP clients:\n\n1. Connect to the SSE endpoint: `http://your-endpoint/sse`\n2. Use the message endpoint: `http://your-endpoint/message`\n3. Authenticate using the blueprint's token system\n4. Access memory operations through MCP protocol\n\n## 📜 License\n\nLicensed under either of\n\n- Apache License, Version 2.0\n  ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license\n  ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## 📬 Feedback and Contributions\n\nWe welcome feedback and contributions to improve this blueprint.\nPlease open an issue or submit a pull request on our GitHub repository.\nPlease let us know if you fork this blueprint and extend it too!\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftangle-network%2Fmem0-mcp-blueprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftangle-network%2Fmem0-mcp-blueprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftangle-network%2Fmem0-mcp-blueprint/lists"}