docs: HTML and PDF set plus optional CORS
WhatToChange: recommended-changes/2026-09-21-docs-and-cors/ What-to-Change.md What-to-Change-To.md How-to-implement-the-changes.md What was actually done: - Markdown, HTML, and PDF for standards, architecture, API, and the operator guide. - README points at scripts/build-docs.sh. - VERAE_MCP_CORS=1 enables CORS and JSON responses on the Streamable HTTP app. What was not done: - (none)
This commit is contained in:
parent
60bcefbca2
commit
840755c84a
24 changed files with 989 additions and 0 deletions
|
|
@ -50,6 +50,15 @@ Global stamp (central VeraeTime). Token lives at `~/.verae/auth.properties` (mod
|
||||||
|
|
||||||
Do not send file bytes to `stamp`. Local receipts persist at `~/.verae/mcp-timestamp-local.json` (`VERAE_LEDGER_PATH`).
|
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`.
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Questions: this research workspace. PRs welcome. Protocol questions belong at https://github.com/modelcontextprotocol. Timestamp ledger questions belong with `verae-timestamp` / `locald`.
|
Questions: this research workspace. PRs welcome. Protocol questions belong at https://github.com/modelcontextprotocol. Timestamp ledger questions belong with `verae-timestamp` / `locald`.
|
||||||
|
|
|
||||||
63
docs/api.md
Normal file
63
docs/api.md
Normal file
|
|
@ -0,0 +1,63 @@
|
||||||
|
# Tool API
|
||||||
|
|
||||||
|
Server name: `verae-timestamping`.
|
||||||
|
|
||||||
|
## stamp
|
||||||
|
|
||||||
|
| Argument | Default | Meaning |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `sha256` | required | 64 hex characters |
|
||||||
|
| `scope` | `local` | `local`, `shared`, or `global` |
|
||||||
|
| `cube_id` | empty | Stored on the local receipt. Sent only as a local field on the global receipt object; the VeraeTime POST body is the digest |
|
||||||
|
| `org_id` | empty | Local idempotency key. Ignored by the global client |
|
||||||
|
|
||||||
|
Returns `{ "receipts": [ Receipt ] }`.
|
||||||
|
|
||||||
|
Receipt fields: `receipt_id`, `hash`, `scope`, `cube_id`, `org_id`, `created_at`, `merkle`, `restamp_of`.
|
||||||
|
|
||||||
|
## verify
|
||||||
|
|
||||||
|
| Argument | Default | Meaning |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `receipt_id` | required | Local id or VeraeTime certificate / job id |
|
||||||
|
| `want_scope` | empty | `global` forces VeraeTime. A weaker scope fails closed when the stored scope ranks lower |
|
||||||
|
|
||||||
|
Returns `{ "valid": bool, "error": string or null, "receipt": Receipt or null }`.
|
||||||
|
|
||||||
|
Scope rank: local < shared < global.
|
||||||
|
|
||||||
|
## hash_report
|
||||||
|
|
||||||
|
| Argument | Default | Meaning |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `sha256` | required | Digest to list |
|
||||||
|
| `org_id` | empty | Filter when set |
|
||||||
|
| `want_scope` | empty | Drop receipts below this rank |
|
||||||
|
|
||||||
|
Returns `{ "receipts": [ ... ] }` from the local file. Global-only certificates are not listed.
|
||||||
|
|
||||||
|
## Environment
|
||||||
|
|
||||||
|
| Name | Default |
|
||||||
|
| --- | --- |
|
||||||
|
| `VERAE_GLOBAL_URL` | `https://api.veraetime.net` |
|
||||||
|
| `VERAE_GLOBAL_TOKEN` | empty (then auth.properties) |
|
||||||
|
| `VERAE_AUTH_PROPERTIES` | `~/.verae/auth.properties` |
|
||||||
|
| `VERAE_LEDGER_PATH` | `~/.verae/mcp-timestamp-local.json` |
|
||||||
|
| `VERAE_MCP_TRANSPORT` | `stdio` |
|
||||||
|
| `VERAE_MCP_HOST` | `127.0.0.1` |
|
||||||
|
| `VERAE_MCP_PORT` | `8000` |
|
||||||
|
| `VERAE_MCP_CORS` | unset. `1` adds CORS for the sample page |
|
||||||
|
|
||||||
|
## Client config (stdio)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"verae-timestamping": {
|
||||||
|
"command": "uv",
|
||||||
|
"args": ["run", "--directory", "/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server", "verae-mcp-timestamping-server"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
26
docs/architecture.md
Normal file
26
docs/architecture.md
Normal file
|
|
@ -0,0 +1,26 @@
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
## Flow
|
||||||
|
|
||||||
|
1. An MCP client calls `stamp`, `verify`, or `hash_report`.
|
||||||
|
2. `RoutingLedger` sends `scope=global` to `GlobalLedger` and every other scope to `FileLedger`.
|
||||||
|
3. `FileLedger` keeps an idempotent JSON list. The same digest, org, and scope returns the existing receipt.
|
||||||
|
4. `GlobalClient` posts the digest to VeraeTime and, when the body has no certificate yet, polls `/api/status/{jobId}`.
|
||||||
|
5. `verify` with `want_scope=global` posts `{ "certificate": "<id>" }` to `/api/verify`. Otherwise it checks the local file first, then VeraeTime.
|
||||||
|
|
||||||
|
## Modules
|
||||||
|
|
||||||
|
| Module | Role |
|
||||||
|
| --- | --- |
|
||||||
|
| `server.py` | MCP tools and process entry |
|
||||||
|
| `ledger.py` | Receipt model, memory ledger, file ledger, router |
|
||||||
|
| `global_client.py` | VeraeTime HTTPS client; blocking I/O runs in a worker thread |
|
||||||
|
| `nats_ledger.py` | Optional leaf `locald` client |
|
||||||
|
|
||||||
|
## Idempotency
|
||||||
|
|
||||||
|
Local stamps are idempotent per digest + org + scope. Global stamps send `restamp: false` and `wait: true`. VeraeTime may return the same certificate for the same digest. This server does not cache global receipts in the local file.
|
||||||
|
|
||||||
|
## What this process is not
|
||||||
|
|
||||||
|
It does not replace `verae-timestamp` / `locald`. It does not write JetStream. It does not store document bytes. Memory ledger exists for tests and for `mcp dev` when a caller injects it. `main()` always builds `RoutingLedger`.
|
||||||
258
docs/html/api.html
Normal file
258
docs/html/api.html
Normal file
|
|
@ -0,0 +1,258 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="generator" content="pandoc" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||||||
|
<title>api</title>
|
||||||
|
<style>
|
||||||
|
/* Default styles provided by pandoc.
|
||||||
|
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
|
||||||
|
*/
|
||||||
|
code{white-space: pre-wrap;}
|
||||||
|
span.smallcaps{font-variant: small-caps;}
|
||||||
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||||||
|
div.column{flex: auto; overflow-x: auto;}
|
||||||
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||||||
|
/* The extra [class] is a hack that increases specificity enough to
|
||||||
|
override a similar rule in reveal.js */
|
||||||
|
ul.task-list[class]{list-style: none;}
|
||||||
|
ul.task-list li input[type="checkbox"] {
|
||||||
|
font-size: inherit;
|
||||||
|
width: 0.8em;
|
||||||
|
margin: 0 0.8em 0.2em -1.6em;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
||||||
|
/* CSS for syntax highlighting */
|
||||||
|
html { -webkit-text-size-adjust: 100%; }
|
||||||
|
pre > code.sourceCode { white-space: pre; position: relative; }
|
||||||
|
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
||||||
|
pre > code.sourceCode > span:empty { height: 1.2em; }
|
||||||
|
.sourceCode { overflow: visible; }
|
||||||
|
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
||||||
|
div.sourceCode { margin: 1em 0; }
|
||||||
|
pre.sourceCode { margin: 0; }
|
||||||
|
@media screen {
|
||||||
|
div.sourceCode { overflow: auto; }
|
||||||
|
}
|
||||||
|
@media print {
|
||||||
|
pre > code.sourceCode { white-space: pre-wrap; }
|
||||||
|
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
||||||
|
}
|
||||||
|
pre.numberSource code
|
||||||
|
{ counter-reset: source-line 0; }
|
||||||
|
pre.numberSource code > span
|
||||||
|
{ position: relative; left: -4em; counter-increment: source-line; }
|
||||||
|
pre.numberSource code > span > a:first-child::before
|
||||||
|
{ content: counter(source-line);
|
||||||
|
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
||||||
|
border: none; display: inline-block;
|
||||||
|
-webkit-touch-callout: none; -webkit-user-select: none;
|
||||||
|
-khtml-user-select: none; -moz-user-select: none;
|
||||||
|
-ms-user-select: none; user-select: none;
|
||||||
|
padding: 0 4px; width: 4em;
|
||||||
|
color: #aaaaaa;
|
||||||
|
}
|
||||||
|
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
|
||||||
|
div.sourceCode
|
||||||
|
{ }
|
||||||
|
@media screen {
|
||||||
|
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
||||||
|
}
|
||||||
|
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||||||
|
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||||||
|
code span.at { color: #7d9029; } /* Attribute */
|
||||||
|
code span.bn { color: #40a070; } /* BaseN */
|
||||||
|
code span.bu { color: #008000; } /* BuiltIn */
|
||||||
|
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||||||
|
code span.ch { color: #4070a0; } /* Char */
|
||||||
|
code span.cn { color: #880000; } /* Constant */
|
||||||
|
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||||||
|
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||||||
|
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||||||
|
code span.dt { color: #902000; } /* DataType */
|
||||||
|
code span.dv { color: #40a070; } /* DecVal */
|
||||||
|
code span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||||||
|
code span.ex { } /* Extension */
|
||||||
|
code span.fl { color: #40a070; } /* Float */
|
||||||
|
code span.fu { color: #06287e; } /* Function */
|
||||||
|
code span.im { color: #008000; font-weight: bold; } /* Import */
|
||||||
|
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||||||
|
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||||||
|
code span.op { color: #666666; } /* Operator */
|
||||||
|
code span.ot { color: #007020; } /* Other */
|
||||||
|
code span.pp { color: #bc7a00; } /* Preprocessor */
|
||||||
|
code span.sc { color: #4070a0; } /* SpecialChar */
|
||||||
|
code span.ss { color: #bb6688; } /* SpecialString */
|
||||||
|
code span.st { color: #4070a0; } /* String */
|
||||||
|
code span.va { color: #19177c; } /* Variable */
|
||||||
|
code span.vs { color: #4070a0; } /* VerbatimString */
|
||||||
|
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||||||
|
</style>
|
||||||
|
<link rel="stylesheet" href="style.css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<header id="title-block-header">
|
||||||
|
<h1 class="title">api</h1>
|
||||||
|
</header>
|
||||||
|
<h1 id="tool-api">Tool API</h1>
|
||||||
|
<p>Server name: <code>verae-timestamping</code>.</p>
|
||||||
|
<h2 id="stamp">stamp</h2>
|
||||||
|
<table>
|
||||||
|
<colgroup>
|
||||||
|
<col style="width: 33%" />
|
||||||
|
<col style="width: 33%" />
|
||||||
|
<col style="width: 33%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Argument</th>
|
||||||
|
<th>Default</th>
|
||||||
|
<th>Meaning</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>sha256</code></td>
|
||||||
|
<td>required</td>
|
||||||
|
<td>64 hex characters</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>scope</code></td>
|
||||||
|
<td><code>local</code></td>
|
||||||
|
<td><code>local</code>, <code>shared</code>, or <code>global</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>cube_id</code></td>
|
||||||
|
<td>empty</td>
|
||||||
|
<td>Stored on the local receipt. Sent only as a local field on the
|
||||||
|
global receipt object; the VeraeTime POST body is the digest</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>org_id</code></td>
|
||||||
|
<td>empty</td>
|
||||||
|
<td>Local idempotency key. Ignored by the global client</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<p>Returns <code>{ "receipts": [ Receipt ] }</code>.</p>
|
||||||
|
<p>Receipt fields: <code>receipt_id</code>, <code>hash</code>,
|
||||||
|
<code>scope</code>, <code>cube_id</code>, <code>org_id</code>,
|
||||||
|
<code>created_at</code>, <code>merkle</code>,
|
||||||
|
<code>restamp_of</code>.</p>
|
||||||
|
<h2 id="verify">verify</h2>
|
||||||
|
<table>
|
||||||
|
<colgroup>
|
||||||
|
<col style="width: 33%" />
|
||||||
|
<col style="width: 33%" />
|
||||||
|
<col style="width: 33%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Argument</th>
|
||||||
|
<th>Default</th>
|
||||||
|
<th>Meaning</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>receipt_id</code></td>
|
||||||
|
<td>required</td>
|
||||||
|
<td>Local id or VeraeTime certificate / job id</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>want_scope</code></td>
|
||||||
|
<td>empty</td>
|
||||||
|
<td><code>global</code> forces VeraeTime. A weaker scope fails closed
|
||||||
|
when the stored scope ranks lower</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<p>Returns
|
||||||
|
<code>{ "valid": bool, "error": string or null, "receipt": Receipt or null }</code>.</p>
|
||||||
|
<p>Scope rank: local < shared < global.</p>
|
||||||
|
<h2 id="hash_report">hash_report</h2>
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Argument</th>
|
||||||
|
<th>Default</th>
|
||||||
|
<th>Meaning</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>sha256</code></td>
|
||||||
|
<td>required</td>
|
||||||
|
<td>Digest to list</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>org_id</code></td>
|
||||||
|
<td>empty</td>
|
||||||
|
<td>Filter when set</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>want_scope</code></td>
|
||||||
|
<td>empty</td>
|
||||||
|
<td>Drop receipts below this rank</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<p>Returns <code>{ "receipts": [ ... ] }</code> from the local file.
|
||||||
|
Global-only certificates are not listed.</p>
|
||||||
|
<h2 id="environment">Environment</h2>
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Name</th>
|
||||||
|
<th>Default</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_GLOBAL_URL</code></td>
|
||||||
|
<td><code>https://api.veraetime.net</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_GLOBAL_TOKEN</code></td>
|
||||||
|
<td>empty (then auth.properties)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_AUTH_PROPERTIES</code></td>
|
||||||
|
<td><code>~/.verae/auth.properties</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_LEDGER_PATH</code></td>
|
||||||
|
<td><code>~/.verae/mcp-timestamp-local.json</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_MCP_TRANSPORT</code></td>
|
||||||
|
<td><code>stdio</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_MCP_HOST</code></td>
|
||||||
|
<td><code>127.0.0.1</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_MCP_PORT</code></td>
|
||||||
|
<td><code>8000</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>VERAE_MCP_CORS</code></td>
|
||||||
|
<td>unset. <code>1</code> adds CORS for the sample page</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<h2 id="client-config-stdio">Client config (stdio)</h2>
|
||||||
|
<div class="sourceCode" id="cb1"><pre
|
||||||
|
class="sourceCode json"><code class="sourceCode json"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
|
||||||
|
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"mcpServers"</span><span class="fu">:</span> <span class="fu">{</span></span>
|
||||||
|
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"verae-timestamping"</span><span class="fu">:</span> <span class="fu">{</span></span>
|
||||||
|
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"command"</span><span class="fu">:</span> <span class="st">"uv"</span><span class="fu">,</span></span>
|
||||||
|
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"args"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"run"</span><span class="ot">,</span> <span class="st">"--directory"</span><span class="ot">,</span> <span class="st">"/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server"</span><span class="ot">,</span> <span class="st">"verae-mcp-timestamping-server"</span><span class="ot">]</span></span>
|
||||||
|
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
|
||||||
|
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
|
||||||
|
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
95
docs/html/architecture.html
Normal file
95
docs/html/architecture.html
Normal file
|
|
@ -0,0 +1,95 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="generator" content="pandoc" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||||||
|
<title>architecture</title>
|
||||||
|
<style>
|
||||||
|
/* Default styles provided by pandoc.
|
||||||
|
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
|
||||||
|
*/
|
||||||
|
code{white-space: pre-wrap;}
|
||||||
|
span.smallcaps{font-variant: small-caps;}
|
||||||
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||||||
|
div.column{flex: auto; overflow-x: auto;}
|
||||||
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||||||
|
/* The extra [class] is a hack that increases specificity enough to
|
||||||
|
override a similar rule in reveal.js */
|
||||||
|
ul.task-list[class]{list-style: none;}
|
||||||
|
ul.task-list li input[type="checkbox"] {
|
||||||
|
font-size: inherit;
|
||||||
|
width: 0.8em;
|
||||||
|
margin: 0 0.8em 0.2em -1.6em;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
||||||
|
</style>
|
||||||
|
<link rel="stylesheet" href="style.css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<header id="title-block-header">
|
||||||
|
<h1 class="title">architecture</h1>
|
||||||
|
</header>
|
||||||
|
<h1 id="architecture">Architecture</h1>
|
||||||
|
<h2 id="flow">Flow</h2>
|
||||||
|
<ol type="1">
|
||||||
|
<li>An MCP client calls <code>stamp</code>, <code>verify</code>, or
|
||||||
|
<code>hash_report</code>.</li>
|
||||||
|
<li><code>RoutingLedger</code> sends <code>scope=global</code> to
|
||||||
|
<code>GlobalLedger</code> and every other scope to
|
||||||
|
<code>FileLedger</code>.</li>
|
||||||
|
<li><code>FileLedger</code> keeps an idempotent JSON list. The same
|
||||||
|
digest, org, and scope returns the existing receipt.</li>
|
||||||
|
<li><code>GlobalClient</code> posts the digest to VeraeTime and, when
|
||||||
|
the body has no certificate yet, polls
|
||||||
|
<code>/api/status/{jobId}</code>.</li>
|
||||||
|
<li><code>verify</code> with <code>want_scope=global</code> posts
|
||||||
|
<code>{ "certificate": "<id>" }</code> to
|
||||||
|
<code>/api/verify</code>. Otherwise it checks the local file first, then
|
||||||
|
VeraeTime.</li>
|
||||||
|
</ol>
|
||||||
|
<h2 id="modules">Modules</h2>
|
||||||
|
<table>
|
||||||
|
<colgroup>
|
||||||
|
<col style="width: 50%" />
|
||||||
|
<col style="width: 50%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Module</th>
|
||||||
|
<th>Role</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>server.py</code></td>
|
||||||
|
<td>MCP tools and process entry</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>ledger.py</code></td>
|
||||||
|
<td>Receipt model, memory ledger, file ledger, router</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>global_client.py</code></td>
|
||||||
|
<td>VeraeTime HTTPS client; blocking I/O runs in a worker thread</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>nats_ledger.py</code></td>
|
||||||
|
<td>Optional leaf <code>locald</code> client</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<h2 id="idempotency">Idempotency</h2>
|
||||||
|
<p>Local stamps are idempotent per digest + org + scope. Global stamps
|
||||||
|
send <code>restamp: false</code> and <code>wait: true</code>. VeraeTime
|
||||||
|
may return the same certificate for the same digest. This server does
|
||||||
|
not cache global receipts in the local file.</p>
|
||||||
|
<h2 id="what-this-process-is-not">What this process is not</h2>
|
||||||
|
<p>It does not replace <code>verae-timestamp</code> /
|
||||||
|
<code>locald</code>. It does not write JetStream. It does not store
|
||||||
|
document bytes. Memory ledger exists for tests and for
|
||||||
|
<code>mcp dev</code> when a caller injects it. <code>main()</code>
|
||||||
|
always builds <code>RoutingLedger</code>.</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
19
docs/html/index.html
Normal file
19
docs/html/index.html
Normal file
|
|
@ -0,0 +1,19 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<title>Verae MCP timestamping server</title>
|
||||||
|
<link rel="stylesheet" href="style.css">
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>Verae MCP timestamping server</h1>
|
||||||
|
<p>Hash-only stamps for assistants that speak the Model Context Protocol.</p>
|
||||||
|
<ul>
|
||||||
|
<li><a href="operator-guide.html">Operator guide</a> (<a href="../pdf/operator-guide.pdf">PDF</a>)</li>
|
||||||
|
<li><a href="architecture.html">Architecture</a> (<a href="../pdf/architecture.pdf">PDF</a>)</li>
|
||||||
|
<li><a href="api.html">Tool API</a> (<a href="../pdf/api.pdf">PDF</a>)</li>
|
||||||
|
<li><a href="standards.html">Standards</a> (<a href="../pdf/standards.pdf">PDF</a>)</li>
|
||||||
|
<li><a href="../../site/index.html">Sample page</a></li>
|
||||||
|
</ul>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
128
docs/html/operator-guide.html
Normal file
128
docs/html/operator-guide.html
Normal file
|
|
@ -0,0 +1,128 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="generator" content="pandoc" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||||||
|
<title>operator-guide</title>
|
||||||
|
<style>
|
||||||
|
/* Default styles provided by pandoc.
|
||||||
|
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
|
||||||
|
*/
|
||||||
|
code{white-space: pre-wrap;}
|
||||||
|
span.smallcaps{font-variant: small-caps;}
|
||||||
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||||||
|
div.column{flex: auto; overflow-x: auto;}
|
||||||
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||||||
|
/* The extra [class] is a hack that increases specificity enough to
|
||||||
|
override a similar rule in reveal.js */
|
||||||
|
ul.task-list[class]{list-style: none;}
|
||||||
|
ul.task-list li input[type="checkbox"] {
|
||||||
|
font-size: inherit;
|
||||||
|
width: 0.8em;
|
||||||
|
margin: 0 0.8em 0.2em -1.6em;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
||||||
|
/* CSS for syntax highlighting */
|
||||||
|
html { -webkit-text-size-adjust: 100%; }
|
||||||
|
pre > code.sourceCode { white-space: pre; position: relative; }
|
||||||
|
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
||||||
|
pre > code.sourceCode > span:empty { height: 1.2em; }
|
||||||
|
.sourceCode { overflow: visible; }
|
||||||
|
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
||||||
|
div.sourceCode { margin: 1em 0; }
|
||||||
|
pre.sourceCode { margin: 0; }
|
||||||
|
@media screen {
|
||||||
|
div.sourceCode { overflow: auto; }
|
||||||
|
}
|
||||||
|
@media print {
|
||||||
|
pre > code.sourceCode { white-space: pre-wrap; }
|
||||||
|
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
||||||
|
}
|
||||||
|
pre.numberSource code
|
||||||
|
{ counter-reset: source-line 0; }
|
||||||
|
pre.numberSource code > span
|
||||||
|
{ position: relative; left: -4em; counter-increment: source-line; }
|
||||||
|
pre.numberSource code > span > a:first-child::before
|
||||||
|
{ content: counter(source-line);
|
||||||
|
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
||||||
|
border: none; display: inline-block;
|
||||||
|
-webkit-touch-callout: none; -webkit-user-select: none;
|
||||||
|
-khtml-user-select: none; -moz-user-select: none;
|
||||||
|
-ms-user-select: none; user-select: none;
|
||||||
|
padding: 0 4px; width: 4em;
|
||||||
|
color: #aaaaaa;
|
||||||
|
}
|
||||||
|
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
|
||||||
|
div.sourceCode
|
||||||
|
{ }
|
||||||
|
@media screen {
|
||||||
|
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
||||||
|
}
|
||||||
|
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||||||
|
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||||||
|
code span.at { color: #7d9029; } /* Attribute */
|
||||||
|
code span.bn { color: #40a070; } /* BaseN */
|
||||||
|
code span.bu { color: #008000; } /* BuiltIn */
|
||||||
|
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||||||
|
code span.ch { color: #4070a0; } /* Char */
|
||||||
|
code span.cn { color: #880000; } /* Constant */
|
||||||
|
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||||||
|
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||||||
|
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||||||
|
code span.dt { color: #902000; } /* DataType */
|
||||||
|
code span.dv { color: #40a070; } /* DecVal */
|
||||||
|
code span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||||||
|
code span.ex { } /* Extension */
|
||||||
|
code span.fl { color: #40a070; } /* Float */
|
||||||
|
code span.fu { color: #06287e; } /* Function */
|
||||||
|
code span.im { color: #008000; font-weight: bold; } /* Import */
|
||||||
|
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||||||
|
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||||||
|
code span.op { color: #666666; } /* Operator */
|
||||||
|
code span.ot { color: #007020; } /* Other */
|
||||||
|
code span.pp { color: #bc7a00; } /* Preprocessor */
|
||||||
|
code span.sc { color: #4070a0; } /* SpecialChar */
|
||||||
|
code span.ss { color: #bb6688; } /* SpecialString */
|
||||||
|
code span.st { color: #4070a0; } /* String */
|
||||||
|
code span.va { color: #19177c; } /* Variable */
|
||||||
|
code span.vs { color: #4070a0; } /* VerbatimString */
|
||||||
|
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||||||
|
</style>
|
||||||
|
<link rel="stylesheet" href="style.css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<header id="title-block-header">
|
||||||
|
<h1 class="title">operator-guide</h1>
|
||||||
|
</header>
|
||||||
|
<h1 id="operator-guide">Operator guide</h1>
|
||||||
|
<h2 id="install">Install</h2>
|
||||||
|
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server</span>
|
||||||
|
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> sync <span class="at">--group</span> dev</span></code></pre></div>
|
||||||
|
<h2 id="run-stdio">Run stdio</h2>
|
||||||
|
<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
|
||||||
|
<h2 id="run-streamable-http">Run Streamable HTTP</h2>
|
||||||
|
<div class="sourceCode" id="cb3"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
|
||||||
|
<p>The listener is <code>http://127.0.0.1:8000/mcp</code>.</p>
|
||||||
|
<p>For the sample page on another origin:</p>
|
||||||
|
<div class="sourceCode" id="cb4"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_CORS</span><span class="op">=</span>1 <span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
|
||||||
|
<p>A page served from the public internet still cannot call
|
||||||
|
<code>127.0.0.1</code> from current browsers. Open
|
||||||
|
<code>site/index.html</code> on the same machine, or put TLS and an
|
||||||
|
access control in front of a non-loopback bind you choose yourself.</p>
|
||||||
|
<h2 id="global-token">Global token</h2>
|
||||||
|
<div class="sourceCode" id="cb5"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co"># POST https://api.veraetime.net/auth/login and store access_token=</span></span>
|
||||||
|
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co"># in ~/.verae/auth.properties (mode 600), or:</span></span>
|
||||||
|
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="bu">export</span> <span class="va">VERAE_GLOBAL_TOKEN</span><span class="op">=</span>...</span></code></pre></div>
|
||||||
|
<h2 id="tests">Tests</h2>
|
||||||
|
<div class="sourceCode" id="cb6"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run pytest</span></code></pre></div>
|
||||||
|
<p>Stamp traces (live VeraeTime) are a separate script. They write
|
||||||
|
<code>debug-trace/<YYYY-MM-DDTHHMMSSZ>-<slug>/</code>:</p>
|
||||||
|
<div class="sourceCode" id="cb7"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run python scripts/transaction_log_test.py</span></code></pre></div>
|
||||||
|
<h2 id="build-these-documents">Build these documents</h2>
|
||||||
|
<div class="sourceCode" id="cb8"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> scripts/build-docs.sh</span></code></pre></div>
|
||||||
|
<p>HTML lands in <code>docs/html/</code>. PDF lands in
|
||||||
|
<code>docs/pdf/</code>.</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
141
docs/html/standards.html
Normal file
141
docs/html/standards.html
Normal file
|
|
@ -0,0 +1,141 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="generator" content="pandoc" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||||||
|
<title>standards</title>
|
||||||
|
<style>
|
||||||
|
/* Default styles provided by pandoc.
|
||||||
|
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
|
||||||
|
*/
|
||||||
|
code{white-space: pre-wrap;}
|
||||||
|
span.smallcaps{font-variant: small-caps;}
|
||||||
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||||||
|
div.column{flex: auto; overflow-x: auto;}
|
||||||
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||||||
|
/* The extra [class] is a hack that increases specificity enough to
|
||||||
|
override a similar rule in reveal.js */
|
||||||
|
ul.task-list[class]{list-style: none;}
|
||||||
|
ul.task-list li input[type="checkbox"] {
|
||||||
|
font-size: inherit;
|
||||||
|
width: 0.8em;
|
||||||
|
margin: 0 0.8em 0.2em -1.6em;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
||||||
|
</style>
|
||||||
|
<link rel="stylesheet" href="style.css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<header id="title-block-header">
|
||||||
|
<h1 class="title">standards</h1>
|
||||||
|
</header>
|
||||||
|
<h1 id="standards">Standards</h1>
|
||||||
|
<p>Rules for the Verae MCP timestamping server.</p>
|
||||||
|
<h2 id="protocol">Protocol</h2>
|
||||||
|
<p>This process is an MCP server (Model Context Protocol). Clients are
|
||||||
|
assistants and inspectors that speak MCP. It is not a REST product API
|
||||||
|
and not a browser session by itself.</p>
|
||||||
|
<h2 id="hash-only">Hash only</h2>
|
||||||
|
<ul>
|
||||||
|
<li>Callers send a SHA-256 digest: 64 lowercase hex characters. A
|
||||||
|
<code>sha256:</code> prefix is stripped.</li>
|
||||||
|
<li>The server does not read files, does not accept document bytes, and
|
||||||
|
does not hash content.</li>
|
||||||
|
<li>Empty input has the well-known digest
|
||||||
|
<code>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</code>.
|
||||||
|
Callers may stamp that digest. The server does not invent it from a
|
||||||
|
missing file.</li>
|
||||||
|
</ul>
|
||||||
|
<h2 id="scopes">Scopes</h2>
|
||||||
|
<table>
|
||||||
|
<colgroup>
|
||||||
|
<col style="width: 50%" />
|
||||||
|
<col style="width: 50%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Scope</th>
|
||||||
|
<th>Where the receipt lives</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><code>local</code></td>
|
||||||
|
<td>JSON file, default
|
||||||
|
<code>~/.verae/mcp-timestamp-local.json</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>shared</code></td>
|
||||||
|
<td>Same file. There is no separate shared store in this process</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>global</code></td>
|
||||||
|
<td><code>POST https://api.veraetime.net/api/timestamp</code> with
|
||||||
|
<code>wait=true</code></td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<p><code>want_scope=global</code> on <code>verify</code> asks VeraeTime.
|
||||||
|
A local receipt cannot satisfy <code>global</code>.</p>
|
||||||
|
<h2 id="global-history">Global history</h2>
|
||||||
|
<p><code>hash_report</code> reads the local file only. VeraeTime is not
|
||||||
|
queried for a digest history. A global stamp can verify by certificate
|
||||||
|
id and still be absent from <code>hash_report</code>. An empty list
|
||||||
|
means “not in the local file,” not “VeraeTime has no record.”</p>
|
||||||
|
<h2 id="credentials">Credentials</h2>
|
||||||
|
<ul>
|
||||||
|
<li>Token: <code>VERAE_GLOBAL_TOKEN</code>, else
|
||||||
|
<code>access_token</code> / <code>id_token</code> /
|
||||||
|
<code>auth_token</code> in <code>~/.verae/auth.properties</code>
|
||||||
|
(<code>VERAE_AUTH_PROPERTIES</code> overrides the path).</li>
|
||||||
|
<li>Do not commit tokens. <code>.env</code> is gitignored.</li>
|
||||||
|
<li>The local receipt file is mode <code>0600</code> after each
|
||||||
|
save.</li>
|
||||||
|
</ul>
|
||||||
|
<h2 id="nats">NATS</h2>
|
||||||
|
<p><code>NatsLedger</code> is optional and is not the default. It uses
|
||||||
|
core NATS request/reply:</p>
|
||||||
|
<ul>
|
||||||
|
<li><code>verae.ts.request</code></li>
|
||||||
|
<li><code>verae.ts.verify</code></li>
|
||||||
|
<li><code>verae.hash.report</code></li>
|
||||||
|
</ul>
|
||||||
|
<p>Job-complete and receipt notifications stay ephemeral core NATS
|
||||||
|
(<code>verae.ts.completed</code>, <code>verae.ts.receipt</code>). This
|
||||||
|
server does not put those events on JetStream.</p>
|
||||||
|
<h2 id="transports">Transports</h2>
|
||||||
|
<table>
|
||||||
|
<colgroup>
|
||||||
|
<col style="width: 50%" />
|
||||||
|
<col style="width: 50%" />
|
||||||
|
</colgroup>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th><code>VERAE_MCP_TRANSPORT</code></th>
|
||||||
|
<th>Bind</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>unset or <code>stdio</code></td>
|
||||||
|
<td>Parent process stdin/stdout</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>streamable-http</code></td>
|
||||||
|
<td><code>VERAE_MCP_HOST</code> (default <code>127.0.0.1</code>) and
|
||||||
|
<code>VERAE_MCP_PORT</code> (default <code>8000</code>), path
|
||||||
|
<code>/mcp</code></td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<p>Leave the HTTP bind on loopback unless a reverse proxy terminates TLS
|
||||||
|
and authentication in front of it. Do not publish the VeraeTime bearer
|
||||||
|
token on an open internet listener.</p>
|
||||||
|
<h2 id="errors">Errors</h2>
|
||||||
|
<p>Invalid digests and unknown scopes raise <code>ToolError</code> with
|
||||||
|
the <code>ValueError</code> text. HTTP failures from VeraeTime surface
|
||||||
|
as <code>global timestamp HTTP <status></code>.</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
1
docs/html/style.css
Normal file
1
docs/html/style.css
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
body{font-family:Georgia,serif;max-width:42rem;margin:2rem auto;padding:0 1rem;line-height:1.45}code,pre{font-family:ui-monospace,monospace}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:0.3rem 0.5rem}
|
||||||
58
docs/operator-guide.md
Normal file
58
docs/operator-guide.md
Normal file
|
|
@ -0,0 +1,58 @@
|
||||||
|
# Operator guide
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cd /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server
|
||||||
|
uv sync --group dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Run stdio
|
||||||
|
|
||||||
|
```sh
|
||||||
|
uv run verae-mcp-timestamping-server
|
||||||
|
```
|
||||||
|
|
||||||
|
## Run Streamable HTTP
|
||||||
|
|
||||||
|
```sh
|
||||||
|
VERAE_MCP_TRANSPORT=streamable-http uv run verae-mcp-timestamping-server
|
||||||
|
```
|
||||||
|
|
||||||
|
The listener is `http://127.0.0.1:8000/mcp`.
|
||||||
|
|
||||||
|
For the sample page on another origin:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
VERAE_MCP_CORS=1 VERAE_MCP_TRANSPORT=streamable-http uv run verae-mcp-timestamping-server
|
||||||
|
```
|
||||||
|
|
||||||
|
A page served from the public internet still cannot call `127.0.0.1` from current browsers. Open `site/index.html` on the same machine, or put TLS and an access control in front of a non-loopback bind you choose yourself.
|
||||||
|
|
||||||
|
## Global token
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# POST https://api.veraetime.net/auth/login and store access_token=
|
||||||
|
# in ~/.verae/auth.properties (mode 600), or:
|
||||||
|
export VERAE_GLOBAL_TOKEN=...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
```sh
|
||||||
|
uv run pytest
|
||||||
|
```
|
||||||
|
|
||||||
|
Stamp traces (live VeraeTime) are a separate script. They write `debug-trace/<YYYY-MM-DDTHHMMSSZ>-<slug>/`:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
uv run python scripts/transaction_log_test.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build these documents
|
||||||
|
|
||||||
|
```sh
|
||||||
|
bash scripts/build-docs.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
HTML lands in `docs/html/`. PDF lands in `docs/pdf/`.
|
||||||
BIN
docs/pdf/api.pdf
Normal file
BIN
docs/pdf/api.pdf
Normal file
Binary file not shown.
BIN
docs/pdf/architecture.pdf
Normal file
BIN
docs/pdf/architecture.pdf
Normal file
Binary file not shown.
BIN
docs/pdf/operator-guide.pdf
Normal file
BIN
docs/pdf/operator-guide.pdf
Normal file
Binary file not shown.
BIN
docs/pdf/standards.pdf
Normal file
BIN
docs/pdf/standards.pdf
Normal file
Binary file not shown.
56
docs/standards.md
Normal file
56
docs/standards.md
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
# Standards
|
||||||
|
|
||||||
|
Rules for the Verae MCP timestamping server.
|
||||||
|
|
||||||
|
## Protocol
|
||||||
|
|
||||||
|
This process is an MCP server (Model Context Protocol). Clients are assistants and inspectors that speak MCP. It is not a REST product API and not a browser session by itself.
|
||||||
|
|
||||||
|
## Hash only
|
||||||
|
|
||||||
|
- Callers send a SHA-256 digest: 64 lowercase hex characters. A `sha256:` prefix is stripped.
|
||||||
|
- The server does not read files, does not accept document bytes, and does not hash content.
|
||||||
|
- Empty input has the well-known digest `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`. Callers may stamp that digest. The server does not invent it from a missing file.
|
||||||
|
|
||||||
|
## Scopes
|
||||||
|
|
||||||
|
| Scope | Where the receipt lives |
|
||||||
|
| --- | --- |
|
||||||
|
| `local` | JSON file, default `~/.verae/mcp-timestamp-local.json` |
|
||||||
|
| `shared` | Same file. There is no separate shared store in this process |
|
||||||
|
| `global` | `POST https://api.veraetime.net/api/timestamp` with `wait=true` |
|
||||||
|
|
||||||
|
`want_scope=global` on `verify` asks VeraeTime. A local receipt cannot satisfy `global`.
|
||||||
|
|
||||||
|
## Global history
|
||||||
|
|
||||||
|
`hash_report` reads the local file only. VeraeTime is not queried for a digest history. A global stamp can verify by certificate id and still be absent from `hash_report`. An empty list means "not in the local file," not "VeraeTime has no record."
|
||||||
|
|
||||||
|
## Credentials
|
||||||
|
|
||||||
|
- Token: `VERAE_GLOBAL_TOKEN`, else `access_token` / `id_token` / `auth_token` in `~/.verae/auth.properties` (`VERAE_AUTH_PROPERTIES` overrides the path).
|
||||||
|
- Do not commit tokens. `.env` is gitignored.
|
||||||
|
- The local receipt file is mode `0600` after each save.
|
||||||
|
|
||||||
|
## NATS
|
||||||
|
|
||||||
|
`NatsLedger` is optional and is not the default. It uses core NATS request/reply:
|
||||||
|
|
||||||
|
- `verae.ts.request`
|
||||||
|
- `verae.ts.verify`
|
||||||
|
- `verae.hash.report`
|
||||||
|
|
||||||
|
Job-complete and receipt notifications stay ephemeral core NATS (`verae.ts.completed`, `verae.ts.receipt`). This server does not put those events on JetStream.
|
||||||
|
|
||||||
|
## Transports
|
||||||
|
|
||||||
|
| `VERAE_MCP_TRANSPORT` | Bind |
|
||||||
|
| --- | --- |
|
||||||
|
| unset or `stdio` | Parent process stdin/stdout |
|
||||||
|
| `streamable-http` | `VERAE_MCP_HOST` (default `127.0.0.1`) and `VERAE_MCP_PORT` (default `8000`), path `/mcp` |
|
||||||
|
|
||||||
|
Leave the HTTP bind on loopback unless a reverse proxy terminates TLS and authentication in front of it. Do not publish the VeraeTime bearer token on an open internet listener.
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
Invalid digests and unknown scopes raise `ToolError` with the `ValueError` text. HTTP failures from VeraeTime surface as `global timestamp HTTP <status>`.
|
||||||
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Done and not done
|
||||||
|
|
||||||
|
WhatToChange: recommended-changes/2026-09-21-docs-and-cors/
|
||||||
|
|
||||||
|
What was actually done:
|
||||||
|
- Markdown, HTML, and PDF for standards, architecture, API, and the operator guide.
|
||||||
|
- README points at scripts/build-docs.sh.
|
||||||
|
- VERAE_MCP_CORS=1 enables CORS on the Streamable HTTP app.
|
||||||
|
|
||||||
|
What was not done:
|
||||||
|
- (none)
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# How to implement the changes:
|
||||||
|
|
||||||
|
Against the pin in git-versions.md (dirty tree).
|
||||||
|
|
||||||
|
1. Add `docs/standards.md`, `docs/architecture.md`, `docs/api.md`, `docs/operator-guide.md`.
|
||||||
|
2. Add `scripts/build-docs.sh` (pandoc HTML and PDF).
|
||||||
|
3. Link the build from `README.md`.
|
||||||
|
4. When `VERAE_MCP_CORS=1`, run uvicorn on `streamable_http_app()` with `CORSMiddleware`.
|
||||||
25
recommended-changes/2026-09-21-docs-and-cors/README.md
Normal file
25
recommended-changes/2026-09-21-docs-and-cors/README.md
Normal file
|
|
@ -0,0 +1,25 @@
|
||||||
|
# Recommended changes: docs and CORS
|
||||||
|
|
||||||
|
Second review, 2026-09-21. Pins are in git-versions.md.
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cd /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server
|
||||||
|
uv sync --group dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```sh
|
||||||
|
less recommended-changes/2026-09-21-docs-and-cors/What-to-Change.md
|
||||||
|
bash scripts/build-docs.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Questions: this research workspace. PRs welcome.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
UNLICENSED © George Lambert
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
# What to Change To:
|
||||||
|
|
||||||
|
| Component | Target behavior | Acceptance criteria | Constraints |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `docs/*.md` plus HTML and PDF | Operator guide, architecture, tool API, and standards | `bash scripts/build-docs.sh` writes four HTML files and four PDFs, each PDF larger than 10 KB | Facts match the code. Do not document JetStream for job-complete |
|
||||||
|
| `VERAE_MCP_CORS=1` | Starlette CORS allows the sample page to see the session header | Default `mcp.run` path unchanged when the variable is unset | Bind stays `127.0.0.1` unless the operator sets `VERAE_MCP_HOST` |
|
||||||
|
|
@ -0,0 +1,13 @@
|
||||||
|
# What to Change:
|
||||||
|
|
||||||
|
Reviewed after `60bcefb`. Pytest 14 passed. The server behavior from the first pack is in place. Operators still had only a short README.
|
||||||
|
|
||||||
|
## What is working
|
||||||
|
|
||||||
|
- Hash-only tools, file ledger mode 0600, global HTTP off the event loop.
|
||||||
|
- `debug-trace/` remains the live stamp record and stays in git.
|
||||||
|
|
||||||
|
| Component | Problem | Evidence | Severity | Type |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| README only | No architecture, tool reference, or standards a reader can print | `docs/` did not exist before this pack | high | doc drift |
|
||||||
|
| Streamable HTTP | Browser sample on another origin cannot read `mcp-session-id` | `server.py` called `mcp.run` with no CORS middleware | medium | missing gate |
|
||||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue