mcp-server-evolutiondb 1.1.0__py3-none-any.whl

mcp_server_evolutiondb-1.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: mcp-server-evolutiondb
+Version: 1.1.0
+Summary: MCP (Model Context Protocol) server backed by EvolutionDB — gives Claude Desktop / Claude Code persistent long-term memory.
+Author-email: alptekin topal <topal.alptekin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alptekin/evolutiondb
+Project-URL: Documentation, https://alptekin.github.io/evolutiondb/
+Project-URL: Repository, https://github.com/alptekin/evolutiondb
+Project-URL: Issues, https://github.com/alptekin/evolutiondb/issues
+Project-URL: Source, https://github.com/alptekin/evolutiondb/tree/main/client/mcp-server-evosql
+Keywords: mcp,model-context-protocol,evolutiondb,claude,claude-desktop,claude-code,long-term-memory,agent-memory
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: psycopg[binary]>=3.1
+
+# mcp-server-evolutiondb
+
+<!-- mcp-name: io.github.alptekin/evolutiondb-memory -->
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server
+that gives Claude Desktop / Claude Code persistent **long-term
+memory** backed by EvolutionDB. Anything Claude decides to remember
+during a conversation is written to a real database; in any future
+session — same window or weeks later — Claude can search it back
+without you having to repaste context.
+
+## Install
+
+```bash
+pipx install mcp-server-evolutiondb
+# or:  pip install --user mcp-server-evolutiondb
+```
+
+The package installs the `mcp-server-evolutiondb` console entry-point
+(also aliased as `mcp-server-evosql`). It speaks the PostgreSQL wire
+protocol over `psycopg`, so installation is **pure-Python** — no C
+toolchain, no `libevosql-memory.so` to build. EvolutionDB still has
+to be running somewhere reachable; `docker compose up -d` in the
+[main repo](https://github.com/alptekin/evolutiondb) is the easiest
+way.
+
+```
+   ┌──────────────────┐         ┌─────────────────────┐         ┌────────────────┐
+   │  Claude Desktop  │  stdio  │  mcp-server-evosql  │  TCP    │   EvolutionDB  │
+   │   (or Claude     │ ◀──────▶│  (this package)     │ ◀──────▶│  (port 9967)   │
+   │     Code)        │  JSON-  │                     │         │                │
+   │                  │   RPC    │  save_memory       │         │ MEMORY STORE   │
+   │                  │   2.0    │  search_memory     │         │ ENTITY STORE   │
+   │                  │          │  recent_memories   │         │                │
+   │                  │          │  forget            │         │                │
+   │                  │          │  list_tags         │         │                │
+   └──────────────────┘          └─────────────────────┘         └────────────────┘
+```
+
+## Why
+
+The default Claude experience is **stateless** — every new chat starts
+from scratch, so you waste tokens re-explaining who you are, what
+project you're on, what your preferences are. Plug this server in
+and the model:
+
+- saves preferences / decisions / facts during natural conversation,
+- searches them back the next time you ask something related,
+- forgets entries on demand,
+- never sees the user_id that pins the namespace (we override it
+  server-side, so the model can't accidentally fragment the
+  namespace by inventing IDs across sessions).
+
+Token math: 100 chats × 3,000 tokens of pre-loaded context (~$0.90
+on Sonnet) → 100 chats × ~250 tokens of just-relevant facts pulled
+on demand (~$0.26). Roughly **3.5× cheaper inputs** without losing
+context fidelity.
+
+## What's exposed to Claude
+
+Five tools, all under one `evolutiondb-memory` MCP server:
+
+| Tool                | Purpose                                          |
+|---------------------|--------------------------------------------------|
+| `save_memory`        | Persist a fact + optional tags                   |
+| `search_memory`      | Substring + tag search (use before answering)    |
+| `recent_memories`    | Last N saved facts (most-recent-first)           |
+| `forget`             | Delete by key                                    |
+| `list_tags`          | All distinct tags in use, with counts            |
+
+Each call's `user_id` is overridden server-side from the
+`MCP_USER_ID` env var — stops the model from drifting the namespace
+across "user" / "default_user" / your name etc.
+
+## Install + run
+
+**1. Bring up EvolutionDB**
+
+```bash
+cd /path/to/evolutiondb
+docker compose up -d
+```
+
+**2. Build the SDK once**
+
+```bash
+make -C client/libevosql-memory
+```
+
+**3. Configure Claude Desktop**
+
+Open the config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Drop in the entry from
+[`examples/claude_desktop_config.json`](examples/claude_desktop_config.json),
+substituting the absolute paths for your machine. Quit + restart
+Claude Desktop.
+
+You'll see a small 🔌 / hammer icon in the bottom-right of the
+chat composer once `evolutiondb-memory` is connected.
+
+**4. Talk normally**
+
+Say "remember that I take my espresso single-shot, no sugar"; Claude
+will run `save_memory(...)`. Days later open a new chat, ask "what
+do I drink?" — Claude runs `search_memory(...)` and recalls.
+
+## Same setup for Claude Code
+
+If you use Claude Code (the CLI), drop the same `mcpServers` entry
+into `~/.claude/mcp.json`:
+
+```bash
+mkdir -p ~/.claude
+cp client/mcp-server-evosql/examples/claude_desktop_config.json ~/.claude/mcp.json
+# edit the absolute paths
+```
+
+Claude Code picks it up automatically on the next `claude` invocation.
+
+## Configuration
+
+| Env var               | Default            | Purpose |
+|-----------------------|--------------------|---------|
+| `EVOSQL_HOST`          | `127.0.0.1`        | DB host |
+| `EVOSQL_PORT`          | `9967`             | EVO port |
+| `EVOSQL_USER`          | `admin`            | DB user |
+| `EVOSQL_PASSWORD`      | `admin`            | DB password |
+| `MCP_USER_ID`          | `default_user`     | Sticky namespace for every tool call |
+| `MCP_STORE_PREFIX`     | `mcp`              | Catalog object prefix |
+| `EVOSQL_PYTHON_SDK`    | (auto-discovered)  | Override path to the Python ctypes binding |
+| `EVOSQL_MEMORY_LIB`    | (auto-discovered)  | Override path to libevosql-memory.dylib/so |
+
+## Tests
+
+```bash
+cd client/mcp-server-evosql
+python3 tests/test_mcp.py
+```
+
+Eight cases — initialize handshake, tools/list discovery, save+search
+round-trip, tag-filtered search, recent ordering, forget, list_tags
+aggregation, and the "user_id can't be hijacked from the LLM side"
+isolation case. Each test spawns the server as a real subprocess and
+talks JSON-RPC, so framing bugs that an in-process unit test would
+hide get caught.
+
+## Inspect the database directly
+
+While Claude is using the server, open another terminal and:
+
+```bash
+docker compose exec evosql evosql-cli -W admin
+```
+
+Then:
+
+```sql
+SELECT mem_namespace, mem_key, mem_value FROM __mem_mcp_mem;
+ENTITY RANK FROM mcp_ents;
+```
+
+Everything Claude has decided to remember is right there as
+queryable rows — no opaque blob storage.
+
+## Wire format
+
+Newline-delimited JSON-RPC 2.0 over stdio (no Content-Length
+headers — that's the LSP variant; MCP uses plain `\n`-delimited).
+The server speaks protocol version `2024-11-05`.
+
+```
+{"jsonrpc":"2.0","id":1,"method":"initialize",
+ "params":{"protocolVersion":"2024-11-05","capabilities":{}}}
+
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+
+{"jsonrpc":"2.0","id":3,"method":"tools/call",
+ "params":{"name":"save_memory",
+           "arguments":{"fact":"loves jazz","tags":["preference"]}}}
+```
+
+Errors come back as `{"jsonrpc":"2.0","id":N,"error":{"code":..,"message":..}}`
+or as a `tools/call` result with `isError: true`.
+
+## Known limitations
+
+- **Single-process EvolutionDB connection.** The server holds one
+  Connection — the SDK contract is one-per-thread, and MCP stdio is
+  inherently single-threaded so this is fine.
+- **No streaming responses.** Tool results return as single JSON
+  blobs. Larger memories (>100 facts) take ~50 ms to serialise; the
+  protocol can stream but Claude's tool-use UI doesn't render
+  partial responses anyway.
+- **Authentication via env-vars only.** If you expose the server to
+  another machine (which you shouldn't — it's stdio), set
+  `EVOSQL_PASSWORD` accordingly. The server doesn't rotate secrets.

mcp_server_evolutiondb-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_server_evosql/__init__.py,sha256=LCJ7j9SPR2PfVAGVkxe5u2KyBORREfe4QBlT2Z0n4rA,84
+mcp_server_evosql/__main__.py,sha256=DKoUu5zWvBGoul6cWpjMXZ6pdXXUuBgjLQRpFsw0S-0,110
+mcp_server_evosql/server.py,sha256=KCcVE5BRyoFgivl-5aUmSEqtRjKSlqBlyJ2NLqrElNA,16145
+mcp_server_evolutiondb-1.1.0.dist-info/METADATA,sha256=3K0KaoVl1alOMK8TdDHxLrlv2fNMqTXouX3qjQ1WaAY,9274
+mcp_server_evolutiondb-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_server_evolutiondb-1.1.0.dist-info/entry_points.txt,sha256=AT_7a8l_YHfO73yfns9iKqHBHD4fUObn0WRMPySHrbI,127
+mcp_server_evolutiondb-1.1.0.dist-info/top_level.txt,sha256=VYvE5FXJRj7fDLw1ZQ--e0oW6_3xXF7-sWviQctI2xg,18
+mcp_server_evolutiondb-1.1.0.dist-info/RECORD,,

mcp_server_evolutiondb-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_server_evolutiondb-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mcp-server-evolutiondb = mcp_server_evosql.__main__:main
+mcp-server-evosql = mcp_server_evosql.__main__:main

mcp_server_evolutiondb-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server_evosql

mcp_server_evosql/__init__.py

@@ -0,0 +1,2 @@
+"""mcp-server-evosql — MCP server backed by EvolutionDB."""
+__version__ = "1.0.0"

mcp_server_evosql/__main__.py

@@ -0,0 +1,5 @@
+"""python -m mcp_server_evosql entrypoint."""
+from .server import main
+
+if __name__ == "__main__":
+    main()

mcp_server_evosql/server.py

@@ -0,0 +1,430 @@
+"""
+mcp_server_evosql.server — JSON-RPC 2.0 stdio loop that exposes
+EvolutionDB-backed long-term memory to Claude Desktop / Claude Code
+through the MCP (Model Context Protocol) standard.
+
+Protocol surface implemented:
+  - initialize             — handshake, advertises tools capability
+  - tools/list             — describes the five memory tools
+  - tools/call             — dispatches to save / search / recent /
+                              forget / list_tags
+  - notifications/initialized (incoming, no response needed)
+  - shutdown / exit        — clean teardown
+
+Threading: MCP stdio is single-threaded. Every request is processed
+in order, so the underlying psycopg connection stays inside one
+event loop.
+
+User isolation: every tool call has its `user_id` server-side
+overridden to MCP_USER_ID env (default "default_user"). This is the
+sticky-id trick — keeps the LLM from fragmenting the namespace
+across "user" / "default_user" / the user's actual name etc.
+
+Backend: speaks the PostgreSQL wire protocol (port 5433) over psycopg.
+This avoids having to ship a compiled C library on PyPI; psycopg has
+pre-built binary wheels on every platform. EvolutionDB's PG adaptor
+parses the same MEMORY DDL/DML the EVO native protocol does.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import traceback
+import uuid
+from typing import Any, Dict, List, Optional
+
+
+PROTOCOL_VERSION = "2024-11-05"          # MCP version we speak
+SERVER_NAME      = "evolutiondb-memory"
+SERVER_VERSION   = "1.1.0"
+
+
+# ---------------------------------------------------------------- #
+#  Memory backend — speaks EvolutionDB over psycopg / PG wire.       #
+# ---------------------------------------------------------------- #
+def _e(s: str) -> str:
+    """Escape a value for inline SQL.
+
+    The MEMORY DDL/DML doesn't take parameters in the EVO grammar,
+    so we have to inline. We strip control bytes and double up
+    apostrophes — same defensive shape as the upstream Python SDK.
+    """
+    if not isinstance(s, str):
+        s = str(s)
+    s = s.replace("\r", " ").replace("\n", " ").replace("\t", " ")
+    return s.replace("'", "''")
+
+
+class MemoryBackend:
+    def __init__(self, host: str, port: int, user: str, password: str,
+                  database: str, prefix: str):
+        try:
+            import psycopg
+        except ImportError as exc:
+            raise RuntimeError(
+                "mcp-server-evosql requires psycopg. "
+                "Install with `pip install 'mcp-server-evosql'` "
+                "or `pip install psycopg[binary]>=3.1`."
+            ) from exc
+
+        self.psycopg = psycopg
+        self.conn = psycopg.connect(
+            host=host, port=port, user=user, password=password,
+            dbname=database, autocommit=True,
+        )
+        self.memory   = f"{prefix}_mem"
+        self.entities = f"{prefix}_ents"
+        # Idempotent CREATE — the server must not lose data across
+        # restarts. Both objects already exist on second start, the
+        # error is silently swallowed.
+        for kind, name in [
+            ("MEMORY STORE", self.memory),
+            ("ENTITY STORE", self.entities),
+        ]:
+            try:
+                with self.conn.cursor() as cur:
+                    cur.execute(f"CREATE {kind} {name}")
+            except Exception:
+                pass
+
+    # -- helpers ------------------------------------------------------
+    def _exec(self, sql: str) -> None:
+        with self.conn.cursor() as cur:
+            cur.execute(sql)
+
+    def _query(self, sql: str) -> List[List[str]]:
+        with self.conn.cursor() as cur:
+            cur.execute(sql)
+            try:
+                return [list(map(_to_str, row)) for row in cur.fetchall()]
+            except self.psycopg.ProgrammingError:
+                return []
+
+    # -- DML wrappers -------------------------------------------------
+    def save(self, user_id: str, fact: str,
+              tags: Optional[List[str]] = None) -> str:
+        created = time.time()
+        key = f"mem_{int(created*1000)}_{uuid.uuid4().hex[:6]}"
+        value = json.dumps({
+            "fact":    fact,
+            "tags":    tags or [],
+            "created": created,
+        })
+        self._exec(
+            f"MEMORY PUT INTO {self.memory} VALUES "
+            f"('{_e(user_id)}','{_e(key)}','{_e(value)}')"
+        )
+        return key
+
+    def search(self, user_id: str, query: str,
+                limit: int = 5,
+                tag: Optional[str] = None) -> List[Dict[str, Any]]:
+        rows = self._query(
+            f"SELECT mem_namespace, mem_key, mem_value FROM "
+            f"__mem_{self.memory} WHERE mem_namespace = "
+            f"'{_e(user_id)}' LIMIT 512"
+        )
+        q_terms = [w for w in query.lower().split() if len(w) > 1]
+        out: List[Dict[str, Any]] = []
+        for r in rows:
+            try:
+                rec = json.loads(r[2]) if r[2] else None
+            except Exception:
+                rec = {"fact": r[2]}
+            if not rec or not rec.get("fact"):
+                continue
+            haystack = (rec.get("fact", "").lower() + " " +
+                        " ".join(rec.get("tags") or []).lower())
+            score = sum(1 for w in q_terms if w in haystack)
+            if tag and tag.lower() not in [t.lower() for t in (rec.get("tags") or [])]:
+                continue
+            if score == 0 and not tag:
+                continue
+            out.append({"key": r[1], "score": score, **rec})
+        out.sort(key=lambda x: -x["score"])
+        return out[:limit]
+
+    def recent(self, user_id: str, limit: int = 10) -> List[Dict[str, Any]]:
+        rows = self._query(
+            f"SELECT mem_namespace, mem_key, mem_value FROM "
+            f"__mem_{self.memory} WHERE mem_namespace = "
+            f"'{_e(user_id)}' LIMIT 512"
+        )
+        out: List[Dict[str, Any]] = []
+        for r in rows:
+            try:
+                rec = json.loads(r[2]) if r[2] else {}
+            except Exception:
+                rec = {"fact": r[2]}
+            out.append({"key": r[1], **rec})
+        out.sort(key=lambda x: -x.get("created", 0))
+        return out[:limit]
+
+    def forget(self, user_id: str, key: str) -> bool:
+        try:
+            self._exec(
+                f"MEMORY DELETE FROM {self.memory} "
+                f"WHERE NS='{_e(user_id)}' AND KEY='{_e(key)}'"
+            )
+            return True
+        except Exception:
+            return False
+
+    def list_tags(self, user_id: str) -> List[Dict[str, Any]]:
+        rows = self._query(
+            f"SELECT mem_namespace, mem_value FROM "
+            f"__mem_{self.memory} WHERE mem_namespace = "
+            f"'{_e(user_id)}' LIMIT 512"
+        )
+        counts: Dict[str, int] = {}
+        for r in rows:
+            try:
+                rec = json.loads(r[1]) if r[1] else {}
+            except Exception:
+                continue
+            for tag in (rec.get("tags") or []):
+                counts[tag] = counts.get(tag, 0) + 1
+        out = [{"tag": t, "count": c} for t, c in counts.items()]
+        out.sort(key=lambda x: -x["count"])
+        return out
+
+
+def _to_str(v: Any) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, (bytes, bytearray)):
+        try:
+            return v.decode("utf-8")
+        except UnicodeDecodeError:
+            return v.decode("latin-1", "replace")
+    if isinstance(v, (dict, list)):
+        return json.dumps(v, ensure_ascii=False)
+    return str(v)
+
+
+# ---------------------------------------------------------------- #
+#  Tool catalog — what Claude Desktop sees on tools/list.            #
+# ---------------------------------------------------------------- #
+TOOLS = [
+    {
+        "name": "save_memory",
+        "description": (
+            "Persist a long-term fact about the user. Call this whenever "
+            "the user shares a preference, decision, biographical detail, "
+            "or anything you'd want to remember across future "
+            "conversations. The fact will be available to all future "
+            "Claude sessions through search_memory."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "fact": {
+                    "type": "string",
+                    "description": "Concise statement of what to remember."
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Categorisation labels (e.g. work, "
+                                       "preference, family). Optional."
+                },
+            },
+            "required": ["fact"],
+        },
+    },
+    {
+        "name": "search_memory",
+        "description": (
+            "Search remembered facts. Call this BEFORE answering any "
+            "question that depends on prior knowledge of the user. "
+            "Substring + tag matching; supply both `query` and "
+            "(optionally) `tag` to narrow."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "tag":   {"type": "string",
+                            "description": "Optional tag filter."},
+                "limit": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "recent_memories",
+        "description": "List the most recently saved facts.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "limit": {"type": "integer", "default": 10},
+            },
+        },
+    },
+    {
+        "name": "forget",
+        "description": "Delete a stored fact by its `key` (returned by "
+                       "save_memory or surfaced by search_memory).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"key": {"type": "string"}},
+            "required": ["key"],
+        },
+    },
+    {
+        "name": "list_tags",
+        "description": "List all distinct tags used so far, with counts.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+]
+
+
+# ---------------------------------------------------------------- #
+#  Server — newline-delimited JSON-RPC 2.0 over stdio.               #
+# ---------------------------------------------------------------- #
+class MCPServer:
+    def __init__(self) -> None:
+        self.user_id = os.environ.get("MCP_USER_ID", "default_user")
+        self.host    = os.environ.get("EVOSQL_HOST",     "127.0.0.1")
+        # Default to PostgreSQL wire (5433). Older deployments using EVO
+        # native (9967) won't work over psycopg — point them at 5433.
+        self.port    = int(os.environ.get("EVOSQL_PORT", "5433"))
+        self.user    = os.environ.get("EVOSQL_USER",     "admin")
+        self.pw      = os.environ.get("EVOSQL_PASSWORD", "admin")
+        self.db      = os.environ.get("EVOSQL_DATABASE", "testdb")
+        self.prefix  = os.environ.get("MCP_STORE_PREFIX", "mcp")
+        self.backend: Optional[MemoryBackend] = None
+
+    def _connect(self) -> MemoryBackend:
+        if self.backend is None:
+            self.backend = MemoryBackend(self.host, self.port,
+                                            self.user, self.pw,
+                                            self.db, self.prefix)
+        return self.backend
+
+    # -- tool dispatch ------------------------------------------------
+    def _call_tool(self, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        b = self._connect()
+        if name == "save_memory":
+            fact = args.get("fact") or ""
+            if not fact.strip():
+                return {"error": "save_memory requires non-empty `fact`"}
+            tags = args.get("tags") or []
+            if isinstance(tags, str):
+                tags = [tags]
+            key = b.save(self.user_id, fact, tags)
+            return {"ok": True, "key": key, "user_id": self.user_id}
+
+        if name == "search_memory":
+            q = args.get("query") or ""
+            if not q.strip():
+                return {"error": "search_memory requires non-empty `query`"}
+            tag = args.get("tag")
+            limit = int(args.get("limit") or 5)
+            return {"ok": True,
+                    "user_id": self.user_id,
+                    "results": b.search(self.user_id, q, limit=limit, tag=tag)}
+
+        if name == "recent_memories":
+            limit = int(args.get("limit") or 10)
+            return {"ok": True, "user_id": self.user_id,
+                    "results": b.recent(self.user_id, limit)}
+
+        if name == "forget":
+            key = args.get("key") or ""
+            if not key:
+                return {"error": "forget requires `key`"}
+            ok = b.forget(self.user_id, key)
+            return {"ok": ok, "key": key}
+
+        if name == "list_tags":
+            return {"ok": True, "user_id": self.user_id,
+                    "tags": b.list_tags(self.user_id)}
+
+        return {"error": f"unknown tool: {name}"}
+
+    # -- JSON-RPC dispatch -------------------------------------------
+    def handle(self, msg: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        method = msg.get("method")
+        params = msg.get("params") or {}
+        msg_id = msg.get("id")
+
+        # Notifications (no id) get no response.
+        if msg_id is None:
+            return None
+
+        if method == "initialize":
+            return self._ok(msg_id, {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities":    {"tools": {"listChanged": False}},
+                "serverInfo":      {"name": SERVER_NAME,
+                                       "version": SERVER_VERSION},
+            })
+
+        if method == "tools/list":
+            return self._ok(msg_id, {"tools": TOOLS})
+
+        if method == "tools/call":
+            name = params.get("name") or ""
+            args = params.get("arguments") or {}
+            try:
+                result = self._call_tool(name, args)
+            except Exception as e:
+                traceback.print_exc(file=sys.stderr)
+                return self._ok(msg_id, {
+                    "content": [{"type": "text",
+                                    "text": f"tool {name} failed: {e}"}],
+                    "isError": True,
+                })
+            text = json.dumps(result, ensure_ascii=False)
+            return self._ok(msg_id, {
+                "content": [{"type": "text", "text": text}],
+                "isError": bool(result.get("error")),
+            })
+
+        if method in ("ping",):
+            return self._ok(msg_id, {})
+
+        return self._err(msg_id, -32601, f"method not found: {method}")
+
+    @staticmethod
+    def _ok(id_, result) -> Dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": id_, "result": result}
+
+    @staticmethod
+    def _err(id_, code, message) -> Dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": id_,
+                "error": {"code": code, "message": message}}
+
+
+# ---------------------------------------------------------------- #
+#  stdio loop                                                       #
+# ---------------------------------------------------------------- #
+def main() -> int:
+    server = MCPServer()
+    print(
+        f"[mcp-evosql] listening on stdio "
+        f"(evosql={server.host}:{server.port}, user_id={server.user_id!r})",
+        file=sys.stderr, flush=True)
+
+    for raw_line in sys.stdin:
+        raw_line = raw_line.strip()
+        if not raw_line:
+            continue
+        try:
+            msg = json.loads(raw_line)
+        except json.JSONDecodeError as e:
+            print(f"[mcp-evosql] bad JSON line: {e}",
+                   file=sys.stderr, flush=True)
+            continue
+        try:
+            resp = server.handle(msg)
+        except Exception as e:
+            traceback.print_exc(file=sys.stderr)
+            resp = server._err(msg.get("id"), -32603, str(e))
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+    return 0