wiki-viewer 1.14.1 → 2.0.0

package/.next/standalone/packages/wiki-viewer-mcp/README.md

@@ -1,195 +0,0 @@
-# wiki-viewer-mcp
-
-MCP filesystem adapter for [wiki-viewer](https://github.com/anh-chu/wiki-viewer).
-
-Maps standard MCP filesystem tools onto the wiki-viewer agent HTTP API so Claude Code, Cursor, and Codex get native-feeling file tools against a **remote** wiki-viewer instance.
-
-## First-time setup (register)
-
-Before connecting an agent, register it with your wiki-viewer instance.
-The human operator approves the request in the wiki-viewer AI Panel.
-
-**Using the built-in CLI (recommended):**
-
-```bash
-# Once published to npm:
-npx wiki-viewer-mcp register \
-  --url https://notes.example.com \
-  --id ai:myagent \
-  --name "My Agent" \
-  --scope-paths "**/*" \
-  --ops read,mutate,delete \
-  --timeout 300
-
-# Or from a local build (after cd packages/wiki-viewer-mcp && npm run build):
-node ./dist/index.js register \
-  --url http://localhost:3000 \
-  --id ai:myagent \
-  --name "My Agent"
-```
-
-The CLI will:
-
-1. POST the registration to wiki-viewer and print the registration ID.
-2. Print `⏳ Waiting for approval. Open the wiki-viewer AI Panel and approve agent "ai:myagent".`
-3. Poll every 3 s until the human approves (or timeout).
-4. On approval, print your `WIKI_VIEWER_TOKEN` and `WIKI_VIEWER_AGENT_ID`, then print a ready-to-paste `mcp.json` snippet.
-
-```
-✅ Approved!
-
-Agent ID : ai:myagent
-Token    : wv_tok_…
-
-Paste this into your mcp.json:
-
-{
-  "servers": {
-    "wiki-viewer": {
-      "command": "npx",
-      "args": ["wiki-viewer-mcp"],
-      "env": {
-        "WIKI_VIEWER_URL": "https://notes.example.com",
-        "WIKI_VIEWER_TOKEN": "wv_tok_…",
-        "WIKI_VIEWER_AGENT_ID": "ai:myagent"
-      }
-    }
-  }
-}
-```
-
-**CLI options:**
-
-| Flag            | Required | Default       | Description                                               |
-| --------------- | -------- | ------------- | --------------------------------------------------------- |
-| `--url`         | yes      | —             | Base URL of wiki-viewer, e.g. `https://notes.example.com` |
-| `--id`          | yes      | —             | Agent ID, must match `ai:[a-z][a-z0-9-]{0,30}`            |
-| `--name`        | yes      | —             | Human-readable display name                               |
-| `--scope-paths` | no       | `**/*`        | Comma-separated path globs the agent can access           |
-| `--ops`         | no       | `read,mutate` | Comma-separated: `read`, `mutate`, `delete`               |
-| `--timeout`     | no       | `300`         | Seconds to wait for approval before giving up             |
-
----
-
-## Installation
-
-```bash
-# Once published to npm:
-npx wiki-viewer-mcp
-# or install globally
-npm i -g wiki-viewer-mcp
-
-# From a local build:
-cd packages/wiki-viewer-mcp
-npm run build
-node dist/index.js   # start MCP server
-```
-
-## Configuration
-
-Set three environment variables before starting the MCP server
-(the `register` command prints them for you after approval):
-
-| Var                     | Description                                                                                                                                                                                       |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `WIKI_VIEWER_URL`       | Base URL of your wiki-viewer instance, e.g. `https://notes.example.com`                                                                                                                           |
-| `WIKI_VIEWER_TOKEN`     | Bearer token obtained via `wiki-viewer-mcp register`                                                                                                                                              |
-| `WIKI_VIEWER_AGENT_ID`  | Your agent ID (e.g. `ai:myagent`), sent as `X-Agent-Id` on every request                                                                                                                          |
-| `WIKI_VIEWER_WORKSPACE` | _Optional._ Workspace id, sent as `X-Workspace` on every request. Targets one root directory when the instance serves several. Omit for single-workspace instances (the server uses its default). |
-
-## Usage in Claude Code / Cursor / Codex
-
-Add to your `mcp.json` (or equivalent):
-
-```json
-{
-  "servers": {
-    "wiki-viewer": {
-      "command": "npx",
-      "args": ["wiki-viewer-mcp"],
-      "env": {
-        "WIKI_VIEWER_URL": "https://notes.example.com",
-        "WIKI_VIEWER_TOKEN": "<your-token>",
-        "WIKI_VIEWER_AGENT_ID": "<your-agent-id>"
-      }
-    }
-  }
-}
-```
-
-## Available tools
-
-| Tool             | Maps to                            | Description                                     |
-| ---------------- | ---------------------------------- | ----------------------------------------------- |
-| `read_file`      | `GET /api/agent/fs/file/<path>`    | Read file bytes; captures sha256 + collab state |
-| `write_file`     | `PUT /api/agent/fs/file/<path>`    | Atomic whole-file write with If-Match           |
-| `edit_file`      | read → str-replace → PUT           | Client-side exact-string replacement            |
-| `list_directory` | `GET /api/agent/fs/ls/<path>`      | Scope-filtered directory listing                |
-| `search`         | `POST /api/agent/fs/search`        | Server-side grep or glob                        |
-| `move_file`      | `POST /api/agent/fs/move`          | Rename/move; sidecar handled by server          |
-| `delete_file`    | `DELETE /api/agent/fs/file/<path>` | Delete; requires `delete` scope                 |
-
-## Working mode vs Collaborating mode (important)
-
-wiki-viewer has two tiers for `.md` files:
-
-- **Tier 1 (raw fs)** — fast, all file types, light audit. Use for code, config, non-prose, or whole-file rewrites.
-- **Tier 2 (collab)** — block-ops + proof-spans, review/accept/revert by humans. Use for prose that a human is co-editing.
-
-The shim enforces this automatically in three layers:
-
-### Layer 1 — discoverable (headers)
-
-Every `read_file` response includes:
-
-```
-X-Collab-State: active | tracked | untracked | not-markdown
-X-Collab-Revision: <n>
-X-Collab-Snapshot: /api/agent/files/<path>.md
-```
-
-| State          | Meaning                                                      | You should                             |
-| -------------- | ------------------------------------------------------------ | -------------------------------------- |
-| `active`       | Human has the doc open OR there are pending review artifacts | **Use Tier-2 block-ops**               |
-| `tracked`      | Sidecar exists, no active review                             | Prefer Tier-2 for prose/semantic edits |
-| `untracked`    | Plain `.md`, no collaboration history                        | Raw ok                                 |
-| `not-markdown` | Not a `.md` file                                             | Raw only                               |
-
-### Layer 2 — client-side guard
-
-If the shim's last-known `X-Collab-State` for a `.md` is `active`, `write_file` and `edit_file` are **blocked** before any HTTP request is made. The tool returns a clear error with the Tier-2 snapshot URL.
-
-### Layer 3 — server-side enforcement (409)
-
-Even if the cache is stale, the server re-checks collab state **atomically inside the write mutex**. A raw `PUT` to an `active` `.md` is rejected with `409 COLLAB_ACTIVE` and the Tier-2 snapshot URL. The shim surfaces this as a clear error message.
-
-### Rule
-
-> Before editing a `.md`, run `read_file` and check `X-Collab-State`.  
-> If `active`, use wiki-viewer block-ops (Tier 2).  
-> For everything else, use raw fs tools.
-
-## If-Match concurrency
-
-The shim caches the sha256 from every `read_file` response (ETag header). `write_file`, `edit_file`, and `delete_file` automatically send this as `If-Match`. If the file changed since your read, you get a `412` error with instructions to re-read.
-
-`edit_file` always reads fresh before writing, so it's naturally atomic per-op.
-
-Use `force: true` to bypass `If-Match` (audited by the server).
-
-## Scope
-
-Your token's `scope.paths` (set during registration) governs what paths you can touch. Paths outside scope, and internal paths (`.proof/`, `.locks/`, the app db), are rejected by the server. Scope supports `**`, `*`, `?` glob patterns.
-
-The `delete` op is a separate scope permission from `mutate` — an agent can be granted "edit but never delete."
-
-## Development
-
-```bash
-cd packages/wiki-viewer-mcp
-pnpm install
-pnpm test      # runs unit tests with tsx --test
-pnpm build     # compiles to dist/
-```
-
-Tests use a mock fetch — no real wiki-viewer instance needed.

package/.next/standalone/packages/wiki-viewer-mcp/bench-e2e.mjs

@@ -1,166 +0,0 @@
-/**
- * End-to-end MCP benchmark — measures the FULL stack a remote agent crosses,
- * minus the LLM: MCP stdio JSON-RPC -> shim fetch (keep-alive or not) -> HTTP
- * -> Next standalone server -> route handler -> disk.
- *
- * It spawns the real Next standalone server on a loopback port with an
- * isolated temp ROOT_DIR + temp HOME (seeded agent registry), then drives the
- * REAL wiki-viewer-mcp shim over stdio via the MCP SDK client.
- *
- * Run from repo root:
- *   node packages/wiki-viewer-mcp/bench-e2e.mjs
- * Requires: `npm run build` (root) and shim built (npm --prefix packages/wiki-viewer-mcp run build).
- * Env: BENCH_ITERS (default 50), BENCH_WARMUP (default 10), BENCH_URL (skip spawning, hit a remote instance)
- */
-import { spawn } from "node:child_process";
-import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { createHash, randomBytes } from "node:crypto";
-import { fileURLToPath } from "node:url";
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-
-const ITERS = Number(process.env.BENCH_ITERS) || 50;
-const WARMUP = Number(process.env.BENCH_WARMUP) || 10;
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const REPO = path.resolve(HERE, "../..");
-
-function sha256hex(buf) {
-	return createHash("sha256").update(buf).digest("hex");
-}
-function pct(s, p) { return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; }
-function stats(label, samples) {
-	const s = [...samples].sort((a, b) => a - b);
-	const mean = s.reduce((a, b) => a + b, 0) / s.length;
-	return { label, p50: pct(s, 50), p95: pct(s, 95), p99: pct(s, 99), mean, max: s[s.length - 1] };
-}
-async function timeIt(fn) { const t = performance.now(); await fn(); return performance.now() - t; }
-
-function waitForLog(child, re, timeoutMs = 30000) {
-	return new Promise((resolve, reject) => {
-		const to = setTimeout(() => reject(new Error("server start timeout")), timeoutMs);
-		const onData = (d) => {
-			const s = d.toString();
-			if (re.test(s)) { clearTimeout(to); child.stdout.off("data", onData); child.stderr.off("data", onData); resolve(); }
-		};
-		child.stdout.on("data", onData);
-		child.stderr.on("data", onData);
-	});
-}
-
-async function main() {
-	let serverProc = null;
-	let baseUrl = process.env.BENCH_URL;
-	let tmpHome, tmpRoot;
-	const TOKEN = randomBytes(32).toString("hex");
-	const AGENT_ID = "ai:bench";
-
-	if (!baseUrl) {
-		const PORT = 3917;
-		tmpHome = await mkdtemp(path.join(tmpdir(), "bench-e2e-home-"));
-		tmpRoot = await mkdtemp(path.join(tmpdir(), "bench-e2e-root-"));
-		// Seed registry: ~/.wiki-viewer/agents.json with our agent + hashed token
-		const tokenHash = sha256hex(TOKEN);
-		await mkdir(path.join(tmpHome, ".wiki-viewer"), { recursive: true });
-		const now = new Date().toISOString();
-		await writeFile(
-			path.join(tmpHome, ".wiki-viewer", "agents.json"),
-			JSON.stringify({
-				version: 1,
-				agents: {
-					[AGENT_ID]: {
-						id: AGENT_ID, displayName: "Bench", tokenHash,
-						scope: { paths: ["**/*"], ops: ["read", "mutate", "delete"] },
-						createdAt: now, lastSeen: now,
-					},
-				},
-			}, null, 2),
-			{ mode: 0o600 },
-		);
-		await writeFile(path.join(tmpRoot, "bench.md"), "# Doc\n\n" + "lorem ipsum dolor sit amet. ".repeat(40));
-
-		serverProc = spawn("node", [path.join(REPO, ".next/standalone/server.js")], {
-			env: {
-				...process.env,
-				HOME: tmpHome,
-				ROOT_DIR: tmpRoot,
-				PORT: String(PORT),
-				HOSTNAME: "127.0.0.1",
-				WIKI_ALLOW_INSECURE: "1",
-				NODE_ENV: "production",
-			},
-			stdio: ["ignore", "pipe", "pipe"],
-		});
-		await waitForLog(serverProc, /Ready|started server|Listening|localhost:|127\.0\.0\.1:/i);
-		baseUrl = `http://127.0.0.1:${PORT}`;
-		// settle
-		await new Promise((r) => setTimeout(r, 500));
-	}
-
-	// Drive the REAL shim over stdio
-	const transport = new StdioClientTransport({
-		command: "node",
-		args: [path.join(HERE, "dist/index.js")],
-		env: {
-			...process.env,
-			WIKI_VIEWER_URL: baseUrl,
-			WIKI_VIEWER_TOKEN: TOKEN,
-			WIKI_VIEWER_AGENT_ID: AGENT_ID,
-		},
-	});
-	const client = new Client({ name: "bench", version: "0" }, { capabilities: {} });
-	await client.connect(transport);
-
-	const call = (name, args) => client.callTool({ name, arguments: args });
-
-	const bodyBase = "# Doc\n\n" + "lorem ipsum dolor sit amet. ".repeat(40);
-
-	// Warm + measure read_file
-	const readS = [], writeS = [], editS = [];
-	for (let i = 0; i < WARMUP + ITERS; i++) {
-		const t = await timeIt(async () => { await call("read_file", { path: "bench.md" }); });
-		if (i >= WARMUP) readS.push(t);
-	}
-	// write_file (whole file) — read once to prime sha cache in shim
-	await call("read_file", { path: "bench.md" });
-	for (let i = 0; i < WARMUP + ITERS; i++) {
-		const t = await timeIt(async () => {
-			await call("write_file", { path: "bench.md", content: bodyBase + "\n\nw " + i, force: true });
-		});
-		if (i >= WARMUP) writeS.push(t);
-	}
-	// edit_file (read+replace+write inside one tool call)
-	await call("write_file", { path: "bench.md", content: bodyBase + "\n\nseed", force: true });
-	for (let i = 0; i < WARMUP + ITERS; i++) {
-		const find = i === 0 ? "seed" : "e " + (i - 1);
-		const t = await timeIt(async () => {
-			await call("edit_file", { path: "bench.md", find, replace: "e " + i });
-		});
-		if (i >= WARMUP) editS.push(t);
-	}
-
-	const results = [stats("read_file", readS), stats("write_file (whole-file)", writeS), stats("edit_file (read+write)", editS)];
-	console.log(`\nE2E MCP benchmark — full stack minus LLM  (iters=${ITERS}, warmup=${WARMUP})`);
-	console.log(`target: ${baseUrl}${serverProc ? " (local standalone)" : " (remote)"}\n`);
-	console.log(["tool".padEnd(26), "p50", "p95", "p99", "mean", "max"].join("  "));
-	for (const r of results) {
-		console.log([
-			r.label.padEnd(26),
-			`${r.p50.toFixed(1)}ms`.padStart(8),
-			`${r.p95.toFixed(1)}ms`.padStart(8),
-			`${r.p99.toFixed(1)}ms`.padStart(8),
-			`${r.mean.toFixed(1)}ms`.padStart(8),
-			`${r.max.toFixed(1)}ms`.padStart(8),
-		].join("  "));
-	}
-	console.log("");
-
-	await client.close();
-	if (serverProc) serverProc.kill("SIGTERM");
-	if (tmpHome) await rm(tmpHome, { recursive: true, force: true });
-	if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
-	process.exit(0);
-}
-main().catch((e) => { console.error(e); process.exit(1); });

package/.next/standalone/packages/wiki-viewer-mcp/bench-latency.mjs

@@ -1,87 +0,0 @@
-/**
- * Latency-model benchmark: proves how per-call TCP/TLS handshakes (no keep-alive)
- * vs pooled keep-alive connections behave under WAN-like RTT.
- *
- * It does NOT need the full Next server — it runs a tiny local HTTP server that
- * sleeps RTT/2 before responding (modeling one-way latency), then compares:
- *   A) fetch with a fresh connection each call (no keep-alive)
- *   B) fetch over a pooled keep-alive agent (undici)
- *
- * For each, it models a "write" (1 request) and an "edit" (2 requests: GET+PUT).
- *
- * Run: node packages/wiki-viewer-mcp/bench-latency.mjs [rttMs]
- */
-import http from "node:http";
-import { Agent, fetch as undiciFetch } from "undici";
-
-const RTT = Number(process.argv[2] ?? process.env.RTT_MS ?? 80); // round-trip ms
-const ITERS = Number(process.env.ITERS ?? 30);
-const ONE_WAY = RTT / 2;
-
-function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
-
-// Local server that injects one-way latency on both receive and send.
-const server = http.createServer(async (req, res) => {
-	// drain body
-	for await (const _ of req) { /* consume */ }
-	await sleep(ONE_WAY);           // network: client -> server
-	res.writeHead(200, { "Content-Type": "application/json", ETag: '"sha256:abc"', "X-File-Size": "1024" });
-	res.end(JSON.stringify({ sha256: "sha256:abc", size: 1024 }));
-});
-
-function pct(s, p) { return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; }
-function summarize(label, samples) {
-	const s = [...samples].sort((a, b) => a - b);
-	const mean = s.reduce((a, b) => a + b, 0) / s.length;
-	return `${label.padEnd(40)} p50=${pct(s, 50).toFixed(0)}ms  p95=${pct(s, 95).toFixed(0)}ms  mean=${mean.toFixed(0)}ms`;
-}
-
-async function bench(label, doCall) {
-	const samples = [];
-	for (let i = 0; i < ITERS + 5; i++) {
-		const t = performance.now();
-		await doCall();
-		if (i >= 5) samples.push(performance.now() - t);
-	}
-	return summarize(label, samples);
-}
-
-async function main() {
-	await new Promise((r) => server.listen(0, "127.0.0.1", r));
-	const port = server.address().port;
-	const base = `http://127.0.0.1:${port}/x`;
-
-	// A) No keep-alive: force a fresh connection per request.
-	const noKa = new Agent({ pipelining: 0, connections: 1, keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
-	// B) Pooled keep-alive.
-	const ka = new Agent({ keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000, connections: 10 });
-
-	const req = (dispatcher, method) =>
-		undiciFetch(base, { method, dispatcher, headers: { "content-type": "application/octet-stream" }, body: method === "PUT" ? "x".repeat(1024) : undefined })
-			.then((r) => r.arrayBuffer());
-
-	// Model a COLD connection: TCP(1 RTT) + TLS(≈2 RTT) handshake before the
-	// request even goes out. Real HTTPS over WAN pays this on every call when
-	// the client doesn't reuse connections. We add it explicitly because
-	// loopback can't reproduce handshake cost.
-	const HANDSHAKE_RTTS = Number(process.env.HANDSHAKE_RTTS ?? 3); // TCP+TLS ≈ 3 RTT
-	const freshReq = async (method) => {
-		await sleep(HANDSHAKE_RTTS * RTT); // cold-connection handshake penalty
-		const d = new Agent({ keepAliveTimeout: 1, connections: 1 });
-		await req(d, method);
-		await d.close();
-	};
-
-	console.log(`\nlatency model — RTT=${RTT}ms, iters=${ITERS}\n`);
-	console.log(await bench("write  · fresh conn per call (no keep-alive)", () => freshReq("PUT")));
-	console.log(await bench("write  · pooled keep-alive", () => req(ka, "PUT")));
-	console.log(await bench("edit   · fresh conn per call (GET+PUT)", async () => { await freshReq("GET"); await freshReq("PUT"); }));
-	console.log(await bench("edit   · pooled keep-alive (GET+PUT)", async () => { await req(ka, "GET"); await req(ka, "PUT"); }));
-	console.log("");
-	console.log("Note: 'fresh conn' pays TCP handshake (+~1 RTT) per call; real HTTPS adds TLS (+1-2 RTT).");
-	console.log("");
-
-	await noKa.close(); await ka.close();
-	server.close();
-}
-main().catch((e) => { console.error(e); process.exit(1); });

package/.next/standalone/packages/wiki-viewer-mcp/bench-payload.mjs

@@ -1,45 +0,0 @@
-/**
- * Payload-size model: how much does whole-file PUT cost vs a diff/patch,
- * across realistic .md sizes and uplink speeds? Decides whether a server-side
- * patch endpoint is worth building.
- *
- * Pure arithmetic model (no network needed): upload_time = bytes / uplink_Bps.
- * A small edit changes ~1 line; a patch payload ≈ the changed region + framing.
- *
- * Run: node packages/wiki-viewer-mcp/bench-payload.mjs
- */
-const DOC_SIZES = [
-	{ label: "small note (2 KB)", bytes: 2 * 1024 },
-	{ label: "typical doc (20 KB)", bytes: 20 * 1024 },
-	{ label: "long doc (100 KB)", bytes: 100 * 1024 },
-	{ label: "big doc (500 KB)", bytes: 500 * 1024 },
-];
-// Uplink speeds (bytes/sec). Home/office uplinks are often the bottleneck.
-const UPLINKS = [
-	{ label: "fast (10 MB/s)", bps: 10 * 1024 * 1024 },
-	{ label: "typical home up (2 Mbps = 0.25 MB/s)", bps: 0.25 * 1024 * 1024 },
-	{ label: "slow / shared (0.5 Mbps)", bps: 0.0625 * 1024 * 1024 },
-];
-const PATCH_PAYLOAD = 300; // bytes: a one-line str-replace patch + JSON framing
-
-function ms(bytes, bps) { return (bytes / bps) * 1000; }
-
-console.log("\nupload-time model — whole-file PUT vs ~300B patch (transfer only)\n");
-for (const up of UPLINKS) {
-	console.log(`uplink: ${up.label}`);
-	console.log("  " + ["doc".padEnd(22), "whole-file", "patch", "speedup"].join("  "));
-	for (const d of DOC_SIZES) {
-		const whole = ms(d.bytes, up.bps);
-		const patch = ms(PATCH_PAYLOAD, up.bps);
-		const speedup = whole / patch;
-		console.log("  " + [
-			d.label.padEnd(22),
-			`${whole.toFixed(0)}ms`.padStart(10),
-			`${patch.toFixed(1)}ms`.padStart(7),
-			`${speedup.toFixed(0)}x`.padStart(7),
-		].join("  "));
-	}
-	console.log("");
-}
-console.log("Note: this is transfer time only; add RTT + handshake (now pooled) on top.");
-console.log("Whole-file PUT also re-sends unchanged bytes every edit; patch sends only the change.\n");