sello 0.1.3 → 0.1.4

package/README.md

@@ -15,6 +15,33 @@ agent calls service
   -> owner fetches, verifies, decrypts
 ```
 
+## Try It
+
+Requires Node.js 22.7 or newer.
+
+From a new project or temporary folder:
+
+```bash
+# Terminal 1
+npx --yes sello dev
+
+# Terminal 2
+npx --yes sello emit-demo
+npx --yes sello actions
+```
+
+Then open:
+
+```text
+http://localhost:8787/actions
+```
+
+To see the tiny wrapped-tool source:
+
+```bash
+npx --yes sello init-demo
+```
+
 ## Why Sello?
 
 Most agent logs are written by the same system whose behavior they describe. If the agent, runtime, or operator is compromised, those logs can be incomplete or false.
@@ -48,14 +75,13 @@ The implementation includes a local end-to-end demo, compact JWS token verificat
 
 ## Start Here
 
-Sello currently requires Node.js 22.7 or newer.
-
 | Goal | Read |
 |------|------|
 | Add Sello in a few lines | [SDK Quickstart](docs/sdk-quickstart.md) |
-| Emit your first receipt | `npx sello dev`, then `npx sello emit-demo` |
+| Emit your first receipt | `npx --yes sello dev`, then `npx --yes sello emit-demo` |
 | Try a wrapped tool locally | `node --run dev`, then `node --run example:tool` |
 | Try an MCP-style tool call | `node --run dev`, then `node --run example:mcp` |
+| See a minimal MCP integration | [examples/mcp-minimal-server.ts](examples/mcp-minimal-server.ts) |
 | Understand the protocol | [SPEC.md](SPEC.md) Quick Start |
 | Run the local demo | `node --run demo` |
 | Run the test suite | `node --run test` |
@@ -82,6 +108,14 @@ Then inspect verified actions:
 npx sello actions --token <agent-token>
 ```
 
+In local dev, `sello dev` prints and saves a demo token:
+
+```bash
+SELLO_ACTION_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
+```
+
+You usually do not need to copy it. `npx sello actions` reads the latest dev token from `.sello/dev.json`. Use `--token` when you want to inspect receipts for a specific agent authorization token from your own system.
+
 Sello works with your own log server. `sello.build` is optional convenience, not a protocol requirement.
 
 To try the repo's local loop:
@@ -99,22 +133,7 @@ The example wraps a fake calendar tool, emits a service-signed encrypted receipt
 
 For an MCP-shaped `tools/call` boundary, run `node --run example:mcp` instead of `node --run example:tool`.
 
-To try the published package from a fresh project:
-
-```bash
-# Terminal 1
-npx sello dev
-
-# Terminal 2
-npx sello emit-demo
-npx sello actions
-```
-
-To see the tiny emitter code:
-
-```bash
-npx sello init-demo
-```
+For a smaller production-shaped MCP example, see [examples/mcp-minimal-server.ts](examples/mcp-minimal-server.ts). It wraps one `tools/call` handler with `sello.service()` and leaves unknown tools unreceipted.
 
 ## The First 10 Minutes
 
@@ -198,18 +217,10 @@ Much of this prior work surfaced after Sello's design had already converged on s
 - Use verifiable log integrated time for revocation decisions, not the receipt timestamp.
 - Deduplicate only on the full spec key, including action type and input/output hashes.
 
-## License
-
-Apache 2.0. See [LICENSE](LICENSE).
-
 ## Feedback
 
 Issues and pull requests are welcome. This is an early draft; adversarial review is the point.
 
-## Development
-
-The current dependency-free test command is:
+## License
 
-```bash
-node --run test
-```
+Apache 2.0. See [LICENSE](LICENSE).

package/docs/sdk-quickstart.md

@@ -22,17 +22,17 @@ From a new project, the shortest loop is:
 
 ```bash
 # Terminal 1
-npx sello dev
+npx --yes sello dev
 
 # Terminal 2
-npx sello emit-demo
-npx sello actions
+npx --yes sello emit-demo
+npx --yes sello actions
 ```
 
 To write the tiny emitter file into your project:
 
 ```bash
-npx sello init-demo
+npx --yes sello init-demo
 ```
 
 Inside this repo, start the local log and action viewer:
@@ -63,6 +63,8 @@ http://localhost:8787/actions
 
 Both examples read `.sello/dev.json`, wrap a fake calendar handler, submit one encrypted receipt, and let the owner verify it locally.
 
+For the smallest production-shaped MCP boundary, see [`examples/mcp-minimal-server.ts`](../examples/mcp-minimal-server.ts). It wraps one `tools/call` handler with `sello.service()` and leaves unknown tools unreceipted.
+
 For your own tool server, copy the printed service env:
 
 ```bash
@@ -80,6 +82,14 @@ Call your wrapped tool with the printed dev token. Then view actions:
 npx sello actions
 ```
 
+In local dev, `sello dev` prints and saves the token:
+
+```bash
+SELLO_ACTION_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
+```
+
+`npx sello actions` reads that token from `.sello/dev.json`. Pass `--token` only when you want to inspect receipts for a specific agent authorization token.
+
 ## Self-Hosted Production
 
 Use your own Sello-compatible log server:

package/examples/mcp-minimal-server.ts

@@ -0,0 +1,95 @@
+import {
+  canonicalJsonBytes,
+  sello,
+  type SelloReceipts,
+} from "../src/index.ts";
+
+export type MinimalMcpRequest = {
+  headers: {
+    authorization?: string;
+    Authorization?: string;
+  };
+  body: {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    method: "tools/call";
+    params: {
+      name: string;
+      arguments: Record<string, unknown>;
+    };
+  };
+};
+
+export type MinimalMcpResponse = {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: {
+    content: { type: "text"; text: string }[];
+  };
+  error?: {
+    code: number;
+    message: string;
+  };
+};
+
+export function createCalendarMcpServer(
+  receipts: SelloReceipts = sello.service(),
+) {
+  const createEvent = receipts.tool<MinimalMcpRequest, MinimalMcpResponse>(
+    "mcp.tools/call.calendar.create_event",
+    async (request) => {
+      const args = request.body.params.arguments;
+      const title = readString(args.title, "title");
+
+      return {
+        jsonrpc: "2.0",
+        id: request.body.id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: `created ${title}`,
+            },
+          ],
+        },
+      };
+    },
+    {
+      canonicalizeInput: (request) => canonicalJsonBytes({
+        method: request.body.method,
+        params: request.body.params,
+      }),
+      canonicalizeOutput: (response) => canonicalJsonBytes(response),
+    },
+  );
+
+  return {
+    async handle(request: MinimalMcpRequest): Promise<MinimalMcpResponse> {
+      if (
+        request.body.method !== "tools/call" ||
+        request.body.params.name !== "calendar.create_event"
+      ) {
+        return {
+          jsonrpc: "2.0",
+          id: request.body.id,
+          error: {
+            code: -32601,
+            message: "tool not found",
+          },
+        };
+      }
+
+      return await createEvent(request);
+    },
+
+    flush: () => receipts.flush(),
+  };
+}
+
+function readString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+
+  return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -31,6 +31,7 @@
     "bench": "node --experimental-strip-types src/cli/bench.ts",
     "demo": "node --experimental-strip-types src/cli/demo.ts",
     "dev": "node --experimental-strip-types src/cli/sello.ts dev",
+    "example:mcp:minimal": "node --test --experimental-strip-types test/examples/mcp-minimal-server.test.ts",
     "example:mcp": "node --experimental-strip-types examples/mcp-tool-server.ts",
     "example:tool": "node --experimental-strip-types examples/quickstart-tool.ts",
     "build": "node --disable-warning=ExperimentalWarning scripts/build-dist.mjs",