# verae-mcp-timestamping-server

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

Verae MCP timestamping server. Hash-only stamps via leaf locald/NATS.

The MCP process never hashes content. Clients send a SHA-256 hex digest. `scope=local` writes `~/.verae/mcp-timestamp-local.json`. `scope=global` POSTs to `https://api.veraetime.net/api/timestamp` (same wire as `verae-timestamp/global.Client`). `want_scope=global` verifies against that API as the central source of truth. `signup` creates a `user` account with no existing session. `login` stores the VeraeTime JWT on this host. `session` checks it. `create_user` adds an account when that JWT is an admin.

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)

## Install

On the machine that will run the server:

```sh
uvx verae-mcp-timestamping-server setup
```

`setup` asks whether this is a new account or an existing one, then writes `~/.verae/auth.properties` (mode 600). It prints the username, role, and expiry. It does not print the token. `uvx verae-mcp-timestamping-server session` prints the same check.

Assistant config names the command or the public URL. It does not contain the token:

```json
{
  "mcpServers": {
    "verae-timestamping": {
      "command": "uvx",
      "args": ["verae-mcp-timestamping-server"]
    }
  }
}
```

For the public server, set `url` to `https://mcp.veraetime.net/mcp`. With `VERAE_MCP_OAUTH=1` and `VERAE_MCP_PUBLIC_URL=https://mcp.veraetime.net`, the first connection opens a browser page to create an account or log in. The assistant stores that token in its own OAuth file.

Development checkout:

```sh
cd /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server
uv sync --group dev
```

## Usage

Inspector (stdio, memory ledger):

```sh
uv run mcp dev src/verae_mcp_timestamping_server/server.py
```

Streamable HTTP (`http://127.0.0.1:8000/mcp`):

```sh
VERAE_MCP_TRANSPORT=streamable-http uv run verae-mcp-timestamping-server
```

Tests:

```sh
uv run pytest
```

HTTP stamp traces (HTML viewer) live under `debug-trace/<YYYY-MM-DDTHHMMSSZ>-<slug>/`:

```sh
uv run python scripts/transaction_log_test.py
open debug-trace/2026-09-20T143541Z-verae-debug-test/transaction-log-test.html
```

Global stamp (central VeraeTime). `login` writes `~/.verae/auth.properties` (mode 600) and does not return the JWT:

```sh
# MCP tools: signup, login, session, create_user
# or: export VERAE_GLOBAL_TOKEN=...
# then stamp with scope=global
```

Do not send file bytes to `stamp`. Local receipts persist at `~/.verae/mcp-timestamp-local.json` (`VERAE_LEDGER_PATH`).

Printed and HTML copies of the operator guide, architecture, tool API, and standards:

```sh
bash scripts/build-docs.sh
open docs/html/index.html
```

Sources: `docs/operator-guide.md`, `docs/architecture.md`, `docs/api.md`, `docs/standards.md`.

Install page and stamp sample:

```sh
open site/index.html
open site/sample.html
```

Public copy of the page and the docs: `https://mcp.georgelambert.org/`.

## Contributing

Questions: this research workspace. PRs welcome. Protocol questions belong at https://github.com/modelcontextprotocol. Timestamp ledger questions belong with `verae-timestamp` / `locald`.

## License

UNLICENSED © George Lambert