mzcache-mcp-server 0.1.0__py3-none-any.whl

mzcache_mcp/main.py

@@ -0,0 +1,735 @@
+import os
+import sys
+import asyncio
+import subprocess
+from pathlib import Path
+from mcp.server.models import InitializationOptions
+from mcp.server import NotificationOptions, Server
+import mcp.types as types
+from mcp.server.stdio import stdio_server
+
+# Import your client here. Assuming it's in a file called mzcache_client.py
+from mzcache import MzCacheClient, MzCacheConnectionError, MzCacheServerError
+
+# Configure the target location for your C++ Engine
+SERVER_HOST = "127.0.0.1"
+SERVER_PORT = 6379
+
+# Initialize the MCP Server
+server = Server("mzcache-engine-server")
+
+def execute_engine_cmd(func_name: str, *args, **kwargs) -> str:
+    """Helper to safely manage connection lifecycle for each tool invocation."""
+    client = MzCacheClient(host=SERVER_HOST, port=SERVER_PORT)
+    try:
+        with client as connected_client:
+            method = getattr(connected_client, func_name)
+            result = method(*args, **kwargs)
+            
+            # Map Python types elegantly for LLM clarity
+            if result is None:
+                return "nil (Key/Field not found)"
+            if isinstance(result, (set, list)):
+                return "\n".join(str(item) for item in result) if result else "(empty collection)"
+            return str(result)
+            
+    except MzCacheConnectionError as ce:
+        return f"Connection Error: Failed communicating with C++ Engine backend. {str(ce)}"
+    except MzCacheServerError as se:
+        return f"Engine Operational Error: {str(se)}"
+    except Exception as e:
+        return f"Internal Server Error: {str(e)}"
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """Exposes core data manipulation capability primitives to the LLM."""
+    return [
+        # --- STRINGS ---
+        types.Tool(
+            name="cache_set",
+            description="Stores a primitive key-value string pair inside mzcache.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "key": {"type": "string", "description": "The target identifier key."},
+                    "value": {"type": "string", "description": "The value payload to store."}
+                },
+                "required": ["key", "value"],
+            },
+        ),
+        types.Tool(
+            name="cache_get",
+            description="Retrieves a cached string value by key identifier.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "key": {"type": "string", "description": "The cache key to check."}
+                },
+                "required": ["key"],
+            },
+        ),
+        types.Tool(
+            name="cache_delete",
+            description="Evicts/removes an absolute key along with its payload data.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "key": {"type": "string", "description": "The key to purge."}
+                },
+                "required": ["key"],
+            },
+        ),
+
+        types.Tool(
+    name="cache_setnx",
+    description="Stores a value only if the key does not already exist.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "value": {"type": "string"}
+        },
+        "required": ["key", "value"],
+    },
+),
+
+types.Tool(
+    name="cache_mset",
+    description="Stores multiple key-value pairs in a single operation.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "mapping": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "string"
+                }
+            }
+        },
+        "required": ["mapping"],
+    },
+),
+
+types.Tool(
+    name="cache_mget",
+    description="Retrieves values for multiple keys.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "keys": {
+                "type": "array",
+                "items": {"type": "string"}
+            }
+        },
+        "required": ["keys"],
+    },
+),
+
+types.Tool(
+    name="cache_append",
+    description="Appends text to an existing string value.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "value": {"type": "string"}
+        },
+        "required": ["key", "value"],
+    },
+),
+
+types.Tool(
+    name="cache_strlen",
+    description="Returns the length of a stored string.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"}
+        },
+        "required": ["key"],
+    },
+),
+
+types.Tool(
+    name="cache_incr",
+    description="Atomically increments an integer value.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"}
+        },
+        "required": ["key"],
+    },
+),
+
+types.Tool(
+    name="cache_incrby",
+    description="Atomically increments an integer value by a specified amount.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "amount": {"type": "integer"}
+        },
+        "required": ["key", "amount"],
+    },
+),
+
+types.Tool(
+    name="cache_decr",
+    description="Atomically decrements an integer value.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"}
+        },
+        "required": ["key"],
+    },
+),
+
+types.Tool(
+    name="cache_decrby",
+    description="Atomically decrements an integer value by a specified amount.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "amount": {"type": "integer"}
+        },
+        "required": ["key", "amount"],
+    },
+),
+        
+        # --- LISTS ---
+        types.Tool(
+            name="cache_rpush",
+            description="Appends an element to the tail end of an active list queue.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "list_name": {"type": "string", "description": "Target list name."},
+                    "value": {"type": "string", "description": "Value to append."}
+                },
+                "required": ["list_name", "value"],
+            },
+        ),
+        types.Tool(
+            name="cache_lpop",
+            description="Removes and returns the frontmost element from a targeted list.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "list_name": {"type": "string", "description": "Target list name."}
+                },
+                "required": ["list_name"],
+            },
+        ),
+
+        types.Tool(
+    name="cache_lpush",
+    description="Prepends an element to a list.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"},
+            "value":{"type":"string"}
+        },
+        "required":["list_name","value"]
+    }
+),
+
+types.Tool(
+    name="cache_rpop",
+    description="Removes the last element of a list.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"}
+        },
+        "required":["list_name"]
+    }
+),
+
+types.Tool(
+    name="cache_llen",
+    description="Returns the length of a list.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"}
+        },
+        "required":["list_name"]
+    }
+),
+
+types.Tool(
+    name="cache_lindex",
+    description="Returns the value at a given list index.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"},
+            "index":{"type":"integer"}
+        },
+        "required":["list_name","index"]
+    }
+),
+
+types.Tool(
+    name="cache_lset",
+    description="Sets the value at a specified list index.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"},
+            "index":{"type":"integer"},
+            "value":{"type":"string"}
+        },
+        "required":["list_name","index","value"]
+    }
+),
+
+types.Tool(
+    name="cache_lsort",
+    description="Sorts a list in ascending or descending order.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"},
+            "order":{
+                "type":"string",
+                "enum":["ASC","DESC"]
+            }
+        },
+        "required":["list_name"]
+    }
+),
+
+types.Tool(
+    name="cache_lprint",
+    description="Returns a printable representation of a list.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "list_name":{"type":"string"}
+        },
+        "required":["list_name"]
+    }
+),
+
+        # --- SETS ---
+        types.Tool(
+            name="cache_sadd",
+            description="Inserts a unique item member inside an target collection set.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "set_name": {"type": "string", "description": "Target set identity name."},
+                    "member": {"type": "string", "description": "Unique string record value to insert."}
+                },
+                "required": ["set_name", "member"],
+            },
+        ),
+        types.Tool(
+            name="cache_smembers",
+            description="Returns all active elements tracked inside a selected Set collection.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "set_name": {"type": "string", "description": "Name of target set."}
+                },
+                "required": ["set_name"],
+            },
+        ),
+
+        types.Tool(
+    name="cache_srem",
+    description="Removes a member from a set.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set_name":{"type":"string"},
+            "member":{"type":"string"}
+        },
+        "required":["set_name","member"]
+    }
+),
+
+types.Tool(
+    name="cache_scard",
+    description="Returns the number of members in a set.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set_name":{"type":"string"}
+        },
+        "required":["set_name"]
+    }
+),
+
+types.Tool(
+    name="cache_spop",
+    description="Removes and returns a random member from a set.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set_name":{"type":"string"}
+        },
+        "required":["set_name"]
+    }
+),
+
+types.Tool(
+    name="cache_sismember",
+    description="Checks whether a member exists in a set.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set_name":{"type":"string"},
+            "member":{"type":"string"}
+        },
+        "required":["set_name","member"]
+    }
+),
+
+types.Tool(
+    name="cache_sunion",
+    description="Returns the union of two sets.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set1":{"type":"string"},
+            "set2":{"type":"string"}
+        },
+        "required":["set1","set2"]
+    }
+),
+
+types.Tool(
+    name="cache_sinter",
+    description="Returns the intersection of two sets.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set1":{"type":"string"},
+            "set2":{"type":"string"}
+        },
+        "required":["set1","set2"]
+    }
+),
+
+types.Tool(
+    name="cache_sdiff",
+    description="Returns the difference between two sets.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "set1":{"type":"string"},
+            "set2":{"type":"string"}
+        },
+        "required":["set1","set2"]
+    }
+),
+
+        # --- HASHES ---
+        types.Tool(
+            name="cache_hset",
+            description="Stores or replaces a mapping field parameter inside a specified complex Hash dictionary tracking name.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "hash_name": {"type": "string", "description": "Target hash grouping handle name."},
+                    "field": {"type": "string", "description": "The sub-key attribute dictionary name label."},
+                    "value": {"type": "string", "description": "String payload data assignment value."}
+                },
+                "required": ["hash_name", "field", "value"],
+            },
+        ),
+        types.Tool(
+            name="cache_hget",
+            description="Fetches properties of a targeted mapping attribute inside a specific Hash dictionary structure identifier.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "hash_name": {"type": "string", "description": "Hash map dictionary tracker parameter name."},
+                    "field": {"type": "string", "description": "Specific object attribute key parameter label to retrieve."}
+                },
+                "required": ["hash_name", "field"],
+            },
+        ),
+        types.Tool(
+    name="cache_hdel",
+    description="Deletes a field from a hash.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "hash_name":{"type":"string"},
+            "field":{"type":"string"}
+        },
+        "required":["hash_name","field"]
+    }
+),
+
+types.Tool(
+    name="cache_hexists",
+    description="Checks whether a field exists in a hash.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "hash_name":{"type":"string"},
+            "field":{"type":"string"}
+        },
+        "required":["hash_name","field"]
+    }
+),
+
+types.Tool(
+    name="cache_hlen",
+    description="Returns the number of fields in a hash.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "hash_name":{"type":"string"}
+        },
+        "required":["hash_name"]
+    }
+),
+
+        # --- TTL ---
+        types.Tool(
+            name="cache_expire",
+            description="Assigns a Time-To-Live countdown constraint configuration payload execution expiration window on a target key identifier.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "key": {"type": "string", "description": "Target tracking key element."},
+                    "seconds": {"type": "integer", "description": "Life cycle deadline period delay window sequence limit values calculated via standard seconds count."}
+                },
+                "required": ["key", "seconds"],
+            },
+        ),
+
+        types.Tool(
+    name="cache_ttl",
+    description="Returns the remaining TTL of a key.",
+    inputSchema={
+        "type":"object",
+        "properties":{
+            "key":{"type":"string"}
+        },
+        "required":["key"]
+    }
+),
+
+    ]
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: dict | None
+) -> list[types.TextContent]:
+    """Routes the requested tool execution securely down to the target client methods."""
+    args = arguments or {}
+    
+    # Simple explicit routing matrix logic mapping tool name hooks directly down to the python client interface methods
+    match name:
+        case "cache_set":
+            res = execute_engine_cmd("set", args["key"], args["value"])
+        case "cache_get":
+            res = execute_engine_cmd("get", args["key"])
+        case "cache_delete":
+            res = execute_engine_cmd("delete", args["key"])
+        case "cache_rpush":
+            res = execute_engine_cmd("rpush", args["list_name"], args["value"])
+        case "cache_lpop":
+            res = execute_engine_cmd("lpop", args["list_name"])
+        case "cache_sadd":
+            res = execute_engine_cmd("sadd", args["set_name"], args["member"])
+        case "cache_smembers":
+            res = execute_engine_cmd("smembers", args["set_name"])
+        case "cache_hset":
+            res = execute_engine_cmd("hset", args["hash_name"], args["field"], args["value"])
+        case "cache_hget":
+            res = execute_engine_cmd("hget", args["hash_name"], args["field"])
+        case "cache_expire":
+            res = execute_engine_cmd("expire", args["key"], int(args["seconds"]))
+        
+        case "cache_setnx":
+            res = execute_engine_cmd("setnx", args["key"], args["value"])
+
+        case "cache_mset":
+            res = execute_engine_cmd("mset", args["mapping"])
+
+        case "cache_mget":
+            res = execute_engine_cmd("mget", args["keys"])
+
+        case "cache_append":
+            res = execute_engine_cmd("append", args["key"], args["value"])
+
+        case "cache_strlen":
+            res = execute_engine_cmd("strlen", args["key"])
+
+        case "cache_incr":
+            res = execute_engine_cmd("incr", args["key"])
+
+        case "cache_incrby":
+            res = execute_engine_cmd("incrby", args["key"], int(args["amount"]))
+
+        case "cache_decr":
+            res = execute_engine_cmd("decr", args["key"])
+
+        case "cache_decrby":
+            res = execute_engine_cmd("decrby", args["key"], int(args["amount"]))
+
+        case "cache_lpush":
+            res = execute_engine_cmd("lpush", args["list_name"], args["value"])
+
+        case "cache_rpop":
+            res = execute_engine_cmd("rpop", args["list_name"])
+
+        case "cache_llen":
+            res = execute_engine_cmd("llen", args["list_name"])
+
+        case "cache_lindex":
+            res = execute_engine_cmd("lindex", args["list_name"], int(args["index"]))
+
+        case "cache_lset":
+            res = execute_engine_cmd(
+                "lset",
+                args["list_name"],
+                int(args["index"]),
+                args["value"],
+            )
+
+        case "cache_lsort":
+            res = execute_engine_cmd(
+                "lsort",
+                args["list_name"],
+                args.get("order", "ASC"),
+            )
+
+        case "cache_lprint":
+            res = execute_engine_cmd("lprint", args["list_name"])
+
+        case "cache_srem":
+            res = execute_engine_cmd("srem", args["set_name"], args["member"])
+
+        case "cache_scard":
+            res = execute_engine_cmd("scard", args["set_name"])
+
+        case "cache_spop":
+            res = execute_engine_cmd("spop", args["set_name"])
+
+        case "cache_sismember":
+            res = execute_engine_cmd(
+                "sismember",
+                args["set_name"],
+                args["member"],
+            )
+
+        case "cache_sunion":
+            res = execute_engine_cmd(
+                "sunion",
+                args["set1"],
+                args["set2"],
+            )
+
+        case "cache_sinter":
+            res = execute_engine_cmd(
+                "sinter",
+                args["set1"],
+                args["set2"],
+            )
+
+        case "cache_sdiff":
+            res = execute_engine_cmd(
+                "sdiff",
+                args["set1"],
+                args["set2"],
+            )
+
+        case "cache_hdel":
+            res = execute_engine_cmd(
+                "hdel",
+                args["hash_name"],
+                args["field"],
+            )
+
+        case "cache_hexists":
+            res = execute_engine_cmd(
+                "hexists",
+                args["hash_name"],
+                args["field"],
+            )
+
+        case "cache_hlen":
+            res = execute_engine_cmd("hlen", args["hash_name"])
+
+        case "cache_ttl":
+            res = execute_engine_cmd("ttl", args["key"])
+        case _:
+            raise ValueError(f"Unknown Tool String Requested: {name}")
+
+    return [types.TextContent(type="text", text=res)]
+
+def launch_backend_engine():
+    """Locates and executes the bundled C++ binary as a background child process."""
+    current_dir = Path(__file__).parent
+    
+    if sys.platform.startswith("linux"):
+        binary_path = current_dir / "bin" / "mzcache_engine_linux"
+    elif sys.platform == "darwin":
+        binary_path = current_dir / "bin" / "mzcache_engine_macos"
+    else:
+        print("Unsupported OS for native binary bundling.", file=sys.stderr)
+        return None
+
+    if not binary_path.exists():
+        print(f"Engine binary missing at: {binary_path}", file=sys.stderr)
+        return None
+
+    try:
+        # Ensure the binary has executable permissions (chmod +x)
+        os.chmod(binary_path, 0o755)
+        
+        # Spawn C++ Engine on port 6379 silently
+        # DEVNULL is critical so C++ stdout logs don't corrupt the MCP JSON stream!
+        process = subprocess.Popen(
+            [str(binary_path), "--port", "6379"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+        return process
+    except Exception as e:
+        print(f"Failed to automatically start C++ engine process: {e}", file=sys.stderr)
+        return None
+
+async def async_main():
+    # Spin up the C++ engine backend process automatically
+    engine_process = launch_backend_engine()
+    
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name="mzcache-engine-server",
+                    server_version="0.1.0",
+                    capabilities=server.get_capabilities(
+                        notification_options=NotificationOptions(),
+                        experimental_capabilities={},
+                    ),
+                ),
+            )
+    finally:
+        # Kill the C++ engine process cleanly when the MCP server shuts down
+        if engine_process:
+            engine_process.terminate()
+            engine_process.wait()
+
+def main():
+    asyncio.run(async_main())
+
+if __name__ == "__main__":
+    main()

mzcache_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mzcache-mcp-server
+Version: 0.1.0
+Summary: Model Context Protocol server for the MzCache C++ engine
+Author-email: Murtaza Baig <murtazabaig335@gmail.com>
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0

mzcache_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mzcache_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mzcache_mcp/main.py,sha256=1srJG47hEABGhN4VJO7yeX1RPY03gHwk4RnDgmA-PyQ,21891
+mzcache_mcp/bin/mzcache_engine_linux,sha256=8MfDh3X5uEgz3XEiRwx3QoUPqQD2Ukczzs699ojRdw4,667640
+mzcache_mcp_server-0.1.0.data/data/mzcache_mcp/bin/mzcache_engine_linux,sha256=8MfDh3X5uEgz3XEiRwx3QoUPqQD2Ukczzs699ojRdw4,667640
+mzcache_mcp_server-0.1.0.dist-info/METADATA,sha256=5DD3xSJQXVgj8ixYafEf6_Z1RNRHhY-ZNQB6IhsYylo,378
+mzcache_mcp_server-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mzcache_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=CxtP0lgwTA2I9ed9DvsLaElFlJsbzIn_U5knOYrcOzM,57
+mzcache_mcp_server-0.1.0.dist-info/RECORD,,

mzcache_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mzcache_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mzcache-server = mzcache_mcp.main:main