George Lambert
30b5df6757
Add docs/cutover.md (shadow :8001, embedded NATS :4223, REQUIRE_BEARER host-token default, cutover/rollback; no JetStream for job-complete). Expand README Usage with env table and pkg/tsnats snippet; add examples/tsnats-bulk.
107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# verae-mcp-timestamping-server-go
|
|
|
|
[](https://github.com/RichardLitt/standard-readme)
|
|
|
|
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). Cutover steps: [`docs/cutover.md`](docs/cutover.md).
|
|
|
|
## Table of Contents
|
|
|
|
- [Install](#install)
|
|
- [Usage](#usage)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Install
|
|
|
|
```sh
|
|
cd verae-mcp-timestamping-server-go
|
|
go build -o bin/verae-mcp-timestamping-server ./cmd/verae-mcp-timestamping-server
|
|
```
|
|
|
|
Requires Go 1.26+. Design: `docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md`. Shadow systemd unit (not installed by this build): `deploy/verae-mcp-timestamping-go.service`.
|
|
|
|
## Usage
|
|
|
|
Shadow beside Python (`:8000` stays live):
|
|
|
|
```sh
|
|
VERAE_MCP_TRANSPORT=streamable-http \
|
|
VERAE_MCP_HOST=127.0.0.1 \
|
|
VERAE_MCP_PORT=8001 \
|
|
VERAE_NATS_LISTEN=127.0.0.1:4223 \
|
|
VERAE_MCP_REQUIRE_BEARER=0 \
|
|
./bin/verae-mcp-timestamping-server
|
|
```
|
|
|
|
Point MCP clients at `http://127.0.0.1:8001/mcp`. For stdio: `-transport stdio` or `VERAE_MCP_TRANSPORT=stdio`.
|
|
|
|
| Variable | Default | Notes |
|
|
| --- | --- | --- |
|
|
| `VERAE_MCP_TRANSPORT` | `streamable-http` | or `stdio` |
|
|
| `VERAE_MCP_HOST` | `127.0.0.1` | HTTP bind |
|
|
| `VERAE_MCP_PORT` | `8000` | shadow examples use `8001` |
|
|
| `VERAE_NATS_LISTEN` | `127.0.0.1:4223` | embedded NATS; set empty to disable |
|
|
| `VERAE_MCP_REQUIRE_BEARER` | `0` | `0` = host-token keeper when no caller bearer; `1` = require caller bearer |
|
|
| `VERAE_GLOBAL_URL` | `https://api.veraetime.net` | |
|
|
| `VERAE_AUTH_PROPERTIES` | `$HOME/.verae/auth.properties` | |
|
|
| `VERAE_GLOBAL_TOKEN` | empty | optional static host bearer |
|
|
| `VERAE_LEDGER_PATH` | `$HOME/.verae/mcp-timestamp-local.json` | |
|
|
| `VERAE_MCP_CORS` | off | set `1` for browser CORS |
|
|
|
|
Global stamps use VeraeTime with auth from `auth.properties` (or caller Bearer). Embedded NATS serves `verae.ts.*`; job-complete is core `verae.ts.completed` only.
|
|
|
|
Parity smoke when Python `:8000` and Go `:8001` are both up:
|
|
|
|
```sh
|
|
./scripts/parity_smoke.sh
|
|
```
|
|
|
|
### pkg/tsnats
|
|
|
|
Bulk workers talk to the embedded (or any) NATS URL. Digests only; `SubscribeCompleted` is core NATS, not JetStream.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
"os"
|
|
|
|
"git.georgelambert.org/marchon/verae-mcp-timestamping-server-go/pkg/tsnats"
|
|
)
|
|
|
|
func main() {
|
|
url := os.Getenv("NATS_URL")
|
|
if url == "" {
|
|
url = "nats://127.0.0.1:4223"
|
|
}
|
|
client, err := tsnats.Connect(url)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
defer client.Close()
|
|
|
|
ctx := context.Background()
|
|
digest := "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
|
|
receipts, err := client.Stamp(ctx, digest, tsnats.StampOptions{Scope: "global"})
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
log.Printf("receipts: %+v", receipts)
|
|
}
|
|
```
|
|
|
|
Runnable sketch: `examples/tsnats-bulk/main.go`.
|
|
|
|
## Contributing
|
|
|
|
Questions: this research workspace / marchon@gmail.com. PRs coordinated in-workspace first. Protocol questions: https://github.com/modelcontextprotocol.
|
|
|
|
## License
|
|
|
|
UNLICENSED © George Lambert
|