pgmnemo-mcp 0.5.2__tar.gz

pgmnemo_mcp-0.5.2/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pgmnemo-mcp
+Version: 0.5.2
+Summary: MCP server wrapping pgmnemo ingest and recall for AI agent memory
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: pydantic>=2.0

pgmnemo_mcp-0.5.2/pgmnemo_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""pgmnemo-mcp — MCP server exposing pgmnemo ingest and recall tools."""
+
+__version__ = "0.5.0"
+
+from .server import mcp, ingest, recall, main
+
+__all__ = ["mcp", "ingest", "recall", "main", "__version__"]

pgmnemo_mcp-0.5.2/pgmnemo_mcp/__main__.py

@@ -0,0 +1,56 @@
+"""python -m pgmnemo_mcp — CLI entry point with --smoke flag."""
+
+import argparse
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="pgmnemo-mcp")
+    parser.add_argument(
+        "--smoke",
+        action="store_true",
+        help="Run a connectivity smoke test: connect to DB and call recall_lessons().",
+    )
+    args = parser.parse_args()
+
+    if args.smoke:
+        _run_smoke()
+    else:
+        from .server import run
+        run()
+
+
+def _run_smoke() -> None:
+    from .config import DATABASE_URL, get_pool
+
+    print(f"pgmnemo-mcp smoke: connecting to {_redact(DATABASE_URL)} …")
+    try:
+        pool = get_pool()
+        conn = pool.getconn()
+        try:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "SELECT count(*) FROM pgmnemo.recall_lessons("
+                    "NULL::vector(1024), 5, NULL, NULL, 'test')"
+                )
+                row = cur.fetchone()
+            pool.putconn(conn)
+        except Exception:
+            pool.putconn(conn)
+            raise
+    except Exception as exc:
+        print(f"pgmnemo-mcp smoke: FAIL — {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"pgmnemo-mcp smoke: OK (recall_lessons returned {row[0]} rows)")
+    sys.exit(0)
+
+
+def _redact(url: str) -> str:
+    """Hide password in DATABASE_URL for safe printing."""
+    import re
+    return re.sub(r"://([^:@]+):([^@]+)@", r"://\1:***@", url)
+
+
+if __name__ == "__main__":
+    main()

pgmnemo_mcp-0.5.2/pgmnemo_mcp/config.py

@@ -0,0 +1,16 @@
+import os
+from psycopg2 import pool
+
+__all__ = ["DATABASE_URL", "MCP_PORT", "get_pool"]
+
+DATABASE_URL: str = os.environ.get("DATABASE_URL", "postgresql://localhost/pgmnemo")
+MCP_PORT: int = int(os.environ.get("MCP_PORT", "8765"))
+
+_pool: pool.SimpleConnectionPool | None = None
+
+
+def get_pool() -> pool.SimpleConnectionPool:
+    global _pool
+    if _pool is None:
+        _pool = pool.SimpleConnectionPool(1, 5, dsn=DATABASE_URL)
+    return _pool

pgmnemo_mcp-0.5.2/pgmnemo_mcp/server.py

@@ -0,0 +1,109 @@
+"""pgmnemo MCP server — exposes ingest and recall as MCP tools.
+
+Transport note (BUG-3 resolution):
+    FastMCP uses MCP protocol transport (stdio by default, SSE/streamable-http
+    optionally). It does NOT expose REST endpoints at /ingest or /recall.
+    Clients must use the MCP JSON-RPC protocol (stdio pipe or SSE at /sse).
+    The --smoke command in __main__.py exercises the DB layer directly
+    without going through the MCP transport.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .config import get_pool
+
+mcp = FastMCP("pgmnemo", port=8765)
+
+
+@mcp.tool(name="pgmnemo.ingest", description="Ingest a lesson into pgmnemo agent memory.")
+def ingest(
+    text: str,
+    role: str = "mcp_agent",
+    topic: str = "general",
+    importance: int = 3,
+    project_id: int = 1,
+    commit_sha: str | None = None,
+    artifact_hash: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Store a lesson via pgmnemo.ingest() SP and return its id.
+
+    Uses the pgmnemo.ingest() stored procedure instead of raw INSERT so that:
+    - Gate enforcement (provenance checks) runs inside the SP.
+    - verified_at is stamped automatically when commit_sha/artifact_hash are present.
+    - Embedding dimension validation fires before the INSERT.
+    """
+    p = get_pool()
+    conn = p.getconn()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT pgmnemo.ingest(
+                    %s, %s, %s, %s, %s::smallint,
+                    NULL::vector(1024), %s, %s, %s::jsonb
+                )
+                """,
+                (
+                    role,
+                    project_id,
+                    topic,
+                    text,
+                    importance,
+                    commit_sha,
+                    artifact_hash,
+                    json.dumps(metadata) if metadata is not None else "{}",
+                ),
+            )
+            new_id = cur.fetchone()[0]
+            conn.commit()
+        return {"id": new_id}
+    finally:
+        p.putconn(conn)
+
+
+@mcp.tool(name="pgmnemo.recall", description="Recall lessons from pgmnemo agent memory.")
+def recall(query: str, top_k: int = 5) -> list[dict[str, Any]]:
+    """Return up to top_k lessons whose text matches query via pgmnemo.recall_lessons.
+
+    recall_lessons() RETURNS TABLE (lesson_id bigint, score, role, ...) — the output
+    column is 'lesson_id' (an alias), not 'id' (the physical table column).
+    """
+    p = get_pool()
+    conn = p.getconn()
+    try:
+        with conn.cursor() as cur:
+            # recall_lessons(query_vec, top_k, role_filter, project_id_filter, query_text)
+            # Pass NULL vector — rely on query_text for BM25/hybrid keyword match.
+            cur.execute(
+                """
+                SELECT lesson_id, role, topic, lesson_text, importance, created_at
+                FROM pgmnemo.recall_lessons(
+                    NULL::vector(1024), %s, NULL, NULL, %s
+                )
+                """,
+                (top_k, query),
+            )
+            cols = [d[0] for d in cur.description]
+            return [dict(zip(cols, row)) for row in cur.fetchall()]
+    finally:
+        p.putconn(conn)
+
+
+def run() -> None:
+    """Entry point for `python -m pgmnemo_mcp.server`."""
+    mcp.run()
+
+
+def main() -> None:
+    """Console script entry point (pgmnemo-mcp = pgmnemo_mcp.server:main)."""
+    run()
+
+
+if __name__ == "__main__":
+    main()

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pgmnemo-mcp
+Version: 0.5.2
+Summary: MCP server wrapping pgmnemo ingest and recall for AI agent memory
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: pydantic>=2.0

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+pyproject.toml
+pgmnemo_mcp/__init__.py
+pgmnemo_mcp/__main__.py
+pgmnemo_mcp/config.py
+pgmnemo_mcp/server.py
+pgmnemo_mcp.egg-info/PKG-INFO
+pgmnemo_mcp.egg-info/SOURCES.txt
+pgmnemo_mcp.egg-info/dependency_links.txt
+pgmnemo_mcp.egg-info/entry_points.txt
+pgmnemo_mcp.egg-info/requires.txt
+pgmnemo_mcp.egg-info/top_level.txt
+tests/test_import.py
+tests/test_server.py

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pgmnemo-mcp = pgmnemo_mcp.server:run

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/requires.txt

@@ -0,0 +1,3 @@
+mcp>=1.0
+psycopg2-binary>=2.9
+pydantic>=2.0

pgmnemo_mcp-0.5.2/pgmnemo_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+pgmnemo_mcp

pgmnemo_mcp-0.5.2/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pgmnemo-mcp"
+version = "0.5.2"
+description = "MCP server wrapping pgmnemo ingest and recall for AI agent memory"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0",
+    "psycopg2-binary>=2.9",
+    "pydantic>=2.0",
+]
+
+[project.scripts]
+pgmnemo-mcp = "pgmnemo_mcp.server:run"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pgmnemo_mcp*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

pgmnemo_mcp-0.5.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pgmnemo_mcp-0.5.2/tests/test_import.py

@@ -0,0 +1,3 @@
+def test_pgmnemo_mcp_importable():
+    import pgmnemo_mcp
+    assert hasattr(pgmnemo_mcp, '__file__')

pgmnemo_mcp-0.5.2/tests/test_server.py

@@ -0,0 +1,234 @@
+"""Unit tests for pgmnemo_mcp.server — ingest() and recall() tools.
+
+Uses unittest.mock to patch get_pool() so no live PostgreSQL is required.
+All tests verify the SQL / SP call generated and the return shape of each function.
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+import types
+import unittest
+from datetime import datetime
+from unittest.mock import MagicMock, patch, call
+
+
+# ---------------------------------------------------------------------------
+# Stub the `mcp` package so tests run without `mcp` installed
+# ---------------------------------------------------------------------------
+
+def _stub_mcp() -> None:
+    if "mcp" in sys.modules:
+        return
+    mcp_pkg = types.ModuleType("mcp")
+    server_pkg = types.ModuleType("mcp.server")
+    fastmcp_mod = types.ModuleType("mcp.server.fastmcp")
+
+    class _FastMCP:
+        def __init__(self, name: str, **kw: object) -> None:
+            self.name = name
+
+        def tool(self, **kw: object):
+            def decorator(fn):
+                return fn
+            return decorator
+
+        def run(self) -> None:
+            pass
+
+    fastmcp_mod.FastMCP = _FastMCP
+    sys.modules["mcp"] = mcp_pkg
+    sys.modules["mcp.server"] = server_pkg
+    sys.modules["mcp.server.fastmcp"] = fastmcp_mod
+
+
+_stub_mcp()
+
+# Force reimport after stub
+for mod in list(sys.modules):
+    if mod.startswith("pgmnemo_mcp"):
+        del sys.modules[mod]
+
+from pgmnemo_mcp import server  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_pool(rows=None, description=None):
+    """Return a mock psycopg2 connection pool and cursor."""
+    pool = MagicMock()
+    conn = MagicMock()
+    cur = MagicMock()
+
+    pool.getconn.return_value = conn
+    conn.cursor.return_value.__enter__ = lambda s: cur
+    conn.cursor.return_value.__exit__ = MagicMock(return_value=False)
+
+    if rows is not None:
+        cur.fetchone.return_value = rows[0] if rows else None
+        cur.fetchall.return_value = rows
+    if description is not None:
+        cur.description = [(col,) for col in description]
+
+    return pool, conn, cur
+
+
+# ---------------------------------------------------------------------------
+# ingest() tests
+# ---------------------------------------------------------------------------
+
+class TestIngest(unittest.TestCase):
+
+    def test_returns_id(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (42,)
+        with patch.object(server, "get_pool", return_value=pool):
+            result = server.ingest(text="hello world")
+        self.assertEqual(result["id"], 42)
+
+    def test_calls_ingest_sp_not_raw_insert(self):
+        """Regression: must call pgmnemo.ingest() SP, not raw INSERT."""
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (1,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="test lesson")
+        sql = cur.execute.call_args[0][0]
+        self.assertIn("pgmnemo.ingest", sql)
+        self.assertNotIn("INSERT INTO", sql)
+
+    def test_default_params_sent_to_sp(self):
+        """SP receives args in positional order: role, project_id, topic, text, importance, ..."""
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (1,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="test lesson")
+        args = cur.execute.call_args[0][1]
+        # Positional order matches SP signature: role, project_id, topic, lesson_text, importance
+        self.assertEqual(args[0], "mcp_agent")    # role
+        self.assertEqual(args[1], 1)              # project_id
+        self.assertEqual(args[2], "general")      # topic
+        self.assertEqual(args[3], "test lesson")  # lesson_text
+        self.assertEqual(args[4], 3)              # importance
+
+    def test_project_id_passed_through(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (7,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x", project_id=99)
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[1], 99)
+
+    def test_commit_sha_and_artifact_hash_forwarded(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (5,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x", commit_sha="abc123", artifact_hash="def456")
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[5], "abc123")   # commit_sha
+        self.assertEqual(args[6], "def456")   # artifact_hash
+
+    def test_metadata_serialized_to_json(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (3,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x", metadata={"key": "val"})
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(json.loads(args[7]), {"key": "val"})
+
+    def test_none_metadata_defaults_to_empty_json_object(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (3,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x")
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[7], "{}")
+
+    def test_jsonb_cast_present_in_sql(self):
+        """Ensures metadata arg is cast to ::jsonb so PostgreSQL accepts it."""
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (1,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x")
+        sql = cur.execute.call_args[0][0]
+        self.assertIn("::jsonb", sql)
+
+    def test_conn_returned_to_pool(self):
+        pool, conn, cur = _make_pool()
+        cur.fetchone.return_value = (1,)
+        with patch.object(server, "get_pool", return_value=pool):
+            server.ingest(text="x")
+        pool.putconn.assert_called_once_with(conn)
+
+    def test_conn_returned_on_exception(self):
+        pool, conn, cur = _make_pool()
+        cur.execute.side_effect = RuntimeError("db down")
+        with patch.object(server, "get_pool", return_value=pool):
+            with self.assertRaises(RuntimeError):
+                server.ingest(text="boom")
+        pool.putconn.assert_called_once_with(conn)
+
+
+# ---------------------------------------------------------------------------
+# recall() tests
+# ---------------------------------------------------------------------------
+
+class TestRecall(unittest.TestCase):
+
+    def test_returns_list_of_dicts(self):
+        ts = datetime(2026, 5, 17)
+        rows = [(10, "agent", "memory", "lesson A", 3, ts)]
+        cols = ["lesson_id", "role", "topic", "lesson_text", "importance", "created_at"]
+        pool, conn, cur = _make_pool(rows=rows, description=cols)
+        with patch.object(server, "get_pool", return_value=pool):
+            result = server.recall(query="memory test")
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0]["lesson_id"], 10)
+        self.assertEqual(result[0]["lesson_text"], "lesson A")
+
+    def test_default_top_k_is_5(self):
+        pool, conn, cur = _make_pool(rows=[], description=["lesson_id"])
+        with patch.object(server, "get_pool", return_value=pool):
+            server.recall(query="q")
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[0], 5)   # top_k
+
+    def test_top_k_passed_through(self):
+        pool, conn, cur = _make_pool(rows=[], description=["lesson_id"])
+        with patch.object(server, "get_pool", return_value=pool):
+            server.recall(query="q", top_k=10)
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[0], 10)
+
+    def test_query_text_forwarded(self):
+        pool, conn, cur = _make_pool(rows=[], description=["lesson_id"])
+        with patch.object(server, "get_pool", return_value=pool):
+            server.recall(query="find lessons about memory")
+        args = cur.execute.call_args[0][1]
+        self.assertEqual(args[1], "find lessons about memory")
+
+    def test_empty_result(self):
+        pool, conn, cur = _make_pool(rows=[], description=["lesson_id"])
+        with patch.object(server, "get_pool", return_value=pool):
+            result = server.recall(query="nothing")
+        self.assertEqual(result, [])
+
+    def test_conn_returned_to_pool(self):
+        pool, conn, cur = _make_pool(rows=[], description=["lesson_id"])
+        with patch.object(server, "get_pool", return_value=pool):
+            server.recall(query="x")
+        pool.putconn.assert_called_once_with(conn)
+
+    def test_conn_returned_on_exception(self):
+        pool, conn, cur = _make_pool()
+        cur.execute.side_effect = RuntimeError("db error")
+        with patch.object(server, "get_pool", return_value=pool):
+            with self.assertRaises(RuntimeError):
+                server.recall(query="x")
+        pool.putconn.assert_called_once_with(conn)
+
+
+if __name__ == "__main__":
+    unittest.main()