keep-agent-mem 1.0.0__tar.gz

keep_agent_mem-1.0.0/.example.env

@@ -0,0 +1,3 @@
+# Google Keep API Credentials
+GOOGLE_EMAIL=your-email@gmail.com
+GOOGLE_MASTER_TOKEN=your-master-token-see-the-readme-on-how-to-get-it 

keep_agent_mem-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install package and test dependencies
+        run: |
+          uv pip install --system -e . pytest pytest-asyncio pytest-cov ruff python-dotenv
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Run tests with coverage
+        run: pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70
+
+      - name: Bytecode sanity
+        run: python -m compileall src

keep_agent_mem-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,202 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Compute semantic release version from commits
+        id: meta
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import os
+          import pathlib
+          import re
+          import subprocess
+
+
+          def run(*args: str) -> str:
+              return subprocess.check_output(args, text=True).strip()
+
+
+          def parse_tuple(version: str) -> tuple[int, int, int]:
+              match = re.fullmatch(r"(\d+)\.(\d+)\.(\d+)", version)
+              if not match:
+                  raise SystemExit(f"Unsupported version format: {version}")
+              return tuple(int(part) for part in match.groups())
+
+
+          def parse_semver_tag(tag: str) -> tuple[int, int, int] | None:
+              match = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)", tag)
+              if not match:
+                  return None
+              return tuple(int(part) for part in match.groups())
+
+          text = pathlib.Path("pyproject.toml").read_text()
+          match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
+          if not match:
+              raise SystemExit("Could not find project version in pyproject.toml")
+          pyproject_version = match.group(1)
+
+          all_tags = run("git", "tag", "--list", "v*.*.*").splitlines()
+          parsed_tags = []
+          for tag in all_tags:
+              parsed = parse_semver_tag(tag)
+              if parsed is not None:
+                  parsed_tags.append((parsed, tag))
+          parsed_tags.sort(key=lambda item: item[0])
+
+          latest_tag = parsed_tags[-1][1] if parsed_tags else ""
+          base_version = parsed_tags[-1][0] if parsed_tags else parse_tuple(pyproject_version)
+
+          log_range = f"{latest_tag}..HEAD" if latest_tag else "HEAD"
+          raw = run("git", "log", log_range, "--pretty=%s%n%b<<END>>")
+          chunks = [chunk.strip() for chunk in raw.split("<<END>>") if chunk.strip()]
+
+          # Conventional commits -> version bump mapping:
+          # major: *!: or BREAKING CHANGE
+          # minor: feat
+          # patch: fix, perf, revert
+          bump_order = {"patch": 1, "minor": 2, "major": 3}
+          bump = None
+
+          for chunk in chunks:
+              lines = chunk.splitlines()
+              subject = lines[0].strip() if lines else ""
+              body = "\n".join(lines[1:]) if len(lines) > 1 else ""
+
+              if "BREAKING CHANGE" in chunk or re.match(r"^[a-z]+(?:\([^)]+\))?!:", subject):
+                  current = "major"
+              elif re.match(r"^feat(?:\([^)]+\))?:", subject):
+                  current = "minor"
+              elif re.match(r"^(fix|perf|revert)(?:\([^)]+\))?:", subject):
+                  current = "patch"
+              else:
+                  current = None
+
+              if current and (bump is None or bump_order[current] > bump_order[bump]):
+                  bump = current
+
+          if bump is None:
+              print("release_required=false")
+              print("reason=no_semantic_release_commits")
+              print(f"previous_tag={latest_tag}")
+              raise SystemExit(0)
+
+          major, minor, patch = base_version
+          if bump == "major":
+              next_version = f"{major + 1}.0.0"
+          elif bump == "minor":
+              next_version = f"{major}.{minor + 1}.0"
+          else:
+              next_version = f"{major}.{minor}.{patch + 1}"
+
+          print("release_required=true")
+          print(f"bump={bump}")
+          print(f"previous_tag={latest_tag}")
+          print(f"version={next_version}")
+          print(f"tag=v{next_version}")
+          PY
+
+      - name: Skip when no releasable semantic commits
+        if: steps.meta.outputs.release_required != 'true'
+        run: |
+          echo "No release created."
+          echo "Reason: ${{ steps.meta.outputs.reason }}"
+          echo "Only these commit types trigger a release: feat, fix, perf, revert, and BREAKING CHANGE."
+
+      - name: Check whether computed tag already exists
+        id: tag_check
+        if: steps.meta.outputs.release_required == 'true'
+        run: |
+          if git show-ref --tags --verify --quiet "refs/tags/${{ steps.meta.outputs.tag }}"; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Skip publish when release tag exists
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists == 'true'
+        run: echo "Tag ${{ steps.meta.outputs.tag }} already exists. Skipping publish."
+
+      - name: Install uv
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install test and build dependencies
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        run: |
+          uv pip install --system -e . pytest pytest-asyncio ruff
+
+      - name: Lint
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        run: ruff check .
+
+      - name: Unit tests
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        run: pytest -q
+
+      - name: Write computed version to pyproject.toml
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        run: |
+          python - <<'PY'
+          import pathlib
+          import re
+
+          version = "${{ steps.meta.outputs.version }}"
+          path = pathlib.Path("pyproject.toml")
+          text = path.read_text()
+          updated, count = re.subn(
+              r'^version\s*=\s*"[^"]+"',
+              f'version = "{version}"',
+              text,
+              count=1,
+              flags=re.MULTILINE,
+          )
+          if count != 1:
+              raise SystemExit("Failed to update version in pyproject.toml")
+          path.write_text(updated)
+          print(f"Updated pyproject version to {version}")
+          PY
+
+      - name: Build distribution artifacts
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        run: uv build
+
+      - name: Publish package to PyPI
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Create GitHub release
+        if: steps.meta.outputs.release_required == 'true' && steps.tag_check.outputs.exists != 'true'
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ steps.meta.outputs.tag }}
+          target_commitish: ${{ github.sha }}
+          name: ${{ steps.meta.outputs.tag }}
+          generate_release_notes: true
+          files: dist/*

keep_agent_mem-1.0.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS specific files
+.DS_Store
+Thumbs.db
+
+# Project specific
+.cursor/
+uv.lock
+API_DOCS.md
+progress
+
+# Test artifacts
+.coverage
+htmlcov/
+.pytest_cache/

keep_agent_mem-1.0.0/.python-version

@@ -0,0 +1 @@
+3.10

keep_agent_mem-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: keep-agent-mem
+Version: 1.0.0
+Summary: Agent Memory via Google Keep MCP
+Project-URL: Homepage, https://github.com/anand-92/keep-agent-mem
+Project-URL: Repository, https://github.com/anand-92/keep-agent-mem
+Author-email: Nik Anand <mntechsurvey@gmail.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: gkeepapi>=0.16.0
+Requires-Dist: python-dotenv>=1.2.2
+Description-Content-Type: text/markdown
+
+# keep-agent-mem
+
+MCP server for Google Keep that serves as cross-device memory for your agents.
+
+
+## How to use
+
+1. Add the MCP server to your MCP servers:
+
+### `config.toml` clients (Claude, Droid, Cursor)
+
+```json
+  "mcpServers": {
+    "keep-agent-mem": {
+      "command": "uvx",
+      "args": [
+        "keep-agent-mem"
+      ],
+      "env": {
+        "GOOGLE_EMAIL": "Your Google Email",
+        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
+      }
+    }
+  }
+```
+
+### `config.toml` clients (Codex, Goose, etc.)
+
+```toml
+[mcp_servers.keep_agent_mem]
+command = "uvx"
+args = ["keep-agent-mem"]
+
+[mcp_servers.keep_agent_mem.env]
+GOOGLE_EMAIL = "you@example.com"
+GOOGLE_MASTER_TOKEN = "your-master-token"
+```
+
+2. Add your credentials:
+* `GOOGLE_EMAIL`: Your Google account email address
+* `GOOGLE_MASTER_TOKEN`: Your Google account master token
+
+Check https://gkeepapi.readthedocs.io/en/latest/#obtaining-a-master-token and https://github.com/simon-weber/gpsoauth?tab=readme-ov-file#alternative-flow for more information.
+
+## Tools
+
+### Query and read tools
+* `find`: Search notes with optional filters for labels, colors, pinned, archived, and trashed
+* `get`: Get a single note by ID
+
+### Creation, update, and deletion tools
+* `create`: Create a new note with a title, text, and an associated label
+* `update`: Update a note's title and text
+* `delete`: Delete a note by ID
+
+
+
+
+## Troubleshooting
+
+* If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"

keep_agent_mem-1.0.0/README.md

@@ -0,0 +1,61 @@
+# keep-agent-mem
+
+MCP server for Google Keep that serves as cross-device memory for your agents.
+
+
+## How to use
+
+1. Add the MCP server to your MCP servers:
+
+### `config.toml` clients (Claude, Droid, Cursor)
+
+```json
+  "mcpServers": {
+    "keep-agent-mem": {
+      "command": "uvx",
+      "args": [
+        "keep-agent-mem"
+      ],
+      "env": {
+        "GOOGLE_EMAIL": "Your Google Email",
+        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
+      }
+    }
+  }
+```
+
+### `config.toml` clients (Codex, Goose, etc.)
+
+```toml
+[mcp_servers.keep_agent_mem]
+command = "uvx"
+args = ["keep-agent-mem"]
+
+[mcp_servers.keep_agent_mem.env]
+GOOGLE_EMAIL = "you@example.com"
+GOOGLE_MASTER_TOKEN = "your-master-token"
+```
+
+2. Add your credentials:
+* `GOOGLE_EMAIL`: Your Google account email address
+* `GOOGLE_MASTER_TOKEN`: Your Google account master token
+
+Check https://gkeepapi.readthedocs.io/en/latest/#obtaining-a-master-token and https://github.com/simon-weber/gpsoauth?tab=readme-ov-file#alternative-flow for more information.
+
+## Tools
+
+### Query and read tools
+* `find`: Search notes with optional filters for labels, colors, pinned, archived, and trashed
+* `get`: Get a single note by ID
+
+### Creation, update, and deletion tools
+* `create`: Create a new note with a title, text, and an associated label
+* `update`: Update a note's title and text
+* `delete`: Delete a note by ID
+
+
+
+
+## Troubleshooting
+
+* If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"

keep_agent_mem-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "keep-agent-mem"
+version = "1.0.0"
+description = "Agent Memory via Google Keep MCP"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp==3.4.2",
+    "gkeepapi>=0.16.0",
+    "python-dotenv>=1.2.2",
+]
+authors = [
+    { name = "Nik Anand", email = "mntechsurvey@gmail.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/anand-92/keep-agent-mem"
+Repository = "https://github.com/anand-92/keep-agent-mem"
+
+[project.scripts]
+keep-agent-mem = "server.cli:main"
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/server"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.16",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

keep_agent_mem-1.0.0/scripts/smoke_test.py

@@ -0,0 +1,52 @@
+"""Basic real-account smoke test for keep-agent-mem server logic.
+
+Usage:
+  GOOGLE_EMAIL=... GOOGLE_MASTER_TOKEN=... python scripts/smoke_test.py
+
+This script performs a lifecycle against Google Keep:
+- create note
+- get note
+- update note
+- find note
+
+It is intended for manual verification, not CI.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from server import cli
+
+
+def main() -> None:
+    if not os.getenv("GOOGLE_EMAIL") or not os.getenv("GOOGLE_MASTER_TOKEN"):
+        raise SystemExit("Set GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN before running smoke test")
+
+    # --- Note lifecycle ---
+    print("Creating note...")
+    created = json.loads(cli.create(label="keep-agent-mem", title="keep-agent-mem smoke", text="hello"))
+    note_id = created["id"]
+    print("Created:", note_id)
+
+    print("Getting note...")
+    fetched = json.loads(cli.get(note_id))
+    assert fetched["id"] == note_id
+
+    print("Updating note...")
+    updated = json.loads(cli.update(note_id, title="keep-agent-mem smoke updated", text="world"))
+    assert updated["title"] == "keep-agent-mem smoke updated"
+
+    # --- find() ---
+    print("Testing find()...")
+    results = json.loads(cli.find(query="keep-agent-mem smoke updated"))
+    assert isinstance(results, list)
+
+    print("Smoke test finished successfully")
+
+
+if __name__ == "__main__":
+    main()

keep_agent_mem-1.0.0/src/server/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

keep_agent_mem-1.0.0/src/server/cli.py

@@ -0,0 +1,136 @@
+import gkeepapi
+from fastmcp import FastMCP
+
+from .keep_api import get_client, serialize_note
+
+mcp = FastMCP("keep")
+
+
+def _get_note_or_raise(note_id: str):
+    keep = get_client()
+    note = keep.get(note_id)
+    if not note:
+        raise ValueError(f"Note with ID {note_id} not found")
+    return keep, note
+
+
+def _normalize_colors(colors: list[str] | None):
+    if colors is None:
+        return None
+
+    normalized_colors = []
+    for color in colors:
+        try:
+            normalized_colors.append(gkeepapi.node.ColorValue(color))
+        except ValueError as exc:
+            raise ValueError(f"Invalid color '{color}'") from exc
+
+    return normalized_colors
+
+
+@mcp.tool()
+def find(
+    query: str = "",
+    labels: list[str] | None = None,
+    colors: list[str] | None = None,
+    pinned: bool | None = None,
+    archived: bool | None = False,
+    trashed: bool = False,
+) -> list[dict]:
+    """Find notes using text and optional filters.
+
+    Args:
+        query: The search term or query string to search for in notes.
+        labels: A list of label IDs to filter the notes by.
+        colors: A list of ColorValue strings to filter by (e.g. DEFAULT, RED, CERULEAN).
+        pinned: Filter notes by pinned status. True for pinned, False for unpinned, None for both.
+        archived: Filter notes by archived status. Defaults to False.
+        trashed: Filter notes by trashed status. Defaults to False.
+    """
+    keep = get_client()
+    normalized_colors = _normalize_colors(colors)
+    notes = keep.find(
+        query=query,
+        labels=labels,
+        colors=normalized_colors,
+        pinned=pinned,
+        archived=archived,
+        trashed=trashed,
+    )
+
+    notes_data = [serialize_note(note) for note in notes]
+    return notes_data
+
+
+@mcp.tool()
+def get(note_id: str) -> dict:
+    """Get a note by ID.
+
+    Args:
+        note_id: The ID of the note to retrieve.
+    """
+    _, note = _get_note_or_raise(note_id)
+    return serialize_note(note)
+
+
+@mcp.tool()
+def create(label: str, title: str | None = None, text: str | None = None) -> dict:
+    """Create a new note with a title, text, and an associated label.
+
+    Args:
+        label: The label to apply to the note. If the user does not explicitly specify a label, the client (e.g. LLM agent) MUST use the name of the current project or repository as the label.
+        title: The title of the note.
+        text: The text content of the note.
+    """
+    keep = get_client()
+    note = keep.createNote(title=title, text=text)
+
+    keep_label = keep.findLabel(label)
+    if not keep_label:
+        keep_label = keep.createLabel(label)
+
+    note.labels.add(keep_label)
+    keep.sync()
+
+    return serialize_note(note)
+
+
+@mcp.tool()
+def update(note_id: str, title: str | None = None, text: str | None = None) -> dict:
+    """Update a note's properties.
+
+    Args:
+        note_id: The ID of the note to update.
+        title: The new title for the note, if specified.
+        text: The new body text for the note, if specified.
+    """
+    keep, note = _get_note_or_raise(note_id)
+
+    if title is not None:
+        note.title = title
+    if text is not None:
+        note.text = text
+
+    keep.sync()
+    return serialize_note(note)
+
+
+@mcp.tool()
+def delete(note_id: str) -> dict:
+    """Delete a note by ID.
+
+    Args:
+        note_id: The ID of the note to delete.
+    """
+    keep, note = _get_note_or_raise(note_id)
+    note.delete()
+    keep.sync()
+    return {"message": f"Note {note_id} marked for deletion"}
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

keep_agent_mem-1.0.0/src/server/keep_api.py

@@ -0,0 +1,103 @@
+import gkeepapi
+import os
+import requests
+from dotenv import load_dotenv
+
+_keep_client = None
+
+def get_client():
+    """
+    Get or initialize the Google Keep client.
+    This ensures we only authenticate once and reuse the client.
+    
+    Returns:
+        gkeepapi.Keep: Authenticated Keep client
+    """
+    global _keep_client
+    
+    if _keep_client is not None:
+        return _keep_client
+    
+    # Load environment variables
+    load_dotenv()
+    
+    # Get credentials from environment variables
+    email = os.getenv('GOOGLE_EMAIL')
+    master_token = os.getenv('GOOGLE_MASTER_TOKEN')
+    
+    if not email or not master_token:
+        raise ValueError("Missing Google Keep credentials. Please set GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN environment variables.")
+    
+    # Initialize the Keep API
+    keep = gkeepapi.Keep()
+    
+    # Authenticate
+    try:
+        keep.authenticate(email, master_token)
+    except requests.exceptions.JSONDecodeError as exc:
+        raise RuntimeError(
+            "Google Keep API returned a non-JSON response during authentication. "
+            "This usually means the unofficial Keep API (notes/v1) is inaccessible "
+            "from this environment (HTTP 403/4xx). "
+            "Check that your GOOGLE_MASTER_TOKEN is valid and that the Keep API "
+            "is reachable from this network."
+        ) from exc
+    except gkeepapi.exception.LoginException as exc:
+        raise RuntimeError(
+            f"Google Keep login failed: {exc}. "
+            "Verify that GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN are correct."
+        ) from exc
+    
+    # Store the client for reuse
+    _keep_client = keep
+    
+    return keep
+
+def serialize_label(label):
+    return {'id': label.id, 'name': label.name}
+
+
+def serialize_list_item(item):
+    return {
+        'id': item.id,
+        'text': item.text,
+        'checked': item.checked,
+        'parent_item_id': item.parent_item.id if item.parent_item else None,
+    }
+
+
+def serialize_note(note):
+    """
+    Serialize a Google Keep note into a dictionary.
+    
+    Args:
+        note: A Google Keep note object
+        
+    Returns:
+        dict: A dictionary containing the note's id, title, text, pinned status, color and labels
+    """
+    payload = {
+        'id': note.id,
+        'title': note.title,
+        'text': note.text,
+        'type': note.type.value,
+        'pinned': note.pinned,
+        'archived': note.archived,
+        'trashed': note.trashed,
+        'color': note.color.value if note.color else None,
+        'labels': [serialize_label(label) for label in note.labels.all()],
+        'collaborators': list(note.collaborators.all()),
+    }
+
+    if hasattr(note, 'items'):
+        payload['items'] = [serialize_list_item(item) for item in note.items]
+
+    payload['media'] = [
+        {
+            'blob_id': blob.id,
+            'type': blob.blob.type.value if blob.blob and blob.blob.type else None,
+        }
+        for blob in note.blobs
+    ]
+
+    return payload

keep_agent_mem-1.0.0/tests/conftest.py

@@ -0,0 +1,4 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))

keep_agent_mem-1.0.0/tests/test_cli.py

@@ -0,0 +1,260 @@
+import pytest
+from fastmcp.client import Client
+
+from server import cli
+
+
+class DummyLabel:
+    def __init__(self, label_id="l1", name="keep-agent-mem"):
+        self.id = label_id
+        self.name = name
+
+
+class DummyLabels:
+    def __init__(self):
+        self._labels = []
+
+    def add(self, label):
+        self._labels.append(label)
+
+    def remove(self, label):
+        self._labels = [existing for existing in self._labels if existing.id != label.id]
+
+    def all(self):
+        return self._labels
+
+
+class DummyCollaborators:
+    def __init__(self):
+        self._emails = []
+
+    def all(self):
+        return list(self._emails)
+
+    def add(self, email):
+        self._emails.append(email)
+
+    def remove(self, email):
+        self._emails = [value for value in self._emails if value != email]
+
+
+class DummyBlobType:
+    def __init__(self, value="IMAGE"):
+        self.value = value
+
+
+class DummyBlobInner:
+    def __init__(self):
+        self.type = DummyBlobType("IMAGE")
+
+
+class DummyBlob:
+    def __init__(self, blob_id="b1"):
+        self.id = blob_id
+        self.blob = DummyBlobInner()
+
+
+class DummyNote:
+    def __init__(self, note_id="n1"):
+        self.id = note_id
+        self.title = "title"
+        self.text = "text"
+        self.pinned = False
+        self.archived = False
+        self.trashed = False
+        self.type = type("T", (), {"value": "NOTE"})()
+        self.color = type("C", (), {"value": "white"})()
+        self.labels = DummyLabels()
+        self.collaborators = DummyCollaborators()
+        self.blobs = [DummyBlob()]
+        self.deleted = False
+
+    def delete(self):
+        self.deleted = True
+
+    def trash(self):
+        self.trashed = True
+
+    def untrash(self):
+        self.trashed = False
+
+    def undelete(self):
+        self.deleted = False
+
+
+class DummyKeep:
+    def __init__(self):
+        self.notes = {}
+        self._labels = {"l1": DummyLabel("l1", "keep-agent-mem")}
+        self.sync_calls = 0
+
+    def sync(self):
+        self.sync_calls += 1
+
+    def find(self, **kwargs):
+        self.last_find_kwargs = kwargs
+        return list(self.notes.values())
+
+    def get(self, note_id):
+        return self.notes.get(note_id)
+
+    def createNote(self, title=None, text=None):
+        note = DummyNote("created")
+        note.title = title
+        note.text = text
+        self.notes[note.id] = note
+        return note
+
+    def findLabel(self, name):
+        for label in self._labels.values():
+            if label.name == name:
+                return label
+        return None
+
+    def createLabel(self, name):
+        label = DummyLabel("new", name)
+        self._labels[label.id] = label
+        return label
+
+    def labels(self):
+        return list(self._labels.values())
+
+    def getLabel(self, label_id):
+        return self._labels.get(label_id)
+
+    def all(self):
+        return list(self.notes.values())
+
+
+@pytest.fixture()
+def keep(monkeypatch):
+    keep = DummyKeep()
+    keep.notes["n1"] = DummyNote("n1")
+    keep.notes["n1"].labels.add(DummyLabel("l1", "keep-agent-mem"))
+
+    monkeypatch.setattr(cli, "get_client", lambda: keep)
+    monkeypatch.setattr(
+        cli.gkeepapi.node,
+        "ColorValue",
+        lambda color: type("Color", (), {"value": color})(),
+    )
+    return keep
+
+
+
+
+def test_find_forwards_filters(keep):
+    result = cli.find(
+        query="q",
+        labels=["l1"],
+        colors=["red"],
+        pinned=True,
+        archived=False,
+        trashed=False,
+    )
+    assert keep.last_find_kwargs["query"] == "q"
+    assert keep.last_find_kwargs["labels"] == ["l1"]
+    assert [color.value for color in keep.last_find_kwargs["colors"]] == ["red"]
+    assert isinstance(result, list)
+
+
+def test_find_without_colors_passes_none(keep):
+    cli.find(query="q")
+    assert keep.last_find_kwargs["colors"] is None
+
+
+def test_find_invalid_color_raises(keep, monkeypatch):
+    def bad_color(_):
+        raise ValueError("bad")
+
+    monkeypatch.setattr(cli.gkeepapi.node, "ColorValue", bad_color)
+    with pytest.raises(ValueError, match="Invalid color 'invalid'"):
+        cli.find(colors=["invalid"])
+
+
+def test_get(keep):
+    data = cli.get("n1")
+    assert data["id"] == "n1"
+
+
+def test_create_labels_and_sync(keep):
+    data = cli.create(label="keep-agent-mem", title="t", text="body")
+    assert data["id"] == "created"
+    assert keep.sync_calls == 1
+
+
+def test_create_creates_label_when_missing(keep):
+    keep._labels = {}
+    data = cli.create(label="my-custom-label", title="t", text="body")
+    assert data["labels"][0]["name"] == "my-custom-label"
+
+
+def test_update_updates_fields(keep):
+    data = cli.update("n1", title="new", text="changed")
+    assert data["title"] == "new"
+    assert data["text"] == "changed"
+
+
+def test_update_not_found_raises(keep):
+    with pytest.raises(ValueError, match="not found"):
+        cli.update("missing", title="x")
+
+
+def test_delete(keep):
+    data = cli.delete("n1")
+    assert data["message"] == "Note n1 marked for deletion"
+    assert keep.notes["n1"].deleted is True
+    assert keep.sync_calls == 1
+
+
+def test_delete_not_found_raises(keep):
+    with pytest.raises(ValueError, match="not found"):
+        cli.delete("missing")
+
+
+def test_main_runs_stdio_transport(monkeypatch):
+    captured = {}
+
+    def fake_run(*args, **kwargs):
+        captured["transport"] = kwargs.get("transport", "stdio")
+
+    monkeypatch.setattr(cli.mcp, "run", fake_run)
+    cli.main()
+    assert captured["transport"] == "stdio"
+
+
+@pytest.fixture
+async def main_mcp_client(keep):
+    async with Client(cli.mcp) as client:
+        yield client
+
+
+async def test_integration_list_tools(main_mcp_client):
+    tools = await main_mcp_client.list_tools()
+    tool_names = [tool.name for tool in tools]
+    assert "find" in tool_names
+    assert "get" in tool_names
+    assert "create" in tool_names
+    assert "update" in tool_names
+    assert "delete" in tool_names
+
+    # Assert schemas are populated
+    find_tool = next(t for t in tools if t.name == "find")
+    assert "query" in find_tool.inputSchema["properties"]
+    assert "labels" in find_tool.inputSchema["properties"]
+    assert "colors" in find_tool.inputSchema["properties"]
+
+
+async def test_integration_create_note(main_mcp_client, keep):
+    result = await main_mcp_client.call_tool(
+        name="create",
+        arguments={
+            "label": "keep-agent-mem",
+            "title": "Integration test note",
+            "text": "Hello world from integration test",
+        },
+    )
+    assert result.structured_content is not None
+    assert result.structured_content["title"] == "Integration test note"
+    assert result.structured_content["text"] == "Hello world from integration test"
+    assert keep.sync_calls == 1

keep_agent_mem-1.0.0/tests/test_keep_api.py

@@ -0,0 +1,75 @@
+from types import SimpleNamespace
+
+from server.keep_api import serialize_note
+
+
+class DummyLabels:
+    def __init__(self, labels):
+        self._labels = labels
+
+    def all(self):
+        return self._labels
+
+
+class DummyCollaborators:
+    def __init__(self, emails):
+        self._emails = emails
+
+    def all(self):
+        return self._emails
+
+
+class DummyBlobType:
+    def __init__(self, value):
+        self.value = value
+
+
+class DummyBlobNode:
+    def __init__(self, blob_id, blob_type):
+        self.id = blob_id
+        self.blob = SimpleNamespace(type=DummyBlobType(blob_type))
+
+
+class DummyNote:
+    def __init__(self):
+        self.id = "n1"
+        self.title = "title"
+        self.text = "text"
+        self.type = SimpleNamespace(value="NOTE")
+        self.pinned = False
+        self.archived = False
+        self.trashed = False
+        self.color = SimpleNamespace(value="white")
+        self.labels = DummyLabels([SimpleNamespace(id="l1", name="keep-agent-mem")])
+        self.collaborators = DummyCollaborators(["alice@example.com"])
+        self.blobs = [DummyBlobNode("b1", "IMAGE")]
+
+
+class DummyListNote(DummyNote):
+    def __init__(self):
+        super().__init__()
+        self.items = [
+            SimpleNamespace(
+                id="i1",
+                text="item",
+                checked=False,
+                parent_item=None,
+            )
+        ]
+
+
+def test_serialize_note_for_note_type():
+    data = serialize_note(DummyNote())
+    assert data["id"] == "n1"
+    assert data["labels"][0]["name"] == "keep-agent-mem"
+    assert data["collaborators"] == ["alice@example.com"]
+    assert data["media"][0]["type"] == "IMAGE"
+    assert "items" not in data
+
+
+def test_serialize_note_for_list_type():
+    data = serialize_note(DummyListNote())
+    assert data["items"][0]["id"] == "i1"
+
+
+

keep_agent_mem-1.0.0/tests/test_keep_client.py

@@ -0,0 +1,41 @@
+from server import keep_api
+
+
+class DummyKeep:
+    def __init__(self):
+        self.auth_calls = []
+
+    def authenticate(self, email, token):
+        self.auth_calls.append((email, token))
+
+
+def test_get_client_authenticates_and_caches(monkeypatch):
+    keep_api._keep_client = None
+    created = DummyKeep()
+
+    monkeypatch.setattr(keep_api, "load_dotenv", lambda: None)
+    monkeypatch.setattr(keep_api.os, "getenv", lambda key: {
+        "GOOGLE_EMAIL": "user@example.com",
+        "GOOGLE_MASTER_TOKEN": "token",
+    }.get(key))
+    monkeypatch.setattr(keep_api.gkeepapi, "Keep", lambda: created)
+
+    first = keep_api.get_client()
+    second = keep_api.get_client()
+
+    assert first is created
+    assert second is created
+    assert created.auth_calls == [("user@example.com", "token")]
+
+
+def test_get_client_raises_when_missing_credentials(monkeypatch):
+    keep_api._keep_client = None
+    monkeypatch.setattr(keep_api, "load_dotenv", lambda: None)
+    monkeypatch.setattr(keep_api.os, "getenv", lambda _key: None)
+
+    try:
+        keep_api.get_client()
+    except ValueError as exc:
+        assert "Missing Google Keep credentials" in str(exc)
+    else:
+        raise AssertionError("Expected ValueError for missing credentials")

keep_agent_mem-1.0.0/tests/test_main_module.py

@@ -0,0 +1,14 @@
+import runpy
+
+
+def test_main_module_calls_cli_main(monkeypatch):
+    called = {"value": False}
+
+    def fake_main():
+        called["value"] = True
+
+    import server.cli
+
+    monkeypatch.setattr(server.cli, "main", fake_main)
+    runpy.run_module("server.__main__", run_name="__main__")
+    assert called["value"] is True