forgingstack-watchtower 0.1.0__py3-none-any.whl

app/mcp_server.py

@@ -0,0 +1,200 @@
+"""MCP wrapper client for ForgingStack Watchtower, v0.1.0.
+
+An agent-native service must be usable by agents, not just by humans
+with curl. MCP is the standard interface agents already speak, so the
+wrapper exposes the same live REST API as MCP tools, with no duplicated
+logic: every tool call goes through the REST API, so metering and
+receipts stay in one place. The service itself is private; this file
+is only a client.
+
+Protocol: JSON-RPC 2.0 over stdio, no new dependencies (stdlib only).
+Supported methods: initialize, ping, tools/list, tools/call.
+Notifications (no id, e.g. notifications/initialized) get no response.
+
+Environment:
+  FORGINGSTACK_API_BASE  default https://forgingstack-watchtower.jkbattles.workers.dev
+  FORGINGSTACK_API_KEY   required for all tools except check_in;
+                         sign up via POST /v1/signup (key shown once)
+
+Run:  python -m app.mcp_server
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+BASE = os.environ.get(
+    "FORGINGSTACK_API_BASE",
+    "https://forgingstack-watchtower.jkbattles.workers.dev",
+)
+API_KEY = os.environ.get("FORGINGSTACK_API_KEY", "")
+
+TOOLS = [
+    {
+        "name": "create_watch",
+        "description": "Register a liveness watch on an agent. The agent "
+        "must check in at least every interval_seconds (plus grace); if "
+        "it goes quiet past that, Watchtower emails an alert and issues "
+        "a hash-chained receipt. Costs 1 credit. Returns the watch plus "
+        "a check-in key, shown once — save it: the agent checks in with "
+        "it, and it cannot be shown again.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "agent_id": {"type": "string"},
+                "interval_seconds": {"type": "integer"},
+                "grace_seconds": {"type": "integer"},
+                "notify_email": {"type": "string"},
+            },
+            "required": [
+                "agent_id", "interval_seconds", "grace_seconds",
+                "notify_email",
+            ],
+        },
+    },
+    {
+        "name": "check_in",
+        "description": "Check in for a watch. Free. Needs only watch_id "
+        "and the check-in key from watch registration — no API key. "
+        "A check-in after an alert or overdue period returns a "
+        "recovery receipt.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "watch_id": {"type": "integer"},
+                "checkin_key": {"type": "string"},
+            },
+            "required": ["watch_id", "checkin_key"],
+        },
+    },
+    {
+        "name": "get_watch",
+        "description": "Fetch a watch by id, with its current status "
+        "(healthy, overdue, alerted, snoozed) and its last 20 events.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"watch_id": {"type": "integer"}},
+            "required": ["watch_id"],
+        },
+    },
+    {
+        "name": "get_credits",
+        "description": "Remaining credit balance for the configured API key.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "get_receipt",
+        "description": "Fetch a past Watchtower receipt by id. Receipts "
+        "are hash-chained: each receipt's hash covers the previous "
+        "receipt's hash, so tampering breaks the chain.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"receipt_id": {"type": "integer"}},
+            "required": ["receipt_id"],
+        },
+    },
+]
+
+
+def _http(method, path, body=None):
+    req = urllib.request.Request(
+        BASE + path,
+        data=json.dumps(body).encode() if body is not None else None,
+        method=method,
+    )
+    # The check-in endpoint needs no API key; the rest do. Send the key
+    # only when one is configured, so check_in works keyless.
+    if API_KEY:
+        req.add_header("X-API-Key", API_KEY)
+    req.add_header("Content-Type", "application/json")
+    # A User-Agent is required: the default Python urllib agent is
+    # rejected (Cloudflare 1010) through some egress paths.
+    req.add_header("User-Agent", "ForgingStack-Watchtower/0.1.0")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.status, json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except Exception:
+            return e.code, {"detail": "api error"}
+
+
+def _text(payload, is_error=False):
+    return {
+        "content": [{"type": "text", "text": json.dumps(payload)}],
+        "isError": is_error,
+    }
+
+
+def handle(msg):
+    method = msg.get("method")
+    params = msg.get("params") or {}
+    if method == "initialize":
+        return {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "forgingstack-watchtower", "version": "0.1.0"},
+        }
+    if method == "ping":
+        return {}
+    if method == "tools/list":
+        return {"tools": TOOLS}
+    if method == "tools/call":
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        if name == "create_watch":
+            body = {k: args[k] for k in
+                    ("agent_id", "interval_seconds", "grace_seconds",
+                     "notify_email")}
+            status, data = _http("POST", "/v1/watches", body)
+            return _text(data, is_error=status >= 400)
+        if name == "check_in":
+            body = {k: args[k] for k in ("watch_id", "checkin_key")}
+            status, data = _http("POST", "/v1/checkin", body)
+            return _text(data, is_error=status >= 400)
+        if name == "get_watch":
+            status, data = _http(
+                "GET", f"/v1/watches/{args['watch_id']}"
+            )
+            return _text(data, is_error=status >= 400)
+        if name == "get_credits":
+            status, data = _http("GET", "/v1/credits")
+            return _text(data, is_error=status >= 400)
+        if name == "get_receipt":
+            status, data = _http(
+                "GET", f"/v1/receipts/{args['receipt_id']}"
+            )
+            return _text(data, is_error=status >= 400)
+        raise ValueError(f"unknown tool: {name}")
+    raise ValueError(f"unknown method: {method}")
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        # Notifications carry no id and get no response.
+        if "id" not in msg:
+            continue
+        try:
+            result = handle(msg)
+            out = {"jsonrpc": "2.0", "id": msg["id"], "result": result}
+        except Exception as exc:  # noqa: BLE001 - MCP error surface
+            out = {
+                "jsonrpc": "2.0", "id": msg["id"],
+                "error": {"code": -32603, "message": str(exc)},
+            }
+        sys.stdout.write(json.dumps(out) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

forgingstack_watchtower-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: forgingstack-watchtower
+Version: 0.1.0
+Summary: An agent that stops checking in is an agent you hear about.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ForgingStack Watchtower
+
+An agent that stops checking in is an agent you hear about.
+
+mcp-name: io.github.jdkabattles/forgingstack-watchtower
+
+This is the **public client** for Watchtower. The service itself —
+the liveness checks, the alert emails, the receipt chain, the key
+store, and billing — runs on ForgingStack's private service and is
+**not** in this repo. Copying this repo does not give you the service:
+you still need an API key and credits, from signup below.
+
+Live API: https://forgingstack-watchtower.jkbattles.workers.dev
+
+## How it works
+
+1. You register a watch on an agent: how often it should check in
+   (`interval_seconds`, 30 to 2,592,000) plus extra quiet time allowed
+   (`grace_seconds`, 0 to 86,400), and where the alert email goes.
+   One watch per agent per owner. Registering a watch costs 1 credit
+   and returns a check-in key, shown once.
+2. The agent checks in with its watch id and check-in key. Check-ins
+   are free and need no API key.
+3. If the agent goes quiet past its interval plus grace, Watchtower
+   emails an alert and issues a hash-chained receipt. Each alert
+   costs the watch owner 1 credit; an owner at 0 credits is skipped
+   and the watch stays overdue.
+4. When the agent checks in again after an alert or overdue period,
+   a recovery receipt is issued. You can also snooze a watch
+   (1 to 1,440 minutes) to silence alerts for a while.
+
+## Signup (v1)
+
+```bash
+curl -X POST https://forgingstack-watchtower.jkbattles.workers.dev/v1/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com"}'
+```
+
+Returns an API key **once** and 100 starter credits. Save the key
+immediately — it is stored only as a hash and cannot be shown again.
+Click the verification link in the signup email before the key can
+register watches; until then, watch registration returns 403.
+
+## Use it (MCP, stdio)
+
+Set the key, then run the MCP server in this repo:
+
+```bash
+export FORGINGSTACK_API_KEY="your-key-here"
+python -m app.mcp_server
+```
+
+Tools: `create_watch`, `check_in`, `get_watch`, `get_credits`,
+`get_receipt`. See `SKILL.md` for when to use it and when not to.
+
+## Price
+
+1 credit to register a watch, 1 credit per alert, check-ins free.
+100 starter credits on signup. Credit packs: $10 for 1,000 credits,
+bought with `POST /v1/billing/checkout` — credits are added once the
+payment is verified (usually within the hour).
+
+## Files in this repo
+
+- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)
+- `SKILL.md` — when to use it, how to read watch status
+- `agent-card.json` — A2A-style discovery card
+- `server.json` — MCP Registry metadata
+- `pyproject.toml` — package metadata for the MCP client

forgingstack_watchtower-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+app/mcp_server.py,sha256=GpTkpEInv0ff5tAI5_eMG8iCLNCffkDoqR2ahhF8Fnk,7154
+forgingstack_watchtower-0.1.0.dist-info/licenses/LICENSE,sha256=kDoUXgBDydvygXjgDe1nE4S2ZeXHI2C_4tc_-THZ2S4,1073
+forgingstack_watchtower-0.1.0.dist-info/METADATA,sha256=ekafgI8MnCN4WqbuR9l-xPYdzzU-tTsLbsaRrZbfTBw,2953
+forgingstack_watchtower-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+forgingstack_watchtower-0.1.0.dist-info/entry_points.txt,sha256=pjg7AI7nUc_DVEg68et1i9-nDLPS7GwurePCFqdSV84,64
+forgingstack_watchtower-0.1.0.dist-info/top_level.txt,sha256=io9g7LCbfmTG1SFKgEOGXmCFB9uMP2H5lerm0HiHWQE,4
+forgingstack_watchtower-0.1.0.dist-info/RECORD,,

forgingstack_watchtower-0.1.0.dist-info/WHEEL

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

forgingstack_watchtower-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+forgingstack-watchtower = app.mcp_server:main

forgingstack_watchtower-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Battles
+
+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.

forgingstack_watchtower-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+app