stamp-mcp 0.3.0__tar.gz

stamp_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: stamp-mcp
+Version: 0.3.0
+Summary: MCP server for NTP time and clock drift: each query is logged, so drift trends (stable vs. accelerating) are visible. Zero dependencies, raw JSON-RPC over stdio.
+Author: theoddden
+License: MIT
+Project-URL: Repository, https://github.com/theoddden/stamp-mcp
+Keywords: mcp,model-context-protocol,ntp,time,clock-drift,drift
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# stamp-mcp
+
+<!-- mcp-name: io.github.theoddden/stamp -->
+
+An MCP server for NTP time and clock drift. Zero dependencies, fully
+synchronous, raw JSON-RPC 2.0 over stdio -- no MCP library, no asyncio.
+
+A single NTP query tells you where your clock is right now. Drift history
+tells you where it is going: a clock that is consistently 200ms fast and
+accelerating is a different problem than one that is stable at 200ms fast.
+`get_time` takes the measurement; every call appends to a local log;
+`get_drift` reads the log and reports the trend.
+
+## Install
+
+```bash
+pip install stamp-mcp
+```
+
+## Use with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "stamp-mcp"
+    }
+  }
+}
+```
+
+Or run the module directly:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "python3",
+      "args": ["-m", "stamp_mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+- **`get_time`** -- one NTP query: UTC time, this clock's offset in ms,
+  network delay, stratum. Appends the sample to the drift log. Optional
+  argument: `server` (default `time.cloudflare.com`).
+- **`get_drift`** -- analyzes the drift log: sample count, timespan,
+  current/mean/stddev offset, drift rate in ms/day (least-squares fit),
+  first-half vs. second-half rates, and a verdict: `stable`, `drifting`,
+  or `accelerating`. Optional argument: `server` to filter samples.
+
+## The drift log
+
+Every `get_time` call appends one JSON line to `~/.stamp/drift.jsonl`
+(override with `STAMP_DRIFT_LOG`). The file is capped at 10,000 samples.
+Call `get_time` periodically -- a cron job, a heartbeat, or just asking
+Claude "check the clock" now and then -- and `get_drift` turns the
+accumulated offsets into a trend.
+
+## How it works
+
+The whole server is `stamp_mcp/server.py`:
+
+- **JSON-RPC 2.0 over stdio** -- `initialize`, `tools/list`, `tools/call`,
+  `ping`, notifications, and the standard error codes (`-32700`, `-32601`).
+- **Raw NTP with real offset math** -- a 48-byte NTPv3 packet over UDP 123
+  carrying our transmit timestamp; the response's receive (t2) and
+  transmit (t3) timestamps are unpacked with `struct.unpack("!II", ...)`
+  as 64-bit fixed point, and offset/delay follow RFC 5905:
+  `offset = ((t2-t1)+(t3-t4))/2`, `delay = (t4-t1)-(t3-t2)`.
+- **Two rules that matter**: stdout is the protocol channel (log to stderr
+  only), and `flush()` after every write (subprocess stdout is
+  block-buffered).
+
+## Development
+
+`client.py` is a test harness that plays the role of an MCP host -- it
+spawns the server and performs the real handshake, printing every raw
+frame:
+
+```bash
+python3 client.py                          # tests server.py (stage 1)
+python3 client.py server_atomic.py         # tests the standalone artifact
+python3 client.py stamp_mcp/server.py      # tests the package
+```
+
+`server.py` and `server_atomic.py` are the from-scratch learning artifacts;
+`stamp_mcp/` is the packaged, published server.
+
+## Publishing
+
+The GitHub Action in `.github/workflows/publish-mcp.yml` runs on version
+tags (`git tag v0.3.0 && git push origin v0.3.0`) and does two things:
+
+1. **Publishes the package to PyPI** -- requires a `PYPI_API_TOKEN`
+   repository secret (or configure Trusted Publishing on PyPI and remove
+   the `password` line).
+2. **Publishes metadata to the MCP Registry** -- uses `mcp-publisher` with
+   GitHub OIDC (`id-token: write`), no secret needed. The server name
+   `io.github.theoddden/stamp` is bound to the GitHub account; the
+   `mcp-name` HTML comment at the top of this README is the PyPI ownership
+   verification marker.
+
+---
+
+# Appendix: how this was built, stage by stage
+
+Build an MCP server with no library, one concept at a time. By the end you
+will have written every line yourself and the official MCP SDK becomes a
+convenience you could discard.
+
+## Stage 1 -- raw JSON-RPC over stdio (DONE, verified)
+
+- `server.py` -- the entire protocol in ~100 lines: `sys.stdin` -> `json` ->
+  dispatch -> `sys.stdout` -> `flush()`.
+- `client.py` -- plays the role of Claude Desktop. Spawns the server and
+  performs the real handshake, printing every raw frame.
+
+Run it:
+
+```bash
+python3 client.py
+```
+
+Things to notice in the output:
+
+- `initialize` returns `protocolVersion`, `capabilities`, `serverInfo`.
+- `notifications/initialized` has **no `id`** and gets **no response**.
+- `tools/list` returns the manifest; `inputSchema` is plain JSON Schema.
+- `tools/call` results are `{"content": [{"type": "text", ...}]}`.
+- Unknown **method** -> JSON-RPC error `-32601`.
+- Unknown **tool** -> a normal result with `isError: true` (so the model can
+  read the failure and recover).
+- Malformed JSON -> `-32700`.
+
+Two rules that will bite you if ignored:
+
+1. **stdout is the protocol channel.** One stray `print()` corrupts the
+   stream. Log to stderr only.
+2. **flush() after every write.** As a subprocess, stdout is block-buffered;
+   without flush the host thinks the server is dead.
+
+## Stage 2 -- asyncio
+
+Rewrite the stdin loop as an async coroutine:
+
+- `async def main()` + `asyncio.run(main())`
+- Read stdin without blocking the loop:
+  `loop.run_in_executor(None, sys.stdin.readline)` or
+  `asyncio.StreamReader` hooked to stdin via `loop.connect_read_pipe`.
+- `await` each handler.
+
+The payoff comes in stage 4 -- for now it is the same server with a
+different engine.
+
+## Stage 3 -- real NTP
+
+Replace the stub `get_time` with a real query.
+
+- First pass: `pip install ntplib`, then
+  `ntplib.NTPClient().request('pool.ntp.org', version=3)`.
+- Second pass (optional, illuminating): delete ntplib and write the UDP
+  query yourself. NTPv3 packet = 48 bytes, first byte `0x1B` (LI=0, VN=3,
+  Mode=3), rest zeros. Send to port 123, read 48 bytes back, unpack the
+  transmit timestamp (bytes 40-43, seconds since 1900) with
+  `struct.unpack('!I', ...)`. Subtract 2208988800 to get Unix time.
+  ntplib is ~200 lines of exactly this -- read its source once.
+
+## Stage 4 -- blocking vs. the event loop
+
+The lesson you learn by breaking it:
+
+1. Call `ntplib` **directly** inside your `async def` handler.
+2. While a slow NTP server is being queried, send a `ping` from the client.
+   Watch it hang -- the single-threaded event loop is frozen.
+3. Fix it: `await loop.run_in_executor(None, blocking_ntp_call)`.
+   Blocking work goes to the thread pool; async work gets awaited.
+
+Rule of thumb: `ntplib`, `requests`, file I/O = blocking. `aiohttp`,
+`httpx` (async mode), `asyncpg` = not blocking.
+
+## Connecting to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ntp-scratch": {
+      "command": "/usr/bin/python3",
+      "args": ["/Users/theowolfenden/CascadeProjects/mcp-from-scratch/server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then ask it "what tools do you have?" -- `get_time`
+should appear. If it doesn't, check the logs at
+`~/Library/Logs/Claude/mcp*.log` -- a stray print or missing flush is the
+usual culprit.
+
+## The wire protocol, in one glance
+
+```
+>>> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
+<<< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
+>>> {"jsonrpc":"2.0","method":"notifications/initialized"}     (no reply)
+>>> {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+<<< {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
+>>> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_time","arguments":{}}}
+<<< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}
+```
+
+That is the whole thing. Everything else is plumbing.

stamp_mcp-0.3.0/README.md

@@ -0,0 +1,219 @@
+# stamp-mcp
+
+<!-- mcp-name: io.github.theoddden/stamp -->
+
+An MCP server for NTP time and clock drift. Zero dependencies, fully
+synchronous, raw JSON-RPC 2.0 over stdio -- no MCP library, no asyncio.
+
+A single NTP query tells you where your clock is right now. Drift history
+tells you where it is going: a clock that is consistently 200ms fast and
+accelerating is a different problem than one that is stable at 200ms fast.
+`get_time` takes the measurement; every call appends to a local log;
+`get_drift` reads the log and reports the trend.
+
+## Install
+
+```bash
+pip install stamp-mcp
+```
+
+## Use with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "stamp-mcp"
+    }
+  }
+}
+```
+
+Or run the module directly:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "python3",
+      "args": ["-m", "stamp_mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+- **`get_time`** -- one NTP query: UTC time, this clock's offset in ms,
+  network delay, stratum. Appends the sample to the drift log. Optional
+  argument: `server` (default `time.cloudflare.com`).
+- **`get_drift`** -- analyzes the drift log: sample count, timespan,
+  current/mean/stddev offset, drift rate in ms/day (least-squares fit),
+  first-half vs. second-half rates, and a verdict: `stable`, `drifting`,
+  or `accelerating`. Optional argument: `server` to filter samples.
+
+## The drift log
+
+Every `get_time` call appends one JSON line to `~/.stamp/drift.jsonl`
+(override with `STAMP_DRIFT_LOG`). The file is capped at 10,000 samples.
+Call `get_time` periodically -- a cron job, a heartbeat, or just asking
+Claude "check the clock" now and then -- and `get_drift` turns the
+accumulated offsets into a trend.
+
+## How it works
+
+The whole server is `stamp_mcp/server.py`:
+
+- **JSON-RPC 2.0 over stdio** -- `initialize`, `tools/list`, `tools/call`,
+  `ping`, notifications, and the standard error codes (`-32700`, `-32601`).
+- **Raw NTP with real offset math** -- a 48-byte NTPv3 packet over UDP 123
+  carrying our transmit timestamp; the response's receive (t2) and
+  transmit (t3) timestamps are unpacked with `struct.unpack("!II", ...)`
+  as 64-bit fixed point, and offset/delay follow RFC 5905:
+  `offset = ((t2-t1)+(t3-t4))/2`, `delay = (t4-t1)-(t3-t2)`.
+- **Two rules that matter**: stdout is the protocol channel (log to stderr
+  only), and `flush()` after every write (subprocess stdout is
+  block-buffered).
+
+## Development
+
+`client.py` is a test harness that plays the role of an MCP host -- it
+spawns the server and performs the real handshake, printing every raw
+frame:
+
+```bash
+python3 client.py                          # tests server.py (stage 1)
+python3 client.py server_atomic.py         # tests the standalone artifact
+python3 client.py stamp_mcp/server.py      # tests the package
+```
+
+`server.py` and `server_atomic.py` are the from-scratch learning artifacts;
+`stamp_mcp/` is the packaged, published server.
+
+## Publishing
+
+The GitHub Action in `.github/workflows/publish-mcp.yml` runs on version
+tags (`git tag v0.3.0 && git push origin v0.3.0`) and does two things:
+
+1. **Publishes the package to PyPI** -- requires a `PYPI_API_TOKEN`
+   repository secret (or configure Trusted Publishing on PyPI and remove
+   the `password` line).
+2. **Publishes metadata to the MCP Registry** -- uses `mcp-publisher` with
+   GitHub OIDC (`id-token: write`), no secret needed. The server name
+   `io.github.theoddden/stamp` is bound to the GitHub account; the
+   `mcp-name` HTML comment at the top of this README is the PyPI ownership
+   verification marker.
+
+---
+
+# Appendix: how this was built, stage by stage
+
+Build an MCP server with no library, one concept at a time. By the end you
+will have written every line yourself and the official MCP SDK becomes a
+convenience you could discard.
+
+## Stage 1 -- raw JSON-RPC over stdio (DONE, verified)
+
+- `server.py` -- the entire protocol in ~100 lines: `sys.stdin` -> `json` ->
+  dispatch -> `sys.stdout` -> `flush()`.
+- `client.py` -- plays the role of Claude Desktop. Spawns the server and
+  performs the real handshake, printing every raw frame.
+
+Run it:
+
+```bash
+python3 client.py
+```
+
+Things to notice in the output:
+
+- `initialize` returns `protocolVersion`, `capabilities`, `serverInfo`.
+- `notifications/initialized` has **no `id`** and gets **no response**.
+- `tools/list` returns the manifest; `inputSchema` is plain JSON Schema.
+- `tools/call` results are `{"content": [{"type": "text", ...}]}`.
+- Unknown **method** -> JSON-RPC error `-32601`.
+- Unknown **tool** -> a normal result with `isError: true` (so the model can
+  read the failure and recover).
+- Malformed JSON -> `-32700`.
+
+Two rules that will bite you if ignored:
+
+1. **stdout is the protocol channel.** One stray `print()` corrupts the
+   stream. Log to stderr only.
+2. **flush() after every write.** As a subprocess, stdout is block-buffered;
+   without flush the host thinks the server is dead.
+
+## Stage 2 -- asyncio
+
+Rewrite the stdin loop as an async coroutine:
+
+- `async def main()` + `asyncio.run(main())`
+- Read stdin without blocking the loop:
+  `loop.run_in_executor(None, sys.stdin.readline)` or
+  `asyncio.StreamReader` hooked to stdin via `loop.connect_read_pipe`.
+- `await` each handler.
+
+The payoff comes in stage 4 -- for now it is the same server with a
+different engine.
+
+## Stage 3 -- real NTP
+
+Replace the stub `get_time` with a real query.
+
+- First pass: `pip install ntplib`, then
+  `ntplib.NTPClient().request('pool.ntp.org', version=3)`.
+- Second pass (optional, illuminating): delete ntplib and write the UDP
+  query yourself. NTPv3 packet = 48 bytes, first byte `0x1B` (LI=0, VN=3,
+  Mode=3), rest zeros. Send to port 123, read 48 bytes back, unpack the
+  transmit timestamp (bytes 40-43, seconds since 1900) with
+  `struct.unpack('!I', ...)`. Subtract 2208988800 to get Unix time.
+  ntplib is ~200 lines of exactly this -- read its source once.
+
+## Stage 4 -- blocking vs. the event loop
+
+The lesson you learn by breaking it:
+
+1. Call `ntplib` **directly** inside your `async def` handler.
+2. While a slow NTP server is being queried, send a `ping` from the client.
+   Watch it hang -- the single-threaded event loop is frozen.
+3. Fix it: `await loop.run_in_executor(None, blocking_ntp_call)`.
+   Blocking work goes to the thread pool; async work gets awaited.
+
+Rule of thumb: `ntplib`, `requests`, file I/O = blocking. `aiohttp`,
+`httpx` (async mode), `asyncpg` = not blocking.
+
+## Connecting to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ntp-scratch": {
+      "command": "/usr/bin/python3",
+      "args": ["/Users/theowolfenden/CascadeProjects/mcp-from-scratch/server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then ask it "what tools do you have?" -- `get_time`
+should appear. If it doesn't, check the logs at
+`~/Library/Logs/Claude/mcp*.log` -- a stray print or missing flush is the
+usual culprit.
+
+## The wire protocol, in one glance
+
+```
+>>> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
+<<< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
+>>> {"jsonrpc":"2.0","method":"notifications/initialized"}     (no reply)
+>>> {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+<<< {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
+>>> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_time","arguments":{}}}
+<<< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}
+```
+
+That is the whole thing. Everything else is plumbing.

stamp_mcp-0.3.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stamp-mcp"
+version = "0.3.0"
+description = "MCP server for NTP time and clock drift: each query is logged, so drift trends (stable vs. accelerating) are visible. Zero dependencies, raw JSON-RPC over stdio."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "theoddden" }]
+keywords = ["mcp", "model-context-protocol", "ntp", "time", "clock-drift", "drift"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/theoddden/stamp-mcp"
+
+[project.scripts]
+stamp-mcp = "stamp_mcp.server:main"
+
+[tool.setuptools.packages.find]
+include = ["stamp_mcp*"]

stamp_mcp-0.3.0/setup.cfg

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

stamp_mcp-0.3.0/stamp_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""stamp-mcp: zero-dependency MCP server for NTP time and clock drift."""
+
+__version__ = "0.3.0"

stamp_mcp-0.3.0/stamp_mcp/__main__.py

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

stamp_mcp-0.3.0/stamp_mcp/server.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""
+stamp -- a minimal MCP server for clock drift, with zero dependencies.
+
+No MCP library, no asyncio. The entire protocol is:
+
+    read line from stdin -> parse JSON-RPC -> dispatch -> write line -> flush
+
+Two tools:
+
+    get_time   -- one NTP query: current UTC time + clock offset, and
+                  appends the sample to a local JSONL drift log.
+    get_drift  -- reads the drift log and reports the trend: mean offset,
+                  drift rate (least-squares slope), and whether the offset
+                  is stable, drifting, or accelerating.
+
+A single NTP query tells you where your clock is. The log tells you where
+it is going: +200ms stable is a different problem than +200ms accelerating.
+
+The NTP query is raw socket + struct: a 48-byte NTPv3 packet over UDP
+port 123, with full four-timestamp offset/delay math (RFC 5905).
+"""
+
+import sys
+import os
+import json
+import socket
+import struct
+import time
+from datetime import datetime, timezone
+
+NTP_DELTA = 2208988800  # seconds between 1900 (NTP epoch) and 1970 (Unix)
+
+# Where drift samples accumulate. One JSON object per line. Override with
+# STAMP_DRIFT_LOG if you want it elsewhere.
+DRIFT_LOG = os.environ.get(
+    "STAMP_DRIFT_LOG", os.path.expanduser("~/.stamp/drift.jsonl")
+)
+DRIFT_LOG_MAX = 10000  # keep the file bounded: trim to last half when hit
+
+TOOLS = [
+    {
+        "name": "get_time",
+        "description": "Query an NTP server for current UTC time and this "
+                       "clock's offset, and append the sample to the drift "
+                       "log. Call it periodically to build drift history.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "server": {
+                    "type": "string",
+                    "description": "NTP server to query",
+                    "default": "time.cloudflare.com",
+                }
+            },
+        },
+    },
+    {
+        "name": "get_drift",
+        "description": "Analyze the drift log built by get_time: reports "
+                       "current offset, drift rate (ms/day), and whether "
+                       "the clock is stable, drifting, or accelerating.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "server": {
+                    "type": "string",
+                    "description": "Only analyze samples from this NTP server",
+                }
+            },
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# NTP: the four timestamps of RFC 5905
+#
+#   t1 = client send time      t2 = server receive time
+#   t3 = server transmit time  t4 = client receive time
+#
+#   offset = ((t2 - t1) + (t3 - t4)) / 2   -- how far our clock is off
+#   delay  = (t4 - t1) - (t3 - t2)         -- round-trip network time
+#
+# NTP timestamps are 64-bit fixed point: 32s seconds + 32s fraction.
+# ---------------------------------------------------------------------------
+
+def _ntp_to_unix(data, offset):
+    """Read an 8-byte NTP timestamp at byte `offset`, return Unix seconds."""
+    sec, frac = struct.unpack("!II", data[offset:offset + 8])
+    return sec - NTP_DELTA + frac / 2**32
+
+
+def query_time(server="time.cloudflare.com"):
+    """One NTPv3 query over UDP, returning time AND clock offset."""
+    pkt = bytearray(48)
+    pkt[0] = 0x1B  # LI 0, Version 3, Mode 3 (client)
+    # Put our send time in the transmit field; the server echoes it back
+    # as the originate timestamp.
+    t1 = time.time()
+    sec = int(t1) + NTP_DELTA
+    frac = int((t1 - int(t1)) * 2**32)
+    struct.pack_into("!II", pkt, 40, sec, frac)
+
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    s.settimeout(5)
+    try:
+        s.sendto(bytes(pkt), (server, 123))
+        data, _ = s.recvfrom(48)
+        t4 = time.time()
+    finally:
+        s.close()
+
+    t2 = _ntp_to_unix(data, 32)  # server receive timestamp
+    t3 = _ntp_to_unix(data, 40)  # server transmit timestamp
+
+    offset = ((t2 - t1) + (t3 - t4)) / 2
+    delay = (t4 - t1) - (t3 - t2)
+
+    return {
+        "utc": datetime.fromtimestamp(t3, tz=timezone.utc).isoformat(),
+        "offset_ms": round(offset * 1000, 3),
+        "delay_ms": round(delay * 1000, 3),
+        "stratum": data[1],
+        "server": server,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Drift log: one JSON sample per line, appended on every get_time call.
+# ---------------------------------------------------------------------------
+
+def log_sample(sample):
+    """Append one sample to the drift log, keeping the file bounded."""
+    os.makedirs(os.path.dirname(DRIFT_LOG), exist_ok=True)
+    with open(DRIFT_LOG, "a") as f:
+        f.write(json.dumps(sample) + "\n")
+    _trim_log()
+
+
+def _trim_log():
+    """If the log exceeds DRIFT_LOG_MAX lines, keep the most recent half."""
+    try:
+        with open(DRIFT_LOG) as f:
+            lines = f.readlines()
+        if len(lines) > DRIFT_LOG_MAX:
+            with open(DRIFT_LOG, "w") as f:
+                f.writelines(lines[DRIFT_LOG_MAX // 2:])
+    except OSError:
+        pass
+
+
+def read_samples(server=None):
+    """Read the drift log, optionally filtered to one server."""
+    samples = []
+    try:
+        with open(DRIFT_LOG) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    s = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if server and s.get("server") != server:
+                    continue
+                if "ts" in s and "offset_ms" in s:
+                    samples.append(s)
+    except OSError:
+        pass
+    return samples
+
+
+def _slope(points):
+    """Least-squares slope of (x, y) points. Returns y-units per x-unit."""
+    n = len(points)
+    if n < 2:
+        return 0.0
+    mx = sum(p[0] for p in points) / n
+    my = sum(p[1] for p in points) / n
+    denom = sum((p[0] - mx) ** 2 for p in points)
+    if denom == 0:
+        return 0.0
+    return sum((p[0] - mx) * (p[1] - my) for p in points) / denom
+
+
+def analyze_drift(server=None):
+    """Trend analysis over the drift log.
+
+    Fits offset vs. time for the whole log and for each half separately.
+    Whole-log slope gives the drift rate; comparing the halves reveals
+    acceleration -- a clock gaining time faster now than before.
+    """
+    samples = read_samples(server)
+    if len(samples) < 2:
+        return {
+            "samples": len(samples),
+            "verdict": "insufficient data",
+            "hint": "call get_time a few times over minutes or hours, "
+                    "then ask again",
+        }
+
+    ts = [s["ts"] for s in samples]
+    offsets = [s["offset_ms"] for s in samples]
+    n = len(samples)
+    span_s = ts[-1] - ts[0]
+
+    # Whole-log drift rate: ms of offset gained per day.
+    slope_ms_per_s = _slope(list(zip(ts, offsets)))
+    rate_ms_per_day = slope_ms_per_s * 86400
+
+    # Split-half comparison for acceleration.
+    half = n // 2
+    rate_first = _slope(list(zip(ts[:half], offsets[:half]))) * 86400
+    rate_second = _slope(list(zip(ts[half:], offsets[half:]))) * 86400
+
+    mean = sum(offsets) / n
+    variance = sum((o - mean) ** 2 for o in offsets) / n
+    stddev = variance ** 0.5
+
+    # Heuristic classification. <5 ms/day is within typical NTP-disciplined
+    # jitter; beyond that the clock is genuinely drifting. "Accelerating"
+    # means the recent rate is at least double the earlier rate and the
+    # recent rate itself is significant. A span under a minute is too short
+    # for any slope to be meaningful -- network jitter dominates.
+    if span_s < 60:
+        verdict = "insufficient timespan"
+    elif abs(rate_ms_per_day) < 5 and stddev < 10:
+        verdict = "stable"
+    elif abs(rate_second) > 2 * abs(rate_first) and abs(rate_second) > 5:
+        verdict = "accelerating"
+    else:
+        verdict = "drifting"
+
+    return {
+        "samples": n,
+        "span_hours": round(span_s / 3600, 2),
+        "current_offset_ms": offsets[-1],
+        "mean_offset_ms": round(mean, 3),
+        "stddev_ms": round(stddev, 3),
+        "drift_rate_ms_per_day": round(rate_ms_per_day, 3),
+        "rate_first_half_ms_per_day": round(rate_first, 3),
+        "rate_second_half_ms_per_day": round(rate_second, 3),
+        "verdict": verdict,
+        "log": DRIFT_LOG,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool dispatch + JSON-RPC plumbing (unchanged from the atomic-clock version)
+# ---------------------------------------------------------------------------
+
+def call_tool(name, arguments):
+    arguments = arguments or {}
+    if name == "get_time":
+        try:
+            data = query_time(arguments.get("server", "time.cloudflare.com"))
+        except Exception as e:
+            return {"content": [{"type": "text",
+                                 "text": f"NTP query failed: {e}"}],
+                    "isError": True}
+        sample = dict(data)
+        sample["ts"] = time.time()
+        try:
+            log_sample(sample)
+        except OSError:
+            pass  # logging is best-effort; never fail the tool over it
+        return {"content": [{"type": "text", "text": json.dumps(data)}]}
+    if name == "get_drift":
+        return {"content": [{"type": "text",
+                             "text": json.dumps(analyze_drift(
+                                 arguments.get("server")))}]}
+    return {"content": [{"type": "text", "text": f"Unknown tool: {name}"}],
+            "isError": True}
+
+
+def _write(message):
+    """Write one JSON-RPC message as a single line, then FLUSH.
+
+    The flush is not optional. As a subprocess, stdout is block-buffered --
+    without flush() responses sit in the buffer and the host thinks the
+    server is dead.
+    """
+    sys.stdout.write(json.dumps(message) + "\n")
+    sys.stdout.flush()
+
+
+def respond(msg_id, result):
+    _write({"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+
+def respond_error(msg_id, code, message):
+    _write({"jsonrpc": "2.0", "id": msg_id,
+            "error": {"code": code, "message": message}})
+
+
+def handle(req):
+    """Dispatch one parsed JSON-RPC message."""
+    method = req.get("method")
+    msg_id = req.get("id")  # None -> notification -> never respond
+
+    if method == "initialize":
+        respond(msg_id, {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "stamp", "version": "0.3.0"},
+        })
+    elif method == "notifications/initialized":
+        pass  # notification: handshake confirmation, no response allowed
+    elif method == "ping":
+        respond(msg_id, {})
+    elif method == "tools/list":
+        respond(msg_id, {"tools": TOOLS})
+    elif method == "tools/call":
+        params = req.get("params") or {}
+        respond(msg_id, call_tool(params.get("name"), params.get("arguments")))
+    else:
+        if msg_id is not None:  # unknown notification: ignore silently
+            respond_error(msg_id, -32601, f"Method not found: {method}")
+
+
+def main():
+    # stdout is the protocol channel -- log to stderr only.
+    print("stamp: listening on stdin", file=sys.stderr, flush=True)
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            respond_error(None, -32700, "Parse error")
+            continue
+        handle(req)
+
+
+if __name__ == "__main__":
+    main()

stamp_mcp-0.3.0/stamp_mcp.egg-info/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: stamp-mcp
+Version: 0.3.0
+Summary: MCP server for NTP time and clock drift: each query is logged, so drift trends (stable vs. accelerating) are visible. Zero dependencies, raw JSON-RPC over stdio.
+Author: theoddden
+License: MIT
+Project-URL: Repository, https://github.com/theoddden/stamp-mcp
+Keywords: mcp,model-context-protocol,ntp,time,clock-drift,drift
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# stamp-mcp
+
+<!-- mcp-name: io.github.theoddden/stamp -->
+
+An MCP server for NTP time and clock drift. Zero dependencies, fully
+synchronous, raw JSON-RPC 2.0 over stdio -- no MCP library, no asyncio.
+
+A single NTP query tells you where your clock is right now. Drift history
+tells you where it is going: a clock that is consistently 200ms fast and
+accelerating is a different problem than one that is stable at 200ms fast.
+`get_time` takes the measurement; every call appends to a local log;
+`get_drift` reads the log and reports the trend.
+
+## Install
+
+```bash
+pip install stamp-mcp
+```
+
+## Use with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "stamp-mcp"
+    }
+  }
+}
+```
+
+Or run the module directly:
+
+```json
+{
+  "mcpServers": {
+    "stamp": {
+      "command": "python3",
+      "args": ["-m", "stamp_mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+- **`get_time`** -- one NTP query: UTC time, this clock's offset in ms,
+  network delay, stratum. Appends the sample to the drift log. Optional
+  argument: `server` (default `time.cloudflare.com`).
+- **`get_drift`** -- analyzes the drift log: sample count, timespan,
+  current/mean/stddev offset, drift rate in ms/day (least-squares fit),
+  first-half vs. second-half rates, and a verdict: `stable`, `drifting`,
+  or `accelerating`. Optional argument: `server` to filter samples.
+
+## The drift log
+
+Every `get_time` call appends one JSON line to `~/.stamp/drift.jsonl`
+(override with `STAMP_DRIFT_LOG`). The file is capped at 10,000 samples.
+Call `get_time` periodically -- a cron job, a heartbeat, or just asking
+Claude "check the clock" now and then -- and `get_drift` turns the
+accumulated offsets into a trend.
+
+## How it works
+
+The whole server is `stamp_mcp/server.py`:
+
+- **JSON-RPC 2.0 over stdio** -- `initialize`, `tools/list`, `tools/call`,
+  `ping`, notifications, and the standard error codes (`-32700`, `-32601`).
+- **Raw NTP with real offset math** -- a 48-byte NTPv3 packet over UDP 123
+  carrying our transmit timestamp; the response's receive (t2) and
+  transmit (t3) timestamps are unpacked with `struct.unpack("!II", ...)`
+  as 64-bit fixed point, and offset/delay follow RFC 5905:
+  `offset = ((t2-t1)+(t3-t4))/2`, `delay = (t4-t1)-(t3-t2)`.
+- **Two rules that matter**: stdout is the protocol channel (log to stderr
+  only), and `flush()` after every write (subprocess stdout is
+  block-buffered).
+
+## Development
+
+`client.py` is a test harness that plays the role of an MCP host -- it
+spawns the server and performs the real handshake, printing every raw
+frame:
+
+```bash
+python3 client.py                          # tests server.py (stage 1)
+python3 client.py server_atomic.py         # tests the standalone artifact
+python3 client.py stamp_mcp/server.py      # tests the package
+```
+
+`server.py` and `server_atomic.py` are the from-scratch learning artifacts;
+`stamp_mcp/` is the packaged, published server.
+
+## Publishing
+
+The GitHub Action in `.github/workflows/publish-mcp.yml` runs on version
+tags (`git tag v0.3.0 && git push origin v0.3.0`) and does two things:
+
+1. **Publishes the package to PyPI** -- requires a `PYPI_API_TOKEN`
+   repository secret (or configure Trusted Publishing on PyPI and remove
+   the `password` line).
+2. **Publishes metadata to the MCP Registry** -- uses `mcp-publisher` with
+   GitHub OIDC (`id-token: write`), no secret needed. The server name
+   `io.github.theoddden/stamp` is bound to the GitHub account; the
+   `mcp-name` HTML comment at the top of this README is the PyPI ownership
+   verification marker.
+
+---
+
+# Appendix: how this was built, stage by stage
+
+Build an MCP server with no library, one concept at a time. By the end you
+will have written every line yourself and the official MCP SDK becomes a
+convenience you could discard.
+
+## Stage 1 -- raw JSON-RPC over stdio (DONE, verified)
+
+- `server.py` -- the entire protocol in ~100 lines: `sys.stdin` -> `json` ->
+  dispatch -> `sys.stdout` -> `flush()`.
+- `client.py` -- plays the role of Claude Desktop. Spawns the server and
+  performs the real handshake, printing every raw frame.
+
+Run it:
+
+```bash
+python3 client.py
+```
+
+Things to notice in the output:
+
+- `initialize` returns `protocolVersion`, `capabilities`, `serverInfo`.
+- `notifications/initialized` has **no `id`** and gets **no response**.
+- `tools/list` returns the manifest; `inputSchema` is plain JSON Schema.
+- `tools/call` results are `{"content": [{"type": "text", ...}]}`.
+- Unknown **method** -> JSON-RPC error `-32601`.
+- Unknown **tool** -> a normal result with `isError: true` (so the model can
+  read the failure and recover).
+- Malformed JSON -> `-32700`.
+
+Two rules that will bite you if ignored:
+
+1. **stdout is the protocol channel.** One stray `print()` corrupts the
+   stream. Log to stderr only.
+2. **flush() after every write.** As a subprocess, stdout is block-buffered;
+   without flush the host thinks the server is dead.
+
+## Stage 2 -- asyncio
+
+Rewrite the stdin loop as an async coroutine:
+
+- `async def main()` + `asyncio.run(main())`
+- Read stdin without blocking the loop:
+  `loop.run_in_executor(None, sys.stdin.readline)` or
+  `asyncio.StreamReader` hooked to stdin via `loop.connect_read_pipe`.
+- `await` each handler.
+
+The payoff comes in stage 4 -- for now it is the same server with a
+different engine.
+
+## Stage 3 -- real NTP
+
+Replace the stub `get_time` with a real query.
+
+- First pass: `pip install ntplib`, then
+  `ntplib.NTPClient().request('pool.ntp.org', version=3)`.
+- Second pass (optional, illuminating): delete ntplib and write the UDP
+  query yourself. NTPv3 packet = 48 bytes, first byte `0x1B` (LI=0, VN=3,
+  Mode=3), rest zeros. Send to port 123, read 48 bytes back, unpack the
+  transmit timestamp (bytes 40-43, seconds since 1900) with
+  `struct.unpack('!I', ...)`. Subtract 2208988800 to get Unix time.
+  ntplib is ~200 lines of exactly this -- read its source once.
+
+## Stage 4 -- blocking vs. the event loop
+
+The lesson you learn by breaking it:
+
+1. Call `ntplib` **directly** inside your `async def` handler.
+2. While a slow NTP server is being queried, send a `ping` from the client.
+   Watch it hang -- the single-threaded event loop is frozen.
+3. Fix it: `await loop.run_in_executor(None, blocking_ntp_call)`.
+   Blocking work goes to the thread pool; async work gets awaited.
+
+Rule of thumb: `ntplib`, `requests`, file I/O = blocking. `aiohttp`,
+`httpx` (async mode), `asyncpg` = not blocking.
+
+## Connecting to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ntp-scratch": {
+      "command": "/usr/bin/python3",
+      "args": ["/Users/theowolfenden/CascadeProjects/mcp-from-scratch/server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then ask it "what tools do you have?" -- `get_time`
+should appear. If it doesn't, check the logs at
+`~/Library/Logs/Claude/mcp*.log` -- a stray print or missing flush is the
+usual culprit.
+
+## The wire protocol, in one glance
+
+```
+>>> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
+<<< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
+>>> {"jsonrpc":"2.0","method":"notifications/initialized"}     (no reply)
+>>> {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+<<< {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
+>>> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_time","arguments":{}}}
+<<< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}
+```
+
+That is the whole thing. Everything else is plumbing.

stamp_mcp-0.3.0/stamp_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+stamp_mcp/__init__.py
+stamp_mcp/__main__.py
+stamp_mcp/server.py
+stamp_mcp.egg-info/PKG-INFO
+stamp_mcp.egg-info/SOURCES.txt
+stamp_mcp.egg-info/dependency_links.txt
+stamp_mcp.egg-info/entry_points.txt
+stamp_mcp.egg-info/top_level.txt

stamp_mcp-0.3.0/stamp_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stamp_mcp-0.3.0/stamp_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stamp-mcp = stamp_mcp.server:main

stamp_mcp-0.3.0/stamp_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+stamp_mcp