@klura/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,113 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Narek Mailian, a natural person resident in Sweden,
+                      his successors and assigns
+
+Licensed Work:        klura-mcp
+                      Copyright (c) 2026 Narek Mailian and Klura
+                      contributors
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided that your production use does not include any
+                      of the following:
+
+                      (a) offering the Licensed Work, in whole or in part,
+                          to third parties as a hosted or managed service;
+
+                      (b) exposing the Licensed Work's functionality to
+                          third parties via an API, SDK, or other interface;
+
+                      (c) using the Licensed Work to build, offer, or
+                          operate a product or service that competes with
+                          any commercial product or service offered by
+                          Licensor (a "Competing Service"); or
+
+                      (d) sublicensing, selling, or reselling access to the
+                          Licensed Work or its functionality.
+
+Change Date:          2030-04-23
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact hello@klura.ai.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License,
+   as the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,57 @@
+# @klura/mcp
+
+MCP (Model Context Protocol) server for [@klura/runtime](https://www.npmjs.com/package/@klura/runtime). Exposes the klura runtime's browser-automation + skill-discovery toolset to any MCP client — Claude Desktop, Claude Code, Cursor, Windsurf, and others.
+
+`@klura/runtime` is the runtime that turns websites into reusable skills: drive the site once, save the recipe, skip the browser on every subsequent run. `@klura/mcp` is the thin wrapper that speaks MCP on top of it. See the [runtime README](https://www.npmjs.com/package/@klura/runtime) for what the skills actually do and how they get saved.
+
+## Install
+
+```bash
+npm install -g @klura/mcp
+```
+
+The `@klura/runtime` package is declared as a dependency and installed alongside. The runtime auto-starts a local daemon on first use and stores everything it learns under `~/.klura/`.
+
+## Wire it up
+
+Add the server to your MCP client's config. The exact file path depends on the client — the server definition is the same.
+
+```json
+{
+  "mcpServers": {
+    "klura": {
+      "command": "npx",
+      "args": ["-y", "@klura/mcp"]
+    }
+  }
+}
+```
+
+Restart the client. The agent picks up the klura toolset automatically.
+
+## What it exposes
+
+Two surfaces land in the agent's context:
+
+- **Tools** — browser automation (`start_session`, `perform_action`, `get_screenshot`, `get_a11y_tree`), discovery + persistence (`save_strategy`, `execute`, `list_platform_skills`, `get_strategy`), network-log inspection (`get_network_log`, `find_in_page`), and the reverse-engineering escape hatches (`inspect_ws_frame`, `try_generator`, `js_eval`, `get_js_source`, `search_js_source`, `read_js_function`, `set_breakpoint`, `wait_for_pause`, and more). The runtime owns the canonical list; this server mirrors it one-for-one.
+- **Resource** `klura://reference` — the detailed reference doc, served section-by-section via URL fragments (`klura://reference#reverse-engineer-playbook`, `klura://reference#strategy-schemas-overview`, etc.) so each response fits inside the MCP output budget. Fetch `klura://reference` with no fragment for a table of contents.
+
+The always-loaded orientation is SKILL.md, passed as the server's `instructions` capability. Agents read SKILL.md on every conversation and pull detail on demand via the `klura://reference` fragments.
+
+## How it works
+
+Thin wrapper — each MCP `tools/call` dispatches to the corresponding klura runtime function. The runtime handles daemon lifecycle, browser sessions, strategy persistence under `~/.klura/skills/`, and execution.
+
+```
+MCP client (Claude Desktop, Cursor, …)
+    │  stdio transport, JSON-RPC
+    ▼
+klura-mcp (this package)
+    │  Node require('@klura/runtime')
+    ▼
+klura runtime → local daemon → Playwright
+```
+
+## License
+
+BUSL-1.1. See [LICENSE](LICENSE). Same terms as the underlying `@klura/runtime`; see the runtime README for the commercial-use terms.

package/index.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+
+// Klura MCP Server — exposes browser automation tools via Model Context Protocol.
+// Works with Claude Desktop, Cursor, Windsurf, and any MCP client.
+//
+// Usage:
+//   npx @klura/mcp           (stdio transport)
+//
+// MCP config:
+//   {
+//     "mcpServers": {
+//       "klura": {
+//         "command": "npx",
+//         "args": ["-y", "@klura/mcp"]
+//       }
+//     }
+//   }
+
+// Build the klura MCP server — wires every tool + resource handler onto a
+// fresh Server instance and returns it unconnected. Callers pick a transport:
+// `main()` below attaches stdio for the CLI path; the field-reports harness
+// imports this directly and passes the instance to the Agent SDK via
+// `{type:'sdk', instance}` so the browser pool survives across SDK `resume`
+// queries (each resume would otherwise spawn a fresh stdio child and orphan
+// every in-memory session).
+async function createKluraMcpServer() {
+  const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+  const { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } = await import('@modelcontextprotocol/sdk/types.js');
+  // Load klura runtime
+  const klura = require('@klura/runtime');
+
+  // SKILL.md (compact) is the always-loaded orientation.
+  // REFERENCE.md (detailed schemas, examples) is served as an on-demand
+  // resource via klura.resolveReferenceResource — see the ReadResource
+  // handler below for the fragment-based section addressing.
+  const skillMd = klura.getSkillMd()
+    .replace(/^---[\s\S]*?---\s*/, ''); // strip frontmatter
+
+  const server = new Server(
+    { name: '@klura/mcp', version: '0.1.0' },
+    { capabilities: { tools: {}, resources: {} }, instructions: skillMd }
+  );
+
+  // -- Resources (on-demand reference docs) --
+  //
+  // REFERENCE.md is served section-by-section via URL fragments so each
+  // response fits inside the MCP output budget. Fetching `klura://reference`
+  // with no fragment returns a short table of contents listing every
+  // addressable `#<slug>`; fetching `klura://reference#<slug>` returns only
+  // that section. The section parser + budget logic lives in the runtime
+  // module (`runtime/src/reference-sections.ts`) so a pre-commit test can
+  // assert every section fits before a regression lands.
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const sections = klura.listReferenceSections();
+    return {
+      resources: [
+        {
+          uri: 'klura://reference',
+          name: 'Klura Reference — Table of Contents',
+          description:
+            'Table of contents for the detailed reference. Fetch individual sections by appending a URL fragment, e.g. klura://reference#fetch-schema. ' +
+            `Available sections: ${sections.map((s) => '#' + s.slug).join(', ')}.`,
+          mimeType: 'text/markdown',
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    try {
+      const { text } = klura.resolveReferenceResource(uri);
+      return {
+        contents: [{ uri, mimeType: 'text/markdown', text }],
+      };
+    } catch (err) {
+      // Surface the runtime's helpful error (which lists available slugs)
+      // directly to the MCP client instead of swallowing it.
+      throw new Error(err instanceof Error ? err.message : String(err));
+    }
+  });
+
+  // -- Tool registry --
+  //
+  // Every tool's schema and handler live colocated in mcp/tools.js. The
+  // ListTools handler reads the registry; the CallTool dispatcher looks up
+  // the entry by name and invokes its handler. Adding a tool means adding
+  // exactly one entry there — no separate switch case to keep in sync.
+  const tools = require('./tools.js')(klura);
+  const toolByName = new Map(tools.map((t) => [t.name, t]));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+  }));
+
+  // OpenAI-style tool_calls deliver `arguments` as a JSON string parsed
+  // once by the client. Many non-Anthropic models then JSON-encode nested
+  // object/array fields a SECOND time, so we receive `args.foo === "{...}"`
+  // where the schema declares `foo: {type: 'object'}`. Walk the inputSchema
+  // and parse strings that the schema says shouldn't be strings. Only
+  // strict JSON ('{', '['); leave anything else alone so we don't disturb
+  // legitimately stringy fields. Best-effort: if parse fails or the value
+  // doesn't match the declared type after parsing, leave it for the
+  // runtime's own validators to reject with a useful error.
+  function coerceArgs(toolName, args) {
+    const tool = toolByName.get(toolName);
+    const schema = tool && tool.inputSchema;
+    if (!schema || !schema.properties || !args || typeof args !== 'object') return args;
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const v = args[key];
+      if (typeof v !== 'string') continue;
+      const expected = propSchema?.type;
+      const wantsContainer =
+        expected === 'object' ||
+        expected === 'array' ||
+        (Array.isArray(expected) && (expected.includes('object') || expected.includes('array')));
+      if (!wantsContainer) continue;
+      const trimmed = v.trim();
+      if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        const parsedType = Array.isArray(parsed) ? 'array' : typeof parsed;
+        const matches = Array.isArray(expected)
+          ? expected.includes(parsedType)
+          : expected === parsedType;
+        if (matches) args[key] = parsed;
+      } catch { /* leave for downstream validator */ }
+    }
+    return args;
+  }
+
+  // -- Tool execution --
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: rawArgs } = request.params;
+    const tool = toolByName.get(name);
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+    const args = coerceArgs(name, rawArgs);
+
+    try {
+      // Phase admissibility — hard tool blocking per the session-phase
+      // state machine. Tools not in the current phase's allowedTools
+      // (or, when budget is exhausted, not in allowedToolsWhenExhausted)
+      // are rejected here without running. Universal tools (control
+      // plane, memory reads, escape valve) bypass; tools called without
+      // a session (start_session, etc.) bypass too. After admission,
+      // tickPhaseCounter increments the per-phase round counter and
+      // engages the soft-block flag when the budget is hit.
+      if (args && args.session_id) {
+        try {
+          klura.assertToolAdmissibleBySessionId(args.session_id, name);
+        } catch (err) {
+          if (err instanceof klura.ToolNotAdmissibleError) {
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify({
+                    ok: false,
+                    error: 'tool_not_admissible',
+                    phase: err.phase,
+                    tool: err.toolName,
+                    message: err.reason,
+                  }, null, 2),
+                },
+              ],
+              isError: true,
+            };
+          }
+          throw err;
+        }
+      }
+
+      // Pending-interruption / pending-checkpoint gates. A prior tool
+      // call returned a handover resolution; every subsequent tool call
+      // on the same session must echo the relevant token + an ack
+      // (user_response / viewer_result) or cancel with {cancelled: true,
+      // reason}. Tools that deliberately resolve the matching pending
+      // state opt out via `skipInterruptionGate` / `skipCheckpointGate`
+      // on their registry entry.
+      if (args && args.session_id && !tool.skipInterruptionGate) {
+        klura.assertNoPendingInterruption(args.session_id, {
+          interruption_token: args.interruption_token,
+          user_response: args.user_response,
+          viewer_result: args.viewer_result,
+          cancelled: args.cancelled,
+          reason: args.reason,
+        });
+      }
+      if (args && args.session_id && !tool.skipCheckpointGate) {
+        klura.assertNoPendingCheckpoint(args.session_id, {
+          checkpoint_token: args.checkpoint_token,
+          user_response: args.user_response,
+          viewer_result: args.viewer_result,
+          cancelled: args.cancelled,
+          reason: args.reason,
+        });
+      }
+
+      let result = await tool.handler(args);
+
+      // Inject sticky LIFT obligation reminder. Fires on every tool
+      // response between the first mutating perform_action and either a
+      // successful save_strategy or close_session ok:true. Once-per-session
+      // semantics → no token-binding needed (see runtime/docs/gates.md
+      // §once-vs-many). klura.formatToolResult hoists the obligation
+      // message into a leading [klura obligation]: <message> text block
+      // so the model reads it as a top-level directive rather than buried
+      // inside the JSON-stringified payload — that hoist + the imperative
+      // wording in session-obligations.ts is the primary mechanism. If a
+      // model still ends_turn with an open obligation despite reading the
+      // hoisted block, treat that as a runtime weakness worth surfacing,
+      // not a harness gap to paper over.
+      if (args && args.session_id) {
+        try {
+          const obligation = klura.getSessionObligation(args.session_id);
+          if (obligation && result && typeof result === 'object' && !Array.isArray(result)) {
+            result = { ...result, _session_obligation: obligation };
+          }
+        } catch {
+          /* non-fatal */
+        }
+      }
+
+      // Convert to MCP content blocks (screenshots become image blocks)
+      const blocks = klura.formatToolResult(name, result);
+      return {
+        content: blocks.map(b =>
+          b.type === 'image'
+            ? { type: 'image', data: b.data, mimeType: b.mediaType }
+            : { type: 'text', text: b.text }
+        ),
+      };
+    } catch (err) {
+      // Attach the LIFT obligation to error responses too. Without this,
+      // every save_strategy / close_session rejection drops the "MUST be
+      // close_session" anchor exactly when the agent most needs it — agents
+      // reading just the bare error treat the failure as a one-off shape
+      // complaint and end the turn after the user-facing goal looks done.
+      let obligationLine = '';
+      if (args && args.session_id) {
+        try {
+          const obligation = klura.getSessionObligation(args.session_id);
+          if (obligation && obligation.message) {
+            obligationLine = `[klura obligation]: ${obligation.message}\n\n`;
+          }
+        } catch { /* non-fatal */ }
+      }
+
+      // klura's audit-style rejections (`invalid_<kind>: ...` and
+      // `invalid_<kind>_rejected (<reason>)`) are iteration steps, not tool
+      // errors — the agent's expected next move is to re-call the same tool
+      // with audit_token + audit_answers. Returning these with
+      // `isError: true` makes the SDK surface them as tool errors, which
+      // Claude reads as "task failed, here's why" and reflexively wraps up
+      // with text (end_turn) instead of continuing the iteration loop. Send
+      // them as normal text results so the model treats them as data.
+      const msg = typeof err.message === 'string' ? err.message : String(err);
+      if (/^invalid_[a-z_]+:/.test(msg)) {
+        return {
+          content: [{ type: 'text', text: `${obligationLine}${msg}` }],
+        };
+      }
+      return {
+        content: [{ type: 'text', text: `${obligationLine}Error: ${msg}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+async function main() {
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const server = await createKluraMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+module.exports = { createKluraMcpServer };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('Klura MCP server failed:', err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@klura/mcp",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "MCP server for klura — exposes browser automation tools via Model Context Protocol",
+  "main": "index.js",
+  "bin": {
+    "klura-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "tools.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "klura",
+    "web-automation",
+    "browser"
+  ],
+  "license": "BUSL-1.1",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@klura/runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "typescript-eslint": "^8.58.0"
+  }
+}