wiki-viewer 1.4.3 → 1.5.0

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

@@ -0,0 +1,194 @@
+# 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 |
+
+## 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/dist/http-client.js

@@ -0,0 +1,220 @@
+/**
+ * Typed HTTP client over the wiki-viewer agent filesystem API.
+ * Contract: docs/agent-fs-plan.md §2.
+ *
+ * All methods throw WikiViewerError on non-2xx unless noted.
+ * The caller (index.ts) catches 409/412 and surfaces them cleanly to the agent.
+ */
+import * as cache from "./state-cache.js";
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export class WikiViewerError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, code, message, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.name = "WikiViewerError";
+    }
+}
+export class IfMatchError extends WikiViewerError {
+    constructor(path, body) {
+        super(412, "IF_MATCH_MISMATCH", `If-Match mismatch for ${path} — re-read before writing`, body);
+        this.name = "IfMatchError";
+    }
+}
+export class CollabActiveError extends WikiViewerError {
+    snapshotUrl;
+    constructor(path, snapshotUrl, body) {
+        super(409, "COLLAB_ACTIVE", `${path} is being actively collaborated on — use Tier-2 block-ops`, body);
+        this.snapshotUrl = snapshotUrl;
+        this.name = "CollabActiveError";
+    }
+}
+// ─── Client ──────────────────────────────────────────────────────────────────
+export class WikiViewerClient {
+    baseUrl;
+    token;
+    agentId;
+    _fetch;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.token = config.token;
+        this.agentId = config.agentId;
+        this._fetch = config.fetch ?? globalThis.fetch;
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    headers(extra = {}) {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            "X-Agent-Id": this.agentId,
+            ...extra,
+        };
+    }
+    url(path, params) {
+        const u = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                u.searchParams.set(k, v);
+            }
+        }
+        return u.toString();
+    }
+    async assertOk(res, path) {
+        if (res.ok)
+            return;
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = await res.text().catch(() => undefined);
+        }
+        if (res.status === 412)
+            throw new IfMatchError(path, body);
+        if (res.status === 409) {
+            const snapshotUrl = body?.snapshotUrl ?? null;
+            throw new CollabActiveError(path, snapshotUrl, body);
+        }
+        throw new WikiViewerError(res.status, `HTTP_${res.status}`, `wiki-viewer ${res.status} for ${path}: ${res.statusText}`, body);
+    }
+    parseCollabHeaders(res) {
+        const raw = (res.headers.get("X-Collab-State") ?? "not-markdown");
+        const validStates = ["active", "tracked", "untracked", "not-markdown"];
+        const collabState = validStates.includes(raw) ? raw : "not-markdown";
+        const revRaw = res.headers.get("X-Collab-Revision");
+        const collabRevision = revRaw !== null ? parseInt(revRaw, 10) : null;
+        const collabSnapshot = res.headers.get("X-Collab-Snapshot") ?? null;
+        return { collabState, collabRevision, collabSnapshot };
+    }
+    // ── read_file ──────────────────────────────────────────────────────────────
+    async readFile(path, range) {
+        const extraHeaders = {};
+        if (range)
+            extraHeaders["Range"] = range;
+        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`), { headers: this.headers(extraHeaders) });
+        await this.assertOk(res, path);
+        const sha256 = stripQuotes(res.headers.get("ETag") ?? "");
+        const size = parseInt(res.headers.get("X-File-Size") ?? "0", 10);
+        const mtime = res.headers.get("X-File-Mtime") ?? "";
+        const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+        const collab = this.parseCollabHeaders(res);
+        const bodyBuf = new Uint8Array(await res.arrayBuffer());
+        const isText = contentType.startsWith("text/") ||
+            contentType.includes("json") ||
+            contentType.includes("xml") ||
+            contentType.includes("javascript") ||
+            contentType.includes("typescript");
+        const text = isText ? new TextDecoder().decode(bodyBuf) : null;
+        const state = {
+            sha256,
+            collabState: collab.collabState,
+            collabRevision: collab.collabRevision,
+            collabSnapshot: collab.collabSnapshot,
+            fetchedAt: Date.now(),
+        };
+        cache.set(path, state);
+        return { body: bodyBuf, text, sha256, size, mtime, contentType, ...collab };
+    }
+    // ── write_file ─────────────────────────────────────────────────────────────
+    async writeFile(path, content, opts = {}) {
+        const extraHeaders = {};
+        // Auto-fill If-Match from the last-read sha (cache) on overwrite, unless the
+        // caller explicitly supplied one or is forcing. A create (no cached sha) omits it.
+        const ifMatch = opts.ifMatch ?? (opts.force ? undefined : cache.get(path)?.sha256);
+        if (ifMatch)
+            extraHeaders["If-Match"] = ifMatch;
+        if (opts.ifCollabMatch !== undefined) {
+            extraHeaders["If-Collab-Match"] = String(opts.ifCollabMatch);
+        }
+        const params = {};
+        if (opts.mkdirs)
+            params["mkdirs"] = "true";
+        if (opts.force)
+            params["force"] = "true";
+        const body = typeof content === "string"
+            ? new TextEncoder().encode(content)
+            : content;
+        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
+            method: "PUT",
+            headers: this.headers({ "Content-Type": "application/octet-stream", ...extraHeaders }),
+            body,
+        });
+        await this.assertOk(res, path);
+        const result = await res.json();
+        // Update cache after successful write
+        cache.set(path, {
+            sha256: result.sha256,
+            collabState: "not-markdown",
+            collabRevision: null,
+            collabSnapshot: null,
+            fetchedAt: Date.now(),
+        });
+        return result;
+    }
+    // ── delete_file ────────────────────────────────────────────────────────────
+    async deleteFile(path, ifMatch, opts = {}) {
+        const params = {};
+        if (opts.recursive)
+            params["recursive"] = "true";
+        if (opts.force)
+            params["force"] = "true";
+        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
+            method: "DELETE",
+            headers: this.headers({ "If-Match": ifMatch }),
+        });
+        await this.assertOk(res, path);
+        cache.del(path);
+    }
+    // ── list_directory ─────────────────────────────────────────────────────────
+    async listDirectory(path, opts = {}) {
+        const params = {};
+        if (opts.recursive)
+            params["recursive"] = "true";
+        if (opts.depth !== undefined)
+            params["depth"] = String(opts.depth);
+        if (opts.limit !== undefined)
+            params["limit"] = String(opts.limit);
+        const res = await this._fetch(this.url(`/api/agent/fs/ls/${encodeFilePath(path)}`, params), { headers: this.headers() });
+        await this.assertOk(res, path);
+        return res.json();
+    }
+    // ── search ────────────────────────────────────────────────────────────────
+    async search(body) {
+        const res = await this._fetch(this.url("/api/agent/fs/search"), {
+            method: "POST",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        await this.assertOk(res, "search");
+        return res.json();
+    }
+    // ── move_file ─────────────────────────────────────────────────────────────
+    async moveFile(from, to, ifMatch) {
+        const body = { from, to };
+        if (ifMatch)
+            body["ifMatch"] = ifMatch;
+        const res = await this._fetch(this.url("/api/agent/fs/move"), {
+            method: "POST",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        await this.assertOk(res, from);
+        cache.rename(from, to);
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Encode path segments but preserve slashes */
+function encodeFilePath(path) {
+    return path
+        .replace(/^\/+/, "")
+        .split("/")
+        .map((seg) => encodeURIComponent(seg))
+        .join("/");
+}
+function stripQuotes(etag) {
+    return etag.replace(/^"/, "").replace(/"$/, "");
+}
+//# sourceMappingURL=http-client.js.map