agent-notify-mcp 0.1.0__tar.gz

agent_notify_mcp-0.1.0/.gitignore

@@ -0,0 +1,208 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$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
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .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
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.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 static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+notify_config_sample.yaml

agent_notify_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tharindu Mendis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_notify_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: agent-notify-mcp
+Version: 0.1.0
+Summary: Universal MCP notification relay — polls MCP servers and streams change events as log notifications
+Project-URL: Homepage, https://github.com/tharindumendis/agent-notify
+Project-URL: Source, https://github.com/tharindumendis/agent-notify
+Project-URL: Tracker, https://github.com/tharindumendis/agent-notify/issues
+Author: Tharindu Mendis
+License: MIT
+License-File: LICENSE
+Keywords: agent,mcp,notification,polling,telegram
+Classifier: Development Status :: 3 - Alpha
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# agent-notify
+
+Universal MCP notification relay.
+
+Agent_notify polls one or more MCP servers for configured tools and streams any changes as JSON notifications via MCP log events.
+
+## Install (using `uv`)
+
+This repository is designed to work with `uv` (a thin wrapper around `python`/`pip` used throughout this workspace).
+
+```sh
+cd Agent_notify
+uv venv .venv          # creates a virtualenv in .venv
+.venv\Scripts\activate  # Windows (use `source .venv/bin/activate` on macOS/Linux)
+uv sync                 # install dependencies from pyproject.toml
+```
+
+## Quickstart (using `uv run`)
+
+1. Create or edit `notify_config.yaml` (a default example is provided in the repository).
+2. Run the agent:
+
+```sh
+uv run agent-notify
+```
+
+You can override the config path:
+
+```sh
+AGENT_NOTIFY_CONFIG=/path/to/notify_config.yaml uv run agent-notify
+```
+
+> If you prefer, you can still install from PyPI:
+>
+> ```sh
+> pip install agent-notify
+> agent-notify
+> ```
+
+## How it works
+
+- Polls every configured server/tool at `poll_interval` seconds.
+- When a tool's returned value changes between polls, it emits a JSON notification.
+- Notifications are streamed as log events (MCP `ctx.info`) until the client disconnects.
+
+## Usage notes
+
+- Enable debug logging by setting `debug: true` in `notify_config.yaml`.
+- Logs are written to stderr and optionally to `log_file` when configured.

agent_notify_mcp-0.1.0/README.md

@@ -0,0 +1,49 @@
+# agent-notify
+
+Universal MCP notification relay.
+
+Agent_notify polls one or more MCP servers for configured tools and streams any changes as JSON notifications via MCP log events.
+
+## Install (using `uv`)
+
+This repository is designed to work with `uv` (a thin wrapper around `python`/`pip` used throughout this workspace).
+
+```sh
+cd Agent_notify
+uv venv .venv          # creates a virtualenv in .venv
+.venv\Scripts\activate  # Windows (use `source .venv/bin/activate` on macOS/Linux)
+uv sync                 # install dependencies from pyproject.toml
+```
+
+## Quickstart (using `uv run`)
+
+1. Create or edit `notify_config.yaml` (a default example is provided in the repository).
+2. Run the agent:
+
+```sh
+uv run agent-notify
+```
+
+You can override the config path:
+
+```sh
+AGENT_NOTIFY_CONFIG=/path/to/notify_config.yaml uv run agent-notify
+```
+
+> If you prefer, you can still install from PyPI:
+>
+> ```sh
+> pip install agent-notify
+> agent-notify
+> ```
+
+## How it works
+
+- Polls every configured server/tool at `poll_interval` seconds.
+- When a tool's returned value changes between polls, it emits a JSON notification.
+- Notifications are streamed as log events (MCP `ctx.info`) until the client disconnects.
+
+## Usage notes
+
+- Enable debug logging by setting `debug: true` in `notify_config.yaml`.
+- Logs are written to stderr and optionally to `log_file` when configured.

agent_notify_mcp-0.1.0/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+core/__init__.py
+"""

agent_notify_mcp-0.1.0/core/config_loader.py

@@ -0,0 +1,92 @@
+"""
+core/config_loader.py
+----------------------
+Loads and parses notify_config.yaml.
+
+Search order for config file:
+  1. AGENT_NOTIFY_CONFIG environment variable
+  2. ./notify_config.yaml  (current working directory)
+  3. ~/.config/agent-notify/config.yaml
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class ToolPollConfig:
+    """One tool to poll on a server."""
+    name: str
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ServerPollConfig:
+    """One MCP server to connect to and poll."""
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    tools: list[ToolPollConfig] = field(default_factory=list)
+
+
+@dataclass
+class NotifyConfig:
+    poll_interval: int                        # seconds between each poll cycle
+    servers: list[ServerPollConfig]
+    debug: bool = False                       # log every poll cycle
+    log_file: str | None = None               # path to log file (None = stderr only)
+
+
+def load_config(path: str | None = None) -> NotifyConfig:
+    """Load notify_config.yaml from *path* or from the default search order."""
+    if path is None:
+        path = os.environ.get("AGENT_NOTIFY_CONFIG")
+
+    if path is None:
+        candidates = [
+            Path("notify_config.yaml"),
+            Path.home() / ".config" / "agent-notify" / "config.yaml",
+        ]
+        for c in candidates:
+            if c.exists():
+                path = c
+                break
+
+    if path is None:
+        raise FileNotFoundError(
+            "notify_config.yaml not found. "
+            "Create one in the current directory or set AGENT_NOTIFY_CONFIG."
+        )
+
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    servers: list[ServerPollConfig] = []
+    for s in data.get("servers", []):
+        tools = [
+            ToolPollConfig(name=t["tool"], args=t.get("args", {}))
+            for t in s.get("tools", [])
+        ]
+        servers.append(
+            ServerPollConfig(
+                name=s["name"],
+                command=s["command"],
+                args=s.get("args", []),
+                env=s.get("env", {}),
+                tools=tools,
+            )
+        )
+
+    return NotifyConfig(
+        poll_interval=int(data.get("poll_interval", 30)),
+        servers=servers,
+        debug=bool(data.get("debug", False)),
+        log_file=data.get("log_file", None),
+    )

agent_notify_mcp-0.1.0/core/differ.py

@@ -0,0 +1,88 @@
+"""
+core/differ.py
+--------------
+Compares old vs new MCP tool responses and returns a change summary,
+or None if nothing changed.
+
+Handles:
+  - JSON arrays  → finds added / removed items by stable ID
+  - JSON objects → reports key-level diff
+  - scalars      → reports old vs new value
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def _stable_id(item: Any) -> str:
+    """Extract or derive a stable string ID from an item."""
+    if isinstance(item, dict):
+        for key in ("id", "message_id", "msgId", "uid", "number",
+                    "pr_number", "sha", "iid", "key", "name"):
+            if key in item:
+                return str(item[key])
+    return hashlib.md5(
+        json.dumps(item, sort_keys=True, default=str).encode()
+    ).hexdigest()
+
+
+def diff_results(old_raw: str | None, new_raw: str | None) -> dict | None:
+    """
+    Compare *old_raw* and *new_raw* (JSON strings from MCP tool responses).
+
+    Returns a change dict, or None if there is no meaningful change.
+
+    Change dict shape:
+        { "added": [...] }          – new list items
+        { "removed": [...] }        – removed list items
+        { "added": [...], "removed": [...] }
+        { "changed": {"from": ..., "to": ...} }  – scalar / dict change
+    """
+    if old_raw == new_raw:
+        return None
+
+    try:
+        old = json.loads(old_raw) if isinstance(old_raw, str) else old_raw
+        new = json.loads(new_raw) if isinstance(new_raw, str) else new_raw
+
+        # ── List diff ─────────────────────────────────────────────────────────
+        if isinstance(old, list) and isinstance(new, list):
+            old_map = {_stable_id(i): i for i in old}
+            new_map = {_stable_id(i): i for i in new}
+
+            added   = [i for k, i in new_map.items() if k not in old_map]
+            removed = [i for k, i in old_map.items() if k not in new_map]
+
+            changes: dict = {}
+            if added:
+                changes["added"] = added
+            if removed:
+                changes["removed"] = removed
+            return changes or None
+
+        # ── Dict diff  ────────────────────────────────────────────────────────
+        if isinstance(old, dict) and isinstance(new, dict):
+            all_keys = set(old) | set(new)
+            changed_keys = {k for k in all_keys if old.get(k) != new.get(k)}
+            if not changed_keys:
+                return None
+            return {
+                "changed": {
+                    k: {"from": old.get(k), "to": new.get(k)}
+                    for k in changed_keys
+                }
+            }
+
+        # ── Scalar  ───────────────────────────────────────────────────────────
+        if old != new:
+            return {"changed": {"from": old, "to": new}}
+
+        return None
+
+    except (json.JSONDecodeError, TypeError):
+        if old_raw != new_raw:
+            return {"changed": {"from": old_raw, "to": new_raw}}
+        return None

agent_notify_mcp-0.1.0/core/poller.py

@@ -0,0 +1,134 @@
+"""
+core/poller.py
+--------------
+Connects to all configured MCP servers as a CLIENT, then polls each
+server's configured tools on every tick, diffing results to detect changes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from contextlib import AsyncExitStack
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from core.config_loader import NotifyConfig
+from core.differ import diff_results
+
+
+class Poller:
+    """
+    Manages persistent MCP client connections to all configured servers
+    and polls their tools on each call to poll_all().
+    """
+
+    def __init__(self, config: NotifyConfig) -> None:
+        self.config = config
+        self._sessions: dict[str, ClientSession] = {}
+        self._last_results: dict[str, str | None] = {}
+        self._stack = AsyncExitStack()
+
+    # ── Context manager ───────────────────────────────────────────────────────
+
+    async def __aenter__(self) -> "Poller":
+        await self._stack.__aenter__()
+        for server in self.config.servers:
+            try:
+                env = {**os.environ, **server.env}
+                params = StdioServerParameters(
+                    command=server.command,
+                    args=server.args,
+                    env=env,
+                )
+                transport = await self._stack.enter_async_context(
+                    stdio_client(params)
+                )
+                read, write = transport
+                session = await self._stack.enter_async_context(
+                    ClientSession(read, write)
+                )
+                await session.initialize()
+                self._sessions[server.name] = session
+            except Exception as exc:
+                # Partial failure — log to stderr, continue with other servers
+                import sys
+                print(
+                    f"[agent-notify] WARNING: could not connect to '{server.name}': {exc}",
+                    file=sys.stderr,
+                )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._stack.__aexit__(*args)
+
+    # ── Polling ───────────────────────────────────────────────────────────────
+
+    async def poll_all(self, first_poll: bool = False) -> list[dict]:
+        """
+        Call every configured tool on every connected server.
+        Compare results to the previous poll and return a list of change events.
+
+        On *first_poll* we only baseline the results (no changes emitted).
+        """
+        events: list[dict] = []
+
+        for server in self.config.servers:
+            session = self._sessions.get(server.name)
+            if session is None:
+                continue
+
+            for tool_cfg in server.tools:
+                key = f"{server.name}::{tool_cfg.name}"
+
+                try:
+                    result = await asyncio.wait_for(
+                        session.call_tool(tool_cfg.name, arguments=tool_cfg.args),
+                        timeout=30.0,
+                    )
+
+                    # Extract the text payload from the MCP result
+                    new_data: str | None = None
+                    for content in result.content or []:
+                        if hasattr(content, "text") and content.text:
+                            new_data = content.text
+                            break
+
+                    old_data = self._last_results.get(key)
+                    self._last_results[key] = new_data
+
+                    # First poll: baseline only — emit nothing
+                    if first_poll:
+                        continue
+
+                    # Skip if we have nothing to compare yet
+                    if old_data is None or new_data is None:
+                        continue
+
+                    change = diff_results(old_data, new_data)
+                    if change:
+                        events.append({
+                            "server": server.name,
+                            "tool":   tool_cfg.name,
+                            "change": change,
+                        })
+
+                except asyncio.TimeoutError:
+                    if not first_poll:
+                        events.append({
+                            "server": server.name,
+                            "tool":   tool_cfg.name,
+                            "error":  "Tool call timed out (30 s)",
+                        })
+
+                except Exception as exc:
+                    if not first_poll:
+                        events.append({
+                            "server": server.name,
+                            "tool":   tool_cfg.name,
+                            "error":  str(exc),
+                        })
+
+        return events

agent_notify_mcp-0.1.0/notify_config.yaml

@@ -0,0 +1,56 @@
+# ─────────────────────────────────────────────────────────────────
+# Agent_notify — notify_config.yaml
+# ─────────────────────────────────────────────────────────────────
+#
+# This file tells Agent_notify which MCP servers to connect to
+# and which tools to poll. Any change in a tool's response between
+# polls is emitted as a JSON notification to the subscriber.
+#
+# EACH server entry uses the SAME format as MCP client config —
+# command + args + env, exactly as you'd put in claude_desktop or
+# Agent_head's config.yaml.
+# ─────────────────────────────────────────────────────────────────
+
+# How often to poll every server/tool (in seconds).
+poll_interval: 15
+
+# Debug mode: logs every poll cycle to a file.
+debug: true
+log_file: "D:\\DEV\\mcp\\universai\\orchestra\\Agent_notify\\agent_notify.log"
+
+servers:
+  # ── Telegram ──────────────────────────────────────────────────
+  - name: telegram
+    command: npx
+    args: ["-y", "@tharindumendis100/tgcli", "mcp", "--transport", "stdio"]
+    env:
+      TELEGRAM_API_ID: "your_telegram_api_id"
+      TELEGRAM_API_HASH: "your_telegram_api_hash"
+    tools:
+      # Detect new incoming messages in your personal inbox
+      - tool: listActiveChannels
+        args: {}
+
+      # Detect new messages in a specific group/channel (optional)
+      - tool: messagesList
+        args:
+          channelId: "1173401646"
+          limit: 5
+
+  # ── GitHub (optional) ─────────────────────────────────────────
+  # - name: github
+  #   command: npx
+  #   args: ["-y", "@modelcontextprotocol/server-github"]
+  #   env:
+  #     GITHUB_PERSONAL_ACCESS_TOKEN: "your_github_token"
+  #   tools:
+  #     # Detect new issues opened in your repo
+  #     - tool: list_issues
+  #       args:
+  #         owner: "your_github_username"
+  #         repo:  "your_repo_name"
+  #         state: "open"
+
+  # ── Any other MCP server ──────────────────────────────────────
+  # Add more servers the same way. Any MCP tool that returns a
+  # list or a value can be monitored for changes.

agent_notify_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-notify-mcp"
+version = "0.1.0"
+description = "Universal MCP notification relay — polls MCP servers and streams change events as log notifications"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Tharindu Mendis" }]
+keywords = ["mcp", "notification", "agent", "telegram", "polling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://github.com/tharindumendis/agent-notify"
+Source = "https://github.com/tharindumendis/agent-notify"
+Tracker = "https://github.com/tharindumendis/agent-notify/issues"
+
+[project.scripts]
+agent-notify = "server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["core"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"server.py" = "server.py"
+"notify_config.yaml" = "notify_config.yaml"
+"LICENSE" = "LICENSE"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "core/",
+    "server.py",
+    "notify_config.yaml",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]

agent_notify_mcp-0.1.0/server.py

@@ -0,0 +1,209 @@
+"""
+server.py — Agent_notify MCP Server
+--------------------------------------
+A FastMCP server that exposes a single long-running tool: get_notifications().
+
+When called, it:
+  1. Connects to all MCP servers listed in notify_config.yaml
+  2. Polls configured tools at poll_interval seconds
+  3. Diffs each result against the previous poll
+  4. Sends every change as a ctx.info(json) log notification WITHOUT
+     closing the tool call — the client receives a stream of events
+
+Debug mode (debug: true in notify_config.yaml):
+  - Logs every poll cycle to the configured log_file
+  - Format: timestamped lines with server/tool/status/changes
+
+Usage:
+    agent-notify                          # uses notify_config.yaml in cwd
+    AGENT_NOTIFY_CONFIG=/path/to/cfg.yaml agent-notify
+    uvx agent-notify
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP, Context
+
+from core.config_loader import NotifyConfig, load_config
+from core.poller import Poller
+
+mcp = FastMCP(
+    "agent-notify",
+    instructions=(
+        "Universal MCP notification relay. "
+        "Call get_notifications() to subscribe to real-time change events "
+        "from all configured MCP servers. "
+        "Events are streamed as log notifications (ctx.info) — "
+        "the tool call does not return until the client disconnects."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Debug logger
+# ---------------------------------------------------------------------------
+
+def _make_logger(config: NotifyConfig) -> logging.Logger:
+    """Set up a file logger when debug=true, else a null logger."""
+    log = logging.getLogger("agent_notify")
+    log.setLevel(logging.DEBUG if config.debug else logging.WARNING)
+    log.handlers.clear()
+
+    if config.debug:
+        fmt = logging.Formatter("%(asctime)s | %(levelname)-5s | %(message)s",
+                                datefmt="%Y-%m-%d %H:%M:%S")
+
+        # Always write to stderr
+        sh = logging.StreamHandler(sys.stderr)
+        sh.setFormatter(fmt)
+        log.addHandler(sh)
+
+        # Optionally also write to a file
+        if config.log_file:
+            log_path = Path(config.log_file)
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            fh = logging.FileHandler(log_path, encoding="utf-8")
+            fh.setFormatter(fmt)
+            log.addHandler(fh)
+
+    return log
+
+
+# ---------------------------------------------------------------------------
+# Tool
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def get_notifications(ctx: Context) -> str:
+    """
+    Subscribe to real-time change notifications from configured MCP servers.
+
+    This tool NEVER returns normally — it streams JSON change events as
+    log notifications (ctx.info) until the client disconnects or cancels.
+
+    Each notification is a JSON object:
+        {
+          "server": "<server_name>",
+          "tool":   "<tool_name>",
+          "change": {
+            "added":   [...],   // new items in a list result
+            "removed": [...],   // removed items
+            // OR
+            "changed": { "from": ..., "to": ... }
+          }
+        }
+
+    On error polling a tool:
+        { "server": "...", "tool": "...", "error": "reason" }
+    """
+    # Load config fresh on each call (supports hot-reload)
+    try:
+        config = load_config()
+    except FileNotFoundError as exc:
+        await ctx.error(str(exc))
+        return f"ERROR: {exc}"
+
+    log = _make_logger(config)
+
+    n_servers = len(config.servers)
+    n_tools   = sum(len(s.tools) for s in config.servers)
+
+    log.info("Agent Notify starting | servers=%d tools=%d interval=%ds debug=%s log=%s",
+             n_servers, n_tools, config.poll_interval, config.debug, config.log_file or "stderr")
+
+    started_msg = {
+        "type":             "started",
+        "servers":          n_servers,
+        "tools":            n_tools,
+        "interval_seconds": config.poll_interval,
+        "debug":            config.debug,
+        "log_file":         config.log_file,
+        "message": (
+            f"Agent Notify: monitoring {n_tools} tool(s) across "
+            f"{n_servers} server(s) every {config.poll_interval}s"
+        ),
+    }
+    await ctx.info(json.dumps(started_msg))
+
+    try:
+        async with Poller(config) as poller:
+            cycle = 0
+            first = True
+
+            while True:
+                cycle += 1
+                cycle_start = datetime.now()
+
+                log.debug("── Poll cycle #%d started at %s", cycle, cycle_start.strftime("%H:%M:%S"))
+
+                try:
+                    events = await poller.poll_all(first_poll=first)
+                    first = False
+
+                    cycle_ms = int((datetime.now() - cycle_start).total_seconds() * 1000)
+
+                    if config.debug:
+                        # Log summary for every server/tool polled
+                        for server in config.servers:
+                            for tool_cfg in server.tools:
+                                key = f"{server.name}/{tool_cfg.name}"
+                                # Find matching event if any
+                                match = next(
+                                    (e for e in events
+                                     if e.get("server") == server.name
+                                     and e.get("tool") == tool_cfg.name),
+                                    None
+                                )
+                                if match and "error" in match:
+                                    log.warning("  [%s] ERROR: %s", key, match["error"])
+                                elif match:
+                                    change = match.get("change", {})
+                                    added   = len(change.get("added", []))
+                                    removed = len(change.get("removed", []))
+                                    log.debug("  [%s] CHANGED | +%d -%d items", key, added, removed)
+                                else:
+                                    log.debug("  [%s] no change", key)
+
+                        log.debug("── Cycle #%d done in %dms | %d change(s)",
+                                  cycle, cycle_ms, len(events))
+
+                    # Emit events to client
+                    for event in events:
+                        log.info("NOTIFY → %s", json.dumps(event))
+                        await ctx.info(json.dumps(event))
+
+                except Exception as poll_exc:
+                    log.error("Poll cycle #%d failed: %s", cycle, poll_exc, exc_info=True)
+                    await ctx.warning(json.dumps({
+                        "type":  "poll_cycle_error",
+                        "cycle": cycle,
+                        "error": str(poll_exc),
+                    }))
+
+                log.debug("Sleeping %ds until cycle #%d …", config.poll_interval, cycle + 1)
+                await asyncio.sleep(config.poll_interval)
+
+    except asyncio.CancelledError:
+        log.info("Agent Notify: subscription cancelled by client.")
+
+    return "Agent Notify: subscription ended."
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Entry point for `agent-notify` CLI command."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()