norn-cli 3.0.0 → 3.1.0

package/NOW.md

@@ -25,30 +25,28 @@
 
 ## Active now
 
-### 🧪 Agent Workbench — Slice 5: AI evals
-The last of the four things nothing else does in one place: let an **AI judge score what a
-contract cannot**, with thresholds useful in CI rather than noisy. An umbrella, not a buildable
-slice — it breaks into six items (authoring, rubric/scoring, judge execution, thresholds,
-reporting, fixtures/docs), specced and built one at a time.
-→ Spec: [`Docs/to-be-built/agent-workbench-slice-5.md`](Docs/to-be-built/agent-workbench-slice-5.md)
-
-**Next step:** **5f — fixtures, docs, positioning**, the last item of slice 5. The feature is
-complete and reported across every surface; what is missing is a demo anyone else can run and an
-explanation of what it is for. 5f has no spec yet.
-
-**5b and 5d are closed.** 5b was made unnecessary by the checklist scoring model. 5d's content
-was decided in conversation — a failed judge stops the sequence, the CLI already exits `1`, and
-per-expectation strictness plus the replay-drift check are future work Peter deferred
-2026-08-10.
-→ 5a spec (built): [`Docs/to-be-built/agent-workbench-slice-5a.md`](Docs/to-be-built/agent-workbench-slice-5a.md)
-→ 5c spec (built): [`Docs/to-be-built/agent-workbench-slice-5c.md`](Docs/to-be-built/agent-workbench-slice-5c.md)
-→ 5e spec (built): [`Docs/to-be-built/agent-workbench-slice-5e.md`](Docs/to-be-built/agent-workbench-slice-5e.md)
+_Nothing accepted right now._ The MCP-servers item finished 2026-08-12 — see **Recently done**.
+Slice 5f is the standing follow-on in the backlog below; it now has a spec and is ready for a
+fresh session the moment Peter accepts it here.
 
 ---
 
 ## Backlog / accepted-but-not-started
 
-_(empty)_
+### 🧪 Agent Workbench — Slice 5f: eval fixtures, docs, positioning
+**Postponed 2026-08-11; the MCP work it was waiting on finished 2026-08-12, and it now has a
+spec.** Slice 5 is otherwise complete and reported across every surface (5a, 5c, 5e built; 5b and
+5d closed). 5f is smaller than its name suggests: the **website already documents `judge` well**,
+and a deterministic judge server already exists as a test fixture — so what is left is promoting
+that fixture to a demo anyone can run with **no API key** (one clearly-good case, one clearly-bad
+one), a README section that catches up with the website, and the explanation of what evals are
+for. **No `src/` change.** The spec leads with the constraint that matters: Norn's positioning is
+locked, so "positioning" here means explaining evals *from* the spine, never a new pitch.
+→ **5f spec: [`Docs/to-be-built/agent-workbench-slice-5f.md`](Docs/to-be-built/agent-workbench-slice-5f.md)**
+→ Slice 5 spec: [`Docs/to-be-built/agent-workbench-slice-5.md`](Docs/to-be-built/agent-workbench-slice-5.md)
+→ Built: [`5a`](Docs/to-be-built/agent-workbench-slice-5a.md) ·
+[`5c`](Docs/to-be-built/agent-workbench-slice-5c.md) ·
+[`5e`](Docs/to-be-built/agent-workbench-slice-5e.md)
 
 ## Parked
 
@@ -60,6 +58,58 @@ narrative and how to resume:
 
 ## Recently done
 
+- **3.1.0 — MCP authoring parity, and the changelog is gone** (2026-08-13) — **done.**
+  Three fixes that all came out of one painful hour authoring a real server by hand. **`header`
+  now reads like HTTP**: `header Name: value` is accepted alongside the original no-colon form,
+  because the colon form is what a `.norn` request writes and what everyone arrives with —
+  rejecting it silently produced a header *named* `Authorization:` and the only complaint came
+  from `Headers.append` at dial time, three layers from the line at fault. The name is now
+  validated against the RFC 9110 token set at parse time, so an unsendable one is red in the
+  editor. The header name and value carry `.norn`'s own `entity.name.tag.http` /
+  `string.unquoted.http` scopes, so the identical header is the identical colour in both files,
+  and the quoted-string pattern is gone from that rule — it advertised an escape that does not
+  exist, and quotes really do end up inside the token. IntelliSense offers the shared
+  `commonHeaders` list after `header `, inserting the colon form and chaining into the
+  `Bearer {{$env.…}}` value completion.
+  **`run mcp` completions now see sidecar-declared servers.** The precedence rule lived in three
+  copies and the completion copy was left on config-only, so a project that declared every server
+  in its sidecar offered no aliases at all while running perfectly. It is now one shared module,
+  `src/mcpAliasScope.ts`, and the alias carries its origin — which matters because the tools cache
+  is written beside whatever *declared* the server, so tool-name completions and signature help
+  were reading the wrong `.norn-cache` even once an alias resolved. **Config `mcp.servers` stays**:
+  supporting both is one function and one line per caller, so retiring it would have been strictly
+  more work than keeping it.
+  **`CHANGELOG.md` deleted** at Peter's call — the release record is git history plus this board,
+  and a changelog was a third place saying the same thing and the likeliest to drift.
+  Also fixed: `@vscode/test-electron` 2.5.2 could not launch VS Code 1.133 (the binary was renamed
+  from `Electron` to `Code`), which had left the Extension Host suite dark.
+- **Agent Workbench — declared MCP servers** (2026-08-12) — **done, all five items.**
+  Agents can now *do* things. A `.nornagent` sidecar declares the servers it uses beside the
+  models it uses — `mcp <Alias> … end mcp`, stdio and http, credentials as `.nornenv`
+  references — and each agent is granted a whole server with `mcp <Alias>` or named tools with
+  `tools <Alias>.<tool>`. The two stay visibly different statements on purpose: a granted tool
+  executes when the model asks, so the authored grant *is* the permission boundary and dropping
+  four characters must not widen it from one tool to twenty. `session run | agent | call` makes
+  shared server state a decision rather than a surprise; `run` stays the default because five
+  agents testing one website are one testing session, and `session agent` is how an agent asks
+  not to inherit a login it never earned. Config `mcp.servers` keeps working with the sidecar
+  winning, `run mcp` steps reach declared servers so a server is provable with no model and no
+  cost, and a granted server is a real node on the canvas — **declared servers only**, per
+  Peter: the graph draws the program the file describes.
+  Four corrections the build forced on the spec, all recorded in it: grant expansion **cannot**
+  live above the runner (pure replay never runs that preflight, and a derived root definition
+  never reaches sub-agents), so it is an injected hook with a live and a replay implementation;
+  drift between record and replay is only knowable where a live listing happens, so the
+  acceptance criterion demanding both was impossible as written; preflight needed a session
+  boundary of its own, or `session agent` was already broken by the check that proves an agent's
+  tools exist; and the spec's own demo sketch used an input expression the language does not
+  have. Fixed along the way: a templated URL resolving differently mid-run silently reused the
+  old session, and a refused connection reported the SDK's "fetch failed" instead of naming what
+  it dialled. 60 focused tests across five items; 256 pass across every runnable suite, plus
+  type-check, lint, bundles, skill validation, and regression at 198/200 (two live-SQL-Server
+  sequences needing a database).
+  → Spec: [`Docs/to-be-built/agent-workbench-mcp-servers.md`](Docs/to-be-built/agent-workbench-mcp-servers.md)
+  · Demo: [`demos/mcp-ticket-testing`](demos/mcp-ticket-testing)
 - **Agent Workbench Slice 5e — reporting** (2026-08-10) — **done.**
   A verdict is now visible in the response panel, the canvas, the debugger, and JUnit, derived
   once through `agentHopPresentation` so the surfaces cannot disagree. The load-bearing move was
@@ -154,4 +204,4 @@ narrative and how to resume:
   and functionality untouched. Was Phase 0 of the marketing plan.
 
 ---
-_Last updated: 2026-08-10_
+_Last updated: 2026-08-12_

package/README.md

@@ -107,7 +107,14 @@ Every `{{...}}` reference in any Norn file shows its resolved value as a gray in
 
 ## Deterministic MCP Tools
 
-Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP sessions are deterministic and shared across the full sequence run, so nested sequences reuse the same connection for the same resolved server alias.
+Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP sessions are deterministic and shared across the full sequence run by default, so nested sequences reuse the same connection for the same resolved server alias.
+
+A server can be declared in two places, and an alias resolves through them in this order:
+
+1. an `mcp <Alias> ... end mcp` block in a `.nornagent` sidecar the file imports — see
+   [Contract-Checked Agent Graphs](#contract-checked-agent-graphs), and prefer this when agents
+   use the server too, because the file then says what it connects to;
+2. `mcp.servers` in the nearest `norn.config.json`.
 
 Create a `norn.config.json` in the root of your project:
 
@@ -150,7 +157,11 @@ Behavior:
 - `run mcp list <alias>` returns the full tool list and drains paginated `nextCursor` responses automatically.
 - `run mcp call <alias> <tool>(...)` supports named arguments or positional arguments bound in tool-schema order, and returns a deterministic result envelope with `content`, `structuredContent`, `isError`, `text`, `server`, and `tool`.
 - Tool `structuredContent` is validated against the MCP tool's advertised `outputSchema` when present.
-- Sessions are closed automatically when the outermost sequence finishes or fails.
+- A run-scoped session is closed automatically when the outermost sequence finishes or fails. A
+  sidecar-declared server can narrow that with `session agent` or `session call`, which close at
+  their own boundary instead.
+- An imported `.norn` helper sequence resolves aliases through **its own** imports, not its
+  caller's — the same rule agent scopes follow.
 
 ## Contract-Checked Agent Graphs
 
@@ -188,6 +199,67 @@ agent TicketRouter
 end agent
 ```
 
+### Giving agents hands: declared MCP servers
+
+An agent reaches the outside world through MCP servers, and those are declared in the same
+file, the same way — every input the server needs written down, credentials as `.nornenv`
+references:
+
+```nornagent
+mcp Browser
+    transport stdio
+    command npx playwright-mcp --headless --isolated
+    session agent            # run (default) | agent | call
+end mcp
+
+mcp House
+    transport http
+    url {{$env.HOUSE_MCP_URL}}                          # the MCP endpoint, path included
+    header Authorization: Bearer {{$env.HOUSE_TOKEN}}
+    timeout 60000
+end mcp
+
+agent FrontendTester
+    model Workbench
+    mcp Browser                                    # every tool this server advertises
+    tools House.getFixtureUser, House.resetTenant  # only these, from this one
+    system file prompts/frontend-tester.md
+end agent
+```
+
+- **`transport stdio` spawns the server per run; `transport http` only dials one.** Norn never
+  starts an http server, so it must already be listening — a refused connection fails before
+  any model spend, naming the URL it tried.
+- **`mcp <Alias>` and `tools <Alias>.<tool>` are deliberately different statements.** A granted
+  tool executes when the model asks for it, so the authored grant *is* the permission boundary:
+  dropping four characters must not silently widen access from one tool to twenty.
+- **`header` writes an HTTP header the way you would write it anywhere else.** `header Name:
+  value`, and the value is the rest of the line taken verbatim — so `Bearer {{token}}` needs no
+  quotes, and quotes you add become part of the token. The colon is optional but recommended:
+  it is what the request side of Norn uses, and IntelliSense inserts it for you.
+- **`session` decides what state is shared.** The default, `run`, gives every agent in a
+  sequence one session — deliberate for an orchestration, and a trap when a backend agent
+  inherits a frontend agent's login and passes a test that should have failed. `session agent`
+  is how an agent asks for its own.
+- An alias with no block still resolves through `norn.config.json` `mcp.servers`, and a block
+  in the sidecar wins over a config entry of the same name.
+
+Deterministic `run mcp` steps resolve the same aliases, so a server can be proved reachable
+with no model and no cost:
+
+```norn
+import "./agents.nornagent"
+
+test sequence ServersUp
+    var tools = run mcp list House
+    assert tools.length > 0
+end sequence
+```
+
+The runnable [`demos/mcp-ticket-testing`](./demos/mcp-ticket-testing) example is the whole
+shape end to end: a browser agent, a backend agent narrowed on the same custom server, a
+reporter, and a `judge` over the expected test cases.
+
 A prompt that outgrows its sidecar can live in its own file instead. `describe`
 and `system` both accept `file <path>`, resolved relative to the `.nornagent`
 file just like an import:

package/demos/agent-workbench/norn.config.json

@@ -4,6 +4,7 @@
     "max_tokens": 16000,
     "max_depth": 5,
     "max_invocations": 25,
+    "max_turns": 100,
     "contract_retries": 2,
     "providers": {
       "local": {

package/demos/mcp-ticket-testing/README.md

@@ -0,0 +1,114 @@
+# Ticket testing with declared MCP servers
+
+An agent graph that **does** something: a ticket arrives, one agent tests the product through a
+browser, another tests it through the team's own API, a third writes the results up, and a
+`judge` rules on whether the expected test cases were actually covered.
+
+Everything it connects to is declared in [`agents.nornagent`](./agents.nornagent), beside the
+model. There is **no `norn.config.json` in this folder** — the servers, their transports, and
+their session lifetimes are all in the file that uses them.
+
+## What to look at
+
+```nornagent
+mcp Browser
+    transport stdio
+    command node ./servers/browser-server.js
+    session agent
+end mcp
+
+agent FrontendTester
+    mcp Browser                                    # the run of the browser
+    tools House.getFixtureUser, House.resetTenant  # only what it needs from ours
+end agent
+
+agent BackendTester
+    tools House.callEndpoint, House.readAuditLog, House.queryDb
+end agent
+```
+
+Three things this shows, and they are the point of the whole slice:
+
+- **Two agents, one custom server, different tools each.** `BackendTester` gets three named
+  tools from `House` and cannot touch the browser at all. The access boundary is visible per
+  agent, in one file, in git.
+- **`mcp Browser` and `tools House.callEndpoint` are visibly different statements.** Dropping
+  four characters must not silently widen access from one tool to twenty, so there is no
+  short form that means "all of it".
+- **`session agent` on the browser.** Each agent invocation gets its own browser, closed when
+  that hop ends. The default, `session run`, shares one browser across every agent in the
+  sequence — right for a continuous flow, and wrong the moment a second agent is granted the
+  same server: it would inherit the first one's login and could pass a test it never
+  authenticated for, which is a false green and worse than a false red. Only `FrontendTester`
+  reaches the browser in this graph, so this is the lifetime worth authoring by default rather
+  than a bleed this demo would actually suffer.
+
+## Run it
+
+The servers are deterministic and ship with the demo, so nothing needs installing or starting.
+Prove they are reachable **without spending anything on a model**:
+
+```bash
+npm run compile
+node ./dist/cli.js demos/mcp-ticket-testing/tickets.norn --sequence ServersUp
+```
+
+That resolves the same aliases the agents use, so a failure points at the server rather than at
+an agent. When you are building a server of your own, this is the loop to develop against.
+
+Then the real thing, which does need a model:
+
+```bash
+export OPENAI_API="your-key"
+node ./dist/cli.js demos/mcp-ticket-testing/tickets.norn --sequence TicketPROJ142
+```
+
+The variable name is not a convention Norn assumes — it is written in the model block as
+`apiKey {{$env.OPENAI_API}}`, so any name works as long as the file and the environment
+agree. A `.nornenv` value wins over the process environment; add `--env <name>` to select one.
+
+## The browser here is a stand-in
+
+[`servers/browser-server.js`](./servers/browser-server.js) is a deterministic scripted site, not
+a real browser, so this demo runs anywhere `node` does — no browser download, no server to keep
+alive. Its declaration is the **same shape** a real Playwright MCP block takes, and both real
+forms are written out in the comments at the top of
+[`agents.nornagent`](./agents.nornagent):
+
+```nornagent
+mcp Browser
+    transport stdio
+    command npx playwright-mcp --headless --isolated
+    session agent
+end mcp
+```
+
+For CI with more than one sequence, run Playwright MCP as a service and dial it instead — that
+is what `transport http` is for. Norn never starts an http server; it only connects to one, and
+a refused connection fails before any model spend, naming the URL it tried.
+
+## The judge, and the CI story
+
+The last line of `TicketPROJ142` is the part that makes this a test rather than a demo:
+
+```norn
+judge report with Reviewer expects file expectations/proj-142.md
+```
+
+Every expectation in [`expectations/proj-142.md`](./expectations/proj-142.md) must be met;
+testing *more* than the list is not a failure. The judge is never asked for an overall verdict —
+it rules on each expectation and quotes its evidence, and Norn computes the result.
+
+Note the comment lines in that file. A line of prose left uncommented there **is** an
+expectation, which is both Norn's comment rule and what makes Markdown headings work.
+
+A live run records itself under `.norn-cache/runs/`. Replay it with no servers running at all:
+
+```bash
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json
+```
+
+That is the CI answer for any expensive server: run it live where the servers exist, and gate
+pull requests on the replay — no browser, no API, no model, and the graph and contracts still
+checked. The recording keeps the tool names each granted server advertised, so a server that
+quietly gains or loses a tool is reported the next time a live run sees it.

package/demos/mcp-ticket-testing/agents.nornagent

@@ -0,0 +1,77 @@
+# Ticket testing — declared MCP servers, granted per agent.
+#
+# Every server this graph uses is declared here, beside the model, so the file says exactly
+# what it connects to. Nothing is left to a norn.config.json the reader cannot see.
+
+model Workbench
+    provider openai
+    name gpt-4o
+    apiKey {{$env.OPENAI_API}}
+end model
+
+# The browser. This demo ships a deterministic stand-in so it runs anywhere `node` does —
+# the declaration is the same shape a real Playwright MCP server takes:
+#
+#   mcp Browser
+#       transport stdio
+#       command npx playwright-mcp --headless --isolated
+#       session agent
+#   end mcp
+#
+# ...or, for a long-lived server you started yourself (a CI job with many sequences):
+#
+#   mcp Browser
+#       transport http
+#       url {{$env.BROWSER_MCP_URL}}     # e.g. http://localhost:8931/mcp
+#       timeout 120000                   # browser work is slow; the default is not for this
+#   end mcp
+mcp Browser
+    transport stdio
+    command node ./servers/browser-server.js
+    # One browser per agent invocation, closed when that hop ends. The default, `session run`,
+    # would share one browser across every agent in the sequence — which is what you want for a
+    # continuous flow, and what you do not want the moment a second agent is granted this server:
+    # it would inherit the first one's login and could pass a test it never authenticated for.
+    # Only FrontendTester reaches the browser here, so this is the safe default to author rather
+    # than a bleed this graph would actually suffer.
+    session agent
+end mcp
+
+# The team's own server: fixtures, endpoints, the audit log, the database.
+mcp House
+    transport stdio
+    command node ./servers/house-server.js
+end mcp
+
+agent FrontendTester
+    model Workbench
+    # The run of the browser: this agent drives the site, and which tools that needs is not
+    # something the author should have to enumerate.
+    mcp Browser
+    # From our own server it gets only what it needs to set up — and cannot reach the
+    # database or the audit log at all.
+    tools House.getFixtureUser, House.resetTenant
+    returns contracts/test-run.schema.json
+    system file prompts/frontend-tester.md
+end agent
+
+agent BackendTester
+    model Workbench
+    # The same server, narrowed differently. Both grants are visible per agent, in one file.
+    tools House.callEndpoint, House.readAuditLog, House.queryDb
+    returns contracts/test-run.schema.json
+    system file prompts/backend-tester.md
+end agent
+
+agent Reporter
+    model Workbench
+    system file prompts/reporter.md
+end agent
+
+agent Reviewer
+    model Workbench
+    system "
+    You are reviewing a QA report against a checklist of expected test cases.
+    Rule on each expectation independently and quote the report as evidence.
+    "
+end agent

package/demos/mcp-ticket-testing/contracts/test-run.schema.json

@@ -0,0 +1,31 @@
+{
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "surface": {
+            "type": "string",
+            "description": "Which side of the product was exercised: frontend or backend."
+        },
+        "cases": {
+            "type": "array",
+            "description": "One entry per test case actually carried out.",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "name": { "type": "string" },
+                    "steps": { "type": "array", "items": { "type": "string" } },
+                    "outcome": { "type": "string", "enum": ["passed", "failed"] },
+                    "evidence": { "type": "string" }
+                },
+                "required": ["name", "steps", "outcome", "evidence"]
+            }
+        },
+        "findings": {
+            "type": "array",
+            "description": "Anything that looked wrong. Empty when nothing did.",
+            "items": { "type": "string" }
+        }
+    },
+    "required": ["surface", "cases", "findings"]
+}

package/demos/mcp-ticket-testing/expectations/proj-142.md

@@ -0,0 +1,12 @@
+# Expected test cases for PROJ-142
+
+# Each line below is one expectation. All must be met; testing more than this is not a
+# failure. Lines starting with # are comments — prose left uncommented here would itself
+# become an expectation, which is both Norn's comment rule and what makes Markdown work.
+
+- A test covers that a signed-out visitor opening /orders is sent to the sign-in page
+- A test covers signing in and seeing the orders list
+- A test covers opening order A-1001 and reading its total
+- A test covers GET /orders/A-1001 returning 200 with the order
+- A test covers GET /orders/A-9999 returning 404
+- A test confirms endpoint calls reach the audit log

package/demos/mcp-ticket-testing/fixtures/proj-142.json

@@ -0,0 +1,13 @@
+{
+    "key": "PROJ-142",
+    "title": "Order detail page and order lookup endpoint",
+    "description": "A signed-in customer can open an order from the orders list and see its total. The API must return the order for a valid id and 404 for an unknown one.",
+    "acceptanceCriteria": [
+        "A signed-out visitor who opens /orders is sent to the sign-in page",
+        "After signing in, the orders list shows the customer's orders",
+        "Opening order A-1001 shows its total",
+        "GET /orders/A-1001 returns 200 with the order",
+        "GET /orders/A-9999 returns 404",
+        "Every endpoint call is written to the audit log"
+    ]
+}

package/demos/mcp-ticket-testing/prompts/backend-tester.md

@@ -0,0 +1,12 @@
+You test the backend of a web product through its team's own MCP server.
+
+Work only from the ticket you are given. For each acceptance criterion that is about an API,
+a database row, or an audit entry, exercise it with the tools you have and record what came
+back — never what you assume would come back.
+
+`callEndpoint` calls the API. `queryDb` reads seeded tables. `readAuditLog` returns what this
+run wrote. You have no browser, and you must not claim to have used one.
+
+Return the required JSON only: one case per criterion you exercised, the steps you took, the
+outcome, and a short quote of the evidence you saw. Put anything that looked wrong in
+`findings`. Set `surface` to "backend".

package/demos/mcp-ticket-testing/prompts/frontend-tester.md

@@ -0,0 +1,14 @@
+You test the front end of a web product by driving a browser through an MCP server.
+
+Work only from the ticket you are given. For each acceptance criterion that is about what a
+person sees or does in the browser, carry out the steps yourself with the browser tools and
+record what actually happened — never what you assume would happen.
+
+The browser starts signed out. `getFixtureUser` gives you the test account; `resetTenant`
+puts the tenant back to its seeded state before you start.
+
+Snapshots are text. Read the elements listed in a snapshot rather than guessing at a page.
+
+Return the required JSON only: one case per criterion you exercised, the steps you took, the
+outcome, and a short quote of the evidence you saw. Put anything that looked wrong in
+`findings`. Set `surface` to "frontend".

package/demos/mcp-ticket-testing/prompts/reporter.md

@@ -0,0 +1,10 @@
+You turn two test runs into one short QA report for a ticket.
+
+You are given the frontend run and the backend run. Write, in plain prose:
+
+1. Which test cases were carried out, naming each one.
+2. What the evidence was for each.
+3. Any findings, or a single sentence saying there were none.
+
+Report only what the runs contain. Do not invent a case that nobody ran, and do not soften a
+failure. Someone will check this report against the list of expected test cases.

package/demos/mcp-ticket-testing/servers/browser-server.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * A deterministic stand-in for Playwright MCP.
+ *
+ * The `mcp Browser` block in `agents.nornagent` is the *same shape* a real Playwright MCP
+ * declaration takes — see the commented block there — so this demo runs anywhere `node` does,
+ * with no browser download, while showing exactly what granting a browser looks like.
+ *
+ * It answers from a tiny scripted site, and its snapshots are text, which is what a browser
+ * agent should be working from anyway: image content never reaches a model's prompt.
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+
+const PAGES = {
+    '/login': {
+        title: 'Sign in',
+        elements: ['textbox "Email"', 'textbox "Password"', 'button "Sign in"']
+    },
+    '/orders': {
+        title: 'Your orders',
+        elements: ['link "A-1001"', 'link "A-1002"', 'button "New order"']
+    },
+    '/orders/A-1001': {
+        title: 'Order A-1001',
+        elements: ['heading "Order A-1001"', 'text "Total: 42.50"', 'button "Cancel order"']
+    }
+};
+
+const state = { url: '/login', signedIn: false, filled: {} };
+
+const TOOLS = [
+    {
+        name: 'browser_navigate',
+        description: 'Navigate to a path on the site under test.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { path: { type: 'string', description: 'Path to open, e.g. /orders.' } },
+            required: ['path']
+        }
+    },
+    {
+        name: 'browser_fill',
+        description: 'Fill a named field on the current page.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                field: { type: 'string', description: 'Field label, e.g. Email.' },
+                value: { type: 'string', description: 'Value to type.' }
+            },
+            required: ['field', 'value']
+        }
+    },
+    {
+        name: 'browser_click',
+        description: 'Click a named control on the current page.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { control: { type: 'string', description: 'Control label, e.g. Sign in.' } },
+            required: ['control']
+        }
+    },
+    {
+        name: 'browser_snapshot',
+        description: 'Return a text accessibility snapshot of the current page.',
+        inputSchema: { type: 'object', additionalProperties: false, properties: {} }
+    }
+];
+
+function structured(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value };
+}
+
+function snapshot() {
+    const page = PAGES[state.url] || { title: 'Not found', elements: [] };
+    return {
+        url: state.url,
+        title: page.title,
+        signedIn: state.signedIn,
+        elements: page.elements
+    };
+}
+
+async function main() {
+    const server = new Server(
+        { name: 'norn-demo-browser', version: '1.0.0' },
+        { capabilities: { tools: {} } }
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+    server.setRequestHandler(CallToolRequestSchema, async request => {
+        const args = request.params.arguments || {};
+        switch (request.params.name) {
+            case 'browser_navigate':
+                state.url = String(args.path || '/');
+                if (state.url !== '/login' && !state.signedIn) {
+                    // The whole point of a session: an unauthenticated visit lands on login.
+                    state.url = '/login';
+                }
+                return structured(snapshot());
+            case 'browser_fill':
+                state.filled[String(args.field)] = String(args.value);
+                return structured({ filled: args.field, ...snapshot() });
+            case 'browser_click':
+                if (String(args.control) === 'Sign in' && state.filled.Email && state.filled.Password) {
+                    state.signedIn = true;
+                    state.url = '/orders';
+                }
+                return structured(snapshot());
+            case 'browser_snapshot':
+                return structured(snapshot());
+            default:
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }]
+                };
+        }
+    });
+
+    await server.connect(new StdioServerTransport());
+}
+
+main().catch(error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});