George Lambert
c3e0cd3abb
setup registers or logs in and writes ~/.verae/auth.properties without printing the JWT. A caller bearer is used for stamp and verify instead of the host login. VERAE_MCP_OAUTH=1 serves the browser account page. site/index.html is the public install guide.
109 lines
3.3 KiB
Markdown
109 lines
3.3 KiB
Markdown
# verae-mcp-timestamping-server
|
|
|
|
[](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
|