From 7b5ae5b9aa83aabac35173d5270b41cac1f87db5 Mon Sep 17 00:00:00 2001 From: George Lambert Date: Tue, 29 Sep 2026 11:40:47 -0400 Subject: [PATCH] docs: add pkg/tsnats NATS client to Go MCP design MCP remains the AI tool surface. Importable pkg/tsnats covers Stamp, Verify, HashReport over core NATS plus SubscribeCompleted; MCP optional upstream reuses the same package. No JetStream for job-complete. --- README.md | 2 + ...09-29-go-mcp-timestamping-server-design.md | 44 +++++++++++++++---- 2 files changed, 37 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 19e27cd..0d1887e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Go MCP timestamping server for Verae. Digests only; sibling to the Python server Implements the same tools as https://mcp.verae.ai/mcp (`stamp`, `verify`, `hash_report`, auth tools) using the official MCP Go SDK. Designed for shadow deploy beside Python, then cutover. +AI assistants use MCP. Bulk app workers can import `pkg/tsnats` for core NATS request/reply on `verae.ts.*` (job-complete stays ephemeral; no JetStream for those events). + ## Table of Contents - [Install](#install) diff --git a/docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md b/docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md index df82247..6c263b7 100644 --- a/docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md +++ b/docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md @@ -17,6 +17,7 @@ The live Verae MCP timestamping service is a Python process (`verae-mcp-timestam 4. Optional core-NATS bridge (same subjects as Python); **no JetStream for job-complete**. 5. Streamable HTTP + stdio transports; CORS / allowed hosts/origins compatible with ns1. 6. Shadow on ns1 beside Python; documented cutover checklist. +7. Importable **`pkg/tsnats`** NATS client for bulk app workers (MCP stays the AI path). ## Non-goals (this project) @@ -35,16 +36,21 @@ The live Verae MCP timestamping service is a Python process (`verae-mcp-timestam ## Architecture ``` -Clients - │ - ▼ -verae-mcp-timestamping-server-go - ├── local|shared → FileLedger (~/.verae/mcp-timestamp-local.json or VERAE_LEDGER_PATH) - ├── global → api.veraetime.net (/api/timestamp, /api/verify, /api/hash/{sha}, /auth/*) - └── optional NATS → verae.ts.request, verae.ts.verify, verae.hash.report (core NATS only) +AI assistants ──MCP (stdio / Streamable HTTP)──► verae-mcp-timestamping-server-go + ├── FileLedger (local|shared) + ├── VeraeTime HTTPS (global) + └── optional upstream NATS (same pkg/tsnats) + +Bulk apps / bus workers ──pkg/tsnats──► NATS core + request/reply: verae.ts.request | verae.ts.verify | verae.hash.report + notify (subscribe): verae.ts.completed / receipt-style subjects + (no JetStream for job-complete) ``` -**SDK:** official `github.com/modelcontextprotocol/go-sdk/mcp` (`NewStreamableHTTPHandler`, `AddTool`, stdio). +**Split:** MCP tools remain the AI surface. `pkg/tsnats` is the digests-only messaging client for large concurrent stamp batches and async completion. + +**SDK:** official `github.com/modelcontextprotocol/go-sdk/mcp` (`NewStreamableHTTPHandler`, `AddTool`, stdio). +**NATS:** `github.com/nats-io/nats.go` inside `pkg/tsnats` (and reused by `internal/natsbridge`). ## Repository layout @@ -53,11 +59,12 @@ Remote (planned): `ssh://git@git.georgelambert.org:2223/marchon/verae-mcp-timest ``` cmd/verae-mcp-timestamping-server/main.go +pkg/tsnats/ # importable NATS timestamp client (Stamp/Verify/HashReport + Completed) internal/config/ internal/digest/ internal/ledger/ # FileLedger internal/veraetime/ # GlobalClient + auth.properties -internal/natsbridge/ # optional +internal/natsbridge/ # optional MCP upstream; wraps pkg/tsnats internal/tools/ # MCP tool handlers docs/superpowers/specs/ docs/cutover.md # cutover checklist (deliverable) @@ -85,6 +92,24 @@ Digests only: reject content/bytes/file/data/path/body/payload/blob/archive. Normalize SHA-256 (optional `sha256:` prefix; 64 hex). Global stamp: `restamp: false`; poll `/api/status/{jobId}` when needed. +## pkg/tsnats (bulk app client) + +Import path (planned): `git.georgelambert.org/marchon/verae-mcp-timestamping-server-go/pkg/tsnats` + +| API | Behavior | +| --- | --- | +| `Connect(url string, opts ...Option) (*Client, error)` | Core NATS connection | +| `Stamp(ctx, sha256, opts)` | Request/reply on `verae.ts.request`; digests only | +| `Verify(ctx, receiptID, opts)` | `verae.ts.verify` | +| `HashReport(ctx, sha256, opts)` | `verae.hash.report` | +| `SubscribeCompleted(ctx, handler)` | Core subscribe to `verae.ts.completed` (and documented receipt alias if any); **not** JetStream | + +Defaults: request timeout ~2s (configurable); concurrent `Stamp` calls are safe; empty/invalid digests fail client-side before publish. + +The MCP server’s optional NATS upstream (`internal/natsbridge`) **imports this package** so bus encoding stays one implementation. + +Bulk guidance: prefer many in-flight `Stamp` calls (or fire request + `SubscribeCompleted`) over serial MCP `tools/call`. For central global certificates when not on the bus, Application Client / VeraeTime HTTPS remains valid. + ## Config (env) | Variable | Default | @@ -132,6 +157,7 @@ Global stamp: `restamp: false`; poll `/api/status/{jobId}` when needed. - Full tool list matches Python. - Local/shared persist to ledger file; global uses VeraeTime with caller/host token. - Optional NATS path does not use JetStream for job-complete. +- `pkg/tsnats` builds as an importable library with unit tests against a NATS test server or fake conn. - Shadow unit runs on ns1 without disturbing Python `:8000`. - Cutover doc is complete enough to swap without inventing steps on the day.