getme-mcp-server 1.0.1__tar.gz

getme_mcp_server-1.0.1/.gitignore

@@ -0,0 +1,155 @@
+
+# ---- Python (.gitignore) ----
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+Pipfile.lock
+
+# Poetry
+#   poetry.lock is generally recommended to commit.
+poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# PDM
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# IDE / editor caches (Python-related)
+.vscode/.ropeproject
+
+
+# hatch-vcs dynamic version file
+getme_mcp_server/_version.py

getme_mcp_server-1.0.1/Dockerfile

@@ -0,0 +1,28 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm AS builder
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock README.md ./
+
+RUN uv sync --frozen --no-dev
+
+COPY getme_mcp_server ./getme_mcp_server
+
+RUN uv pip install --python /app/.venv/bin/python --no-deps .
+
+
+# slim Python image, no uv
+FROM python:3.12-slim-bookworm AS runtime
+
+WORKDIR /app
+
+ENV PYTHONUNBUFFERED=1 \
+  GETME_BASE_URL=http://unix \
+  GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock \
+  PATH=/app/.venv/bin:$PATH
+
+COPY --from=builder /app/.venv /app/.venv
+
+COPY --from=builder /app/README.md /app/README.md
+
+ENTRYPOINT ["getme-mcp-server"]

getme_mcp_server-1.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: getme-mcp-server
+Version: 1.0.1
+Summary: MCP server for getMe (HTTP over Unix domain socket).
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# getMe MCP Server
+
+An MCP server that exposes `getMe` key-value operations as Model Context Protocol (MCP) tools, enabling LLMs to talk to the getMe core database over **HTTP via a Unix Domain Socket (UDS)**.
+
+<!-- mcp-name: io.github.aatirnadim/getme-mcp-server -->
+
+## 🔗 Quick Links
+
+- **GitHub Repository**: [AatirNadim/getMe](https://github.com/AatirNadim/getMe)
+- **PyPI Package**: [getme-mcp-server](https://pypi.org/project/getme-mcp-server/)
+- **Core Database Docs**: [Architecture & Deep Dive](https://github.com/AatirNadim/getMe/tree/main/server)
+- **DockerHub Image**: [getme](https://hub.docker.com/r/aatir0docking/getme)
+- **Blog Part I - Building getMe**: [Read here!](https://techtom.hashnode.dev/building-getme-i)
+- **Blog Part II - Building getMe**: [Read here!](https://techtom.hashnode.dev/building-getme-ii)
+
+## Using the MCP Server
+
+The `getme-mcp-server` package is published on PyPI. For integration with MCP-compatible clients like Claude Desktop, Cursor, or the MCP Inspector, you can seamlessly run it using `uvx` or `pipx`.
+
+### Claude Desktop Configuration
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "getme": {
+      "command": "uvx",
+      "args": ["getme-mcp-server"],
+      "env": {
+        "GETME_SOCKET_PATH": "/tmp/getMeStore/sockDir/getMe.sock",
+        "GETME_KEY_PREFIX": "agent-context:",
+        "GETME_READ_ONLY": "false"
+      }
+    }
+  }
+}
+```
+
+## Features & Safety
+
+- **Read-Only Mode:** Ensure LLMs don't mutate data via `GETME_READ_ONLY=true`.
+- **Destructive Operation Guards:** The `clear` tool is disabled by default, ensuring agents can't accidentally drop the store.
+- **Payload & Connection Limits:** Defends against massive payloads/batches and re-uses HTTP connections for performance.
+- **Prefix Isolation:** Restrict the LLM to a specific namespace in the DB with `GETME_KEY_PREFIX`.
+- **Masked Logging:** Tool execution metadata is logged, but payloads are masked to prevent leaking secrets.
+
+## Configuration (Environment Variables)
+
+Control safety rules and performance via environment variables.
+
+- `GETME_SOCKET_PATH` (default: `/tmp/getMeStore/sockDir/getMe.sock`): Path to the UNIX socket used by the core getMe daemon.
+- `GETME_READ_ONLY` (default: `false`): If `true`, only `get` and `get_json` tools are registered.
+- `GETME_ALLOW_CLEAR` (default: `false`): If `true`, enables the dangerous `clear` tool.
+- `GETME_KEY_PREFIX` (default: `""`): String prefix prepended to all keys. Sandboxes the LLM (e.g., `agent1:`).
+- `GETME_MAX_VALUE_SIZE_BYTES` (default: `5242880` / 5MB): Limit on single value payload sizes.
+- `GETME_MAX_BATCH_ITEMS` (default: `100`): Maximum keys processed in one `batch_put`.
+
+## Best Practices
+
+1. **Sandbox with Prefixes**: Always use `GETME_KEY_PREFIX` when handing the database over to an LLM. For instance, using `GETME_KEY_PREFIX="claude:"` ensures the model can't overwrite core application data.
+2. **Restrict Privileges**: If the agent only needs context (e.g., fetching RAG documents or reading app state), enforce `GETME_READ_ONLY=true`.
+3. **Never Allow Clear**: Keep `GETME_ALLOW_CLEAR=false` (the default) in production environments to prevent catastrophic drops caused by hallucinated commands.
+4. **Volume Mounts**: Make sure the environment running the MCP server has adequate read/write permissions to the `GETME_SOCKET_PATH`.
+
+## Tools
+
+Once connected, the LLM has access to the following operations:
+
+- `get(key) -> str`
+- `get_json(key) -> object`
+- `put(key, value) -> str`
+- `put_json(key, json_value) -> str`
+- `delete(key) -> str`
+- `clear() -> str` _(Requires `GETME_ALLOW_CLEAR=true`)_
+- `batch_put(pairs: object) -> object`
+- `batch_get(keys: list) -> object`
+- `batch_delete(keys: list) -> object`
+
+## Development & Installation
+
+### Prereqs
+
+- `uv` installed
+- `getMe` core server running and listening on the Unix socket
+
+### Install from Source
+
+```bash
+cd mcp-server
+uv sync
+```
+
+### Fixing VS Code "package not installed" warnings
+
+If Pylance shows warnings like `Package "httpx" is not installed in the selected environment`, VS Code is using a different Python interpreter than the `uv` virtualenv.
+
+- Open Command Palette → `Python: Select Interpreter`
+- Select: `getMe/mcp-server/.venv/bin/python`
+
+This repo also includes a workspace setting that points the interpreter at `mcp-server/.venv`.
+
+### Run Locally
+
+```bash
+cd mcp-server
+# optional override
+export GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock
+uv run getme-mcp-server
+```
+
+### Docker deployment
+
+This MCP server speaks **stdio** (JSON-RPC), so when running in Docker you must avoid allocating a TTY.
+
+Build the image:
+
+```bash
+cd mcp-server
+docker compose build
+```
+
+Run it over stdio (recommended for MCP clients):
+
+```bash
+cd mcp-server
+docker compose run --rm -T getme-mcp-server
+```
+
+The compose file bind-mounts the host UDS directory:
+
+- host: `/tmp/getMeStore/sockDir`
+- container: `/tmp/getMeStore/sockDir`
+
+So the MCP server can reach the core getMe server via `GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock`.

getme_mcp_server-1.0.1/README.md

@@ -0,0 +1,135 @@
+# getMe MCP Server
+
+An MCP server that exposes `getMe` key-value operations as Model Context Protocol (MCP) tools, enabling LLMs to talk to the getMe core database over **HTTP via a Unix Domain Socket (UDS)**.
+
+<!-- mcp-name: io.github.aatirnadim/getme-mcp-server -->
+
+## 🔗 Quick Links
+
+- **GitHub Repository**: [AatirNadim/getMe](https://github.com/AatirNadim/getMe)
+- **PyPI Package**: [getme-mcp-server](https://pypi.org/project/getme-mcp-server/)
+- **Core Database Docs**: [Architecture & Deep Dive](https://github.com/AatirNadim/getMe/tree/main/server)
+- **DockerHub Image**: [getme](https://hub.docker.com/r/aatir0docking/getme)
+- **Blog Part I - Building getMe**: [Read here!](https://techtom.hashnode.dev/building-getme-i)
+- **Blog Part II - Building getMe**: [Read here!](https://techtom.hashnode.dev/building-getme-ii)
+
+## Using the MCP Server
+
+The `getme-mcp-server` package is published on PyPI. For integration with MCP-compatible clients like Claude Desktop, Cursor, or the MCP Inspector, you can seamlessly run it using `uvx` or `pipx`.
+
+### Claude Desktop Configuration
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "getme": {
+      "command": "uvx",
+      "args": ["getme-mcp-server"],
+      "env": {
+        "GETME_SOCKET_PATH": "/tmp/getMeStore/sockDir/getMe.sock",
+        "GETME_KEY_PREFIX": "agent-context:",
+        "GETME_READ_ONLY": "false"
+      }
+    }
+  }
+}
+```
+
+## Features & Safety
+
+- **Read-Only Mode:** Ensure LLMs don't mutate data via `GETME_READ_ONLY=true`.
+- **Destructive Operation Guards:** The `clear` tool is disabled by default, ensuring agents can't accidentally drop the store.
+- **Payload & Connection Limits:** Defends against massive payloads/batches and re-uses HTTP connections for performance.
+- **Prefix Isolation:** Restrict the LLM to a specific namespace in the DB with `GETME_KEY_PREFIX`.
+- **Masked Logging:** Tool execution metadata is logged, but payloads are masked to prevent leaking secrets.
+
+## Configuration (Environment Variables)
+
+Control safety rules and performance via environment variables.
+
+- `GETME_SOCKET_PATH` (default: `/tmp/getMeStore/sockDir/getMe.sock`): Path to the UNIX socket used by the core getMe daemon.
+- `GETME_READ_ONLY` (default: `false`): If `true`, only `get` and `get_json` tools are registered.
+- `GETME_ALLOW_CLEAR` (default: `false`): If `true`, enables the dangerous `clear` tool.
+- `GETME_KEY_PREFIX` (default: `""`): String prefix prepended to all keys. Sandboxes the LLM (e.g., `agent1:`).
+- `GETME_MAX_VALUE_SIZE_BYTES` (default: `5242880` / 5MB): Limit on single value payload sizes.
+- `GETME_MAX_BATCH_ITEMS` (default: `100`): Maximum keys processed in one `batch_put`.
+
+## Best Practices
+
+1. **Sandbox with Prefixes**: Always use `GETME_KEY_PREFIX` when handing the database over to an LLM. For instance, using `GETME_KEY_PREFIX="claude:"` ensures the model can't overwrite core application data.
+2. **Restrict Privileges**: If the agent only needs context (e.g., fetching RAG documents or reading app state), enforce `GETME_READ_ONLY=true`.
+3. **Never Allow Clear**: Keep `GETME_ALLOW_CLEAR=false` (the default) in production environments to prevent catastrophic drops caused by hallucinated commands.
+4. **Volume Mounts**: Make sure the environment running the MCP server has adequate read/write permissions to the `GETME_SOCKET_PATH`.
+
+## Tools
+
+Once connected, the LLM has access to the following operations:
+
+- `get(key) -> str`
+- `get_json(key) -> object`
+- `put(key, value) -> str`
+- `put_json(key, json_value) -> str`
+- `delete(key) -> str`
+- `clear() -> str` _(Requires `GETME_ALLOW_CLEAR=true`)_
+- `batch_put(pairs: object) -> object`
+- `batch_get(keys: list) -> object`
+- `batch_delete(keys: list) -> object`
+
+## Development & Installation
+
+### Prereqs
+
+- `uv` installed
+- `getMe` core server running and listening on the Unix socket
+
+### Install from Source
+
+```bash
+cd mcp-server
+uv sync
+```
+
+### Fixing VS Code "package not installed" warnings
+
+If Pylance shows warnings like `Package "httpx" is not installed in the selected environment`, VS Code is using a different Python interpreter than the `uv` virtualenv.
+
+- Open Command Palette → `Python: Select Interpreter`
+- Select: `getMe/mcp-server/.venv/bin/python`
+
+This repo also includes a workspace setting that points the interpreter at `mcp-server/.venv`.
+
+### Run Locally
+
+```bash
+cd mcp-server
+# optional override
+export GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock
+uv run getme-mcp-server
+```
+
+### Docker deployment
+
+This MCP server speaks **stdio** (JSON-RPC), so when running in Docker you must avoid allocating a TTY.
+
+Build the image:
+
+```bash
+cd mcp-server
+docker compose build
+```
+
+Run it over stdio (recommended for MCP clients):
+
+```bash
+cd mcp-server
+docker compose run --rm -T getme-mcp-server
+```
+
+The compose file bind-mounts the host UDS directory:
+
+- host: `/tmp/getMeStore/sockDir`
+- container: `/tmp/getMeStore/sockDir`
+
+So the MCP server can reach the core getMe server via `GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock`.

getme_mcp_server-1.0.1/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  getme-mcp-server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: getme-mcp-server:local
+
+    # the getMe core server over UDS (HTTP over Unix domain socket).
+    volumes:
+      - /tmp/getMeStore/sockDir:/tmp/getMeStore/sockDir
+
+    environment:
+      GETME_SOCKET_PATH: /tmp/getMeStore/sockDir/getMe.sock
+      GETME_BASE_URL: http://unix
+
+    stdin_open: true
+    tty: false
+
+    restart: "no"

getme_mcp_server-1.0.1/getme_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0-dev"

getme_mcp_server-1.0.1/getme_mcp_server/__main__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import sys
+
+from .server import build_mcp
+
+from .utills import _install_graceful_shutdown_handlers
+
+
+def main() -> int:
+    _install_graceful_shutdown_handlers()
+    mcp = build_mcp()
+
+    try:
+        print("Starting MCP server...")
+        mcp.run()
+        return 0
+    except (KeyboardInterrupt, SystemExit):
+        # quite shutdown in case of interrupts
+        return 0
+    except BrokenPipeError:
+        # treating broken pipe as a normal exit
+        return 0
+    finally:
+        try:
+            sys.stdout.flush()
+        except Exception:
+            pass
+        try:
+            sys.stderr.flush()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

getme_mcp_server-1.0.1/getme_mcp_server/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.1'
+__version_tuple__ = version_tuple = (1, 0, 1)
+
+__commit_id__ = commit_id = None