@lenso/mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LioRael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# Local MCP adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@lenso/mcp` is an optional local stdio adapter for **existing, explicitly
+declared Lenso operations**. It uses the official MCP SDK's `Server` and
+`StdioServerTransport`. It does not start a remote server, accept credentials,
+implement business handlers, load Engine config, or expose a shell.
+
+## Trusted launch configuration
+
+Install the optional package in the application and create a dedicated entry:
+
+```ts
+import { serveStdio } from "@lenso/mcp";
+
+const adapter = await serveStdio({
+  root: import.meta.dir,
+  allow: [{ pluginId: "greeting", method: "greet" }],
+});
+
+// For explicit host shutdown, await adapter.close().
+```
+
+Configure an MCP host to launch `bun /absolute/path/to/mcp.ts`. The application
+root and allowlist belong to trusted host configuration, not model/tool input.
+There is deliberately no general-purpose command-line operation selector or
+dynamic config-module loader. Use a fresh process when changing source or the
+allowlist: normal trusted module caching still applies.
+
+Startup calls `inspect(root)` from `@lenso/cli` without application setup. Every
+allowlisted `(pluginId, method)` must already be declared. Duplicate, absent,
+runtime-validation-only, and non-object input schemas reject startup before
+protocol readiness. The adapter preserves Engine's converted input schema; it
+does not invent an empty schema or infer one from runtime service methods.
+Schemas must also satisfy the SDK's tool representation.
+
+Tool names are `operation_0`, `operation_1`, etc., in allowlist order. Their
+titles identify the canonical plugin/method. Clients should discover names
+through `tools/list`, not persist an index across launch configuration changes.
+Only those names resolve to fixed bindings; business arguments cannot select
+the root, module, method, or shell. Applications still own the meaning and
+safety of their business input.
+
+## Invocation, authorization, and output
+
+Each call delegates to `call(root, pluginId, method, input)` from `@lenso/cli`. The
+existing shared Standard Schema validator runs before setup; the existing
+service method runs with its service as `this`; CLI awaits app shutdown,
+including ordered business/cleanup diagnostics. No alternate execution graph,
+retry loop, HTTP actor, or authorization bypass exists here. Service
+authorization must remain in the application. A host allowlist is additional
+exposure policy, **not permission to bypass service authorization**.
+
+All requests in one stdio process use the trusted launch environment's identity.
+There is no per-request remote login or serialized-actor adapter. Run separate
+processes with separately authorized credentials when local callers require
+identity isolation. A developer who can change application code/config or use
+the raw DB has administrative authority outside the tool surface; this adapter
+does not grant that authority to its client. Remote credentials, audiences and
+scopes require a separately designed trusted ingress, not this stdio entry.
+
+Successful tool content contains one text block with Engine's deterministic,
+redacted JSON result. No output schema is fabricated. Undefined, cyclic,
+nonfinite, and nonplain output fails through the existing serialization policy.
+Business failures use `isError: true` with safe Engine/CLI diagnostic JSON,
+without raw input, arbitrary exception text, or stacks. Unknown tool names
+produce a protocol `InvalidParams` error; malformed messages are SDK-owned.
+Explicit application `CliError` messages must themselves be safe.
+
+Descriptions come from canonical operation metadata. MCP hints default
+conservatively: read-only only for an explicit read effect, destructive unless
+explicitly false, idempotent only for declared safe retry, open-world true.
+Hints are descriptive, not authorization or execution guarantees. Output
+descriptions are included when declared. Cancellation is always request-only
+at this adapter boundary, even if application metadata says otherwise.
+The full canonical description, including instance, source, schema availability
+and semantic metadata, is retained in `_meta["lenso/operation"]`.
+
+## Limits and shutdown
+
+Defaults are a 1 MiB SDK incoming read buffer, 256 KiB serialized business
+input, and 1 MiB redacted serialized result. Trusted options `maxFrameBytes`,
+`maxInputBytes`, and `maxOutputBytes` must be positive safe integers. These
+bound incoming framing and business payloads, not arbitrary allocations inside
+trusted application code or tool-discovery metadata.
+The output budget also bounds failed tool content. Oversized diagnostics retain
+their code and phase with `truncated: true`, omitting paths, details, causes and
+source to fit the limit. If even that header cannot fit, a fixed
+`output-too-large` diagnostic is returned. `maxOutputBytes` must be at least 91
+bytes so that fallback always fits. Serialization failures likewise use a safe
+bounded diagnostic, never arbitrary error text.
+
+Only one business call is admitted at a time; concurrent calls fail with
+`adapter-busy`, without a queue. The adapter checks SDK request cancellation
+before and after the awaited CLI call. The existing service API has no signal:
+cancelling a request does **not** stop in-flight service work, undo effects, or
+promise rollback. The client/SDK may discard the response. The adapter still
+awaits the call and cleanup before admitting another operation.
+
+`close()`, stdin EOF, SIGINT, and SIGTERM stop admission and drain the admitted
+call before closing transport and restoring console. No forced-termination or
+cleanup timeout promise is made. Hanging application work can hang shutdown;
+a host that force-kills the process cannot rely on cleanup completion.
+Detached tasks and acquired resources remain application-owned.
+
+## stdout and trust
+
+SDK protocol messages are the adapter's only stdout output. During startup,
+operation execution, and drain, console methods (including Bun's
+`console.write`) route to stderr. Common logging methods use the existing
+redaction policy and omit direct Error text. This is a **trusted in-process
+adapter, not a sandbox**: direct `process.stdout.write`, native logging,
+captured pre-start console references, or deliberately unsafe code can still
+corrupt protocol output or disclose secrets. Redaction cannot identify every
+secret under innocuous keys. Do not embed secrets in schema constraints or
+metadata, and do not print them.
+
+## SDK and specification verification
+
+Primary sources checked for this implementation:
+
+- [npm registry: official SDK latest 1.x](https://registry.npmjs.org/@modelcontextprotocol/sdk/latest),
+  pinned here to `1.32.1` (not a floating range).
+- [Official SDK source, v1.x](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x):
+  its protocol latest constant is `2025-11-25`; the SDK owns negotiation.
+- [Current MCP specification](https://modelcontextprotocol.io/specification/latest)
+  resolves to `2026-07-28`. The current SDK v2 uses split packages.
+- [2025-11-25 stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
+  and [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+This package deliberately uses the mature official monolithic v1 SDK. It does
+**not** claim implementation of the newer 2026-07-28 stateless protocol or
+v2-only features. No resources, prompts, tasks, elicitation, remote auth, or
+credentials are advertised.
+
+## Development
+
+The integration owner installs dependencies and owns the workspace lockfile.
+Rebuild `@lenso/core`, `@lenso/engine`, and `@lenso/cli` before consuming their exports.
+Then run from this package:
+
+```sh
+bun run typecheck
+bun run build
+bun test
+```
+
+Tests launch a real subprocess and communicate using the official SDK client
+and stdio transport. They cover discovery without setup, allowlisting, shared
+validation, service lifecycle, redaction, safe authorization/runtime
+diagnostics, unsupported output, payload limits, cancellation, and rejected
+concurrent requests.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type OperationBinding } from "@lenso/engine/application";
+export interface StdioOptions {
+    /** Trusted launch configuration, never supplied by an MCP tool. */
+    root: string;
+    allow: readonly {
+        pluginId: string;
+        method: string;
+    }[];
+    maxInputBytes?: number;
+    maxOutputBytes?: number;
+    maxFrameBytes?: number;
+    binding?: OperationBinding;
+}
+/**
+ * Owns a dedicated stdio process. Tools translate only to CLI call; no app or
+ * service lifecycle is implemented here. Close drains the admitted call.
+ */
+export declare function serveStdio(options: StdioOptions): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/index.js

@@ -0,0 +1,243 @@
+// @bun
+// src/index.ts
+import { Console } from "console";
+import { join, resolve } from "path";
+import { Writable } from "stream";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+  ToolSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { invoke, CliError, diagnostic } from "@lenso/cli";
+import { readApplication } from "@lenso/engine/application";
+import {
+  describeOperation,
+  redactOperationDescription,
+  validateOperations
+} from "@lenso/engine/operations";
+import { environmentSecrets, redact, stableJson } from "@lenso/engine/diagnostics";
+var serving = false;
+function failure(code, phase, message) {
+  return new CliError({ code, phase, message });
+}
+function limit(value, fallback) {
+  const bytes = value ?? fallback;
+  if (!Number.isSafeInteger(bytes) || bytes < 1)
+    throw failure("invalid-arguments", "arguments", "Limits must be positive safe integers.");
+  return bytes;
+}
+function result(data, maxBytes) {
+  stableJson(data);
+  const text = stableJson(redact(data, environmentSecrets()));
+  if (Buffer.byteLength(text) > maxBytes)
+    throw failure("output-too-large", "output", "Operation output exceeds the host limit.");
+  return { content: [{ type: "text", text }] };
+}
+var oversizedDiagnostic = stableJson({
+  code: "output-too-large",
+  phase: "output",
+  message: "Diagnostic exceeds the host limit."
+});
+function errorResult(error, maxBytes) {
+  let text;
+  try {
+    const detail = diagnostic(error);
+    text = stableJson(redact(detail, environmentSecrets()));
+    if (Buffer.byteLength(text) > maxBytes) {
+      text = stableJson(redact({
+        code: detail.code,
+        phase: detail.phase,
+        message: "Diagnostic truncated to the host output limit.",
+        truncated: true
+      }, environmentSecrets()));
+    }
+  } catch {
+    text = stableJson({
+      code: "serialization-failed",
+      phase: "output",
+      message: "Diagnostic is not JSON data."
+    });
+  }
+  if (Buffer.byteLength(text) > maxBytes)
+    text = oversizedDiagnostic;
+  return { isError: true, content: [{ type: "text", text }] };
+}
+async function serveStdio(options) {
+  if (serving)
+    throw failure("invalid-arguments", "arguments", "Only one stdio adapter may own this process.");
+  const root = resolve(options.root);
+  const maxInput = limit(options.maxInputBytes, 256 * 1024);
+  const maxOutput = limit(options.maxOutputBytes, 1024 * 1024);
+  if (maxOutput < Buffer.byteLength(oversizedDiagnostic))
+    throw failure("invalid-arguments", "arguments", "Output limit must fit a bounded diagnostic.");
+  const maxFrame = limit(options.maxFrameBytes, 1024 * 1024);
+  serving = true;
+  const originalConsole = globalThis.console;
+  const logs = new Writable({
+    write(chunk, _encoding, done) {
+      process.stderr.write(String(redact(chunk.toString(), environmentSecrets())), done);
+    }
+  });
+  globalThis.console = Object.assign(new Console({ stdout: logs, stderr: logs }), {
+    write(...values) {
+      const text = values.map((value) => typeof value === "string" ? value : Buffer.from(ArrayBuffer.isView(value) ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength) : new Uint8Array(value)).toString()).join("");
+      logs.write(text);
+      return Buffer.byteLength(text);
+    }
+  });
+  for (const level of [
+    "log",
+    "info",
+    "warn",
+    "error",
+    "debug",
+    "dir",
+    "dirxml",
+    "table",
+    "trace"
+  ]) {
+    globalThis.console[level] = (...values) => {
+      const safe = values.map((value) => value instanceof Error ? "[Application error text omitted]" : redact(value, environmentSecrets()));
+      logs.write(`${safe.map((value) => typeof value === "string" ? value : JSON.stringify(value)).join(" ")}
+`);
+    };
+  }
+  globalThis.console.assert = (condition, ...values) => {
+    if (!condition)
+      globalThis.console.error("Assertion failed:", ...values);
+  };
+  let server;
+  let active;
+  let closing = false;
+  let closePromise;
+  const restore = () => {
+    globalThis.console = originalConsole;
+    serving = false;
+  };
+  const close = () => {
+    if (closePromise)
+      return closePromise;
+    closing = true;
+    closePromise = (async () => {
+      try {
+        await active;
+        await server?.close();
+      } finally {
+        process.stdin.off("end", onEnd);
+        process.off("SIGINT", onEnd);
+        process.off("SIGTERM", onEnd);
+        restore();
+      }
+    })();
+    return closePromise;
+  };
+  const onEnd = () => {
+    close().catch(() => {
+      process.exitCode = 1;
+    });
+  };
+  try {
+    const { app, configPath } = await readApplication(root, join(root, "lenso.config.ts"));
+    const selected = validateOperations(app.plugins, app.mcpOperations ?? app.operations ?? []);
+    const tools = [];
+    const bindings = new Map;
+    const seen = new Set;
+    for (const allowed of options.allow) {
+      const key = stableJson([allowed.pluginId, allowed.method]);
+      if (seen.has(key))
+        throw failure("duplicate-operation", "discovery", "Duplicate MCP allowlist entry.");
+      seen.add(key);
+      const ref = selected.find((item) => item.plugin.id === allowed.pluginId && item.method === allowed.method);
+      const operation = ref ? redactOperationDescription(describeOperation(ref, configPath)) : undefined;
+      if (!operation)
+        throw failure("unknown-operation", "discovery", "MCP allowlist operation is not declared.");
+      const schema = operation.inputSchema;
+      if (!schema || schema.type !== "object")
+        throw failure("unsupported-input-schema", "discovery", "MCP tools require a convertible object input schema.");
+      stableJson(schema);
+      const name = `operation_${tools.length}`;
+      const tool = {
+        name,
+        title: `${operation.pluginId}.${operation.method}`,
+        description: [
+          operation.description,
+          ...operation.outputDescription ? [`Output: ${operation.outputDescription}`] : [],
+          "Cancellation is request-only: in-flight work and cleanup are awaited; no rollback or automatic retry."
+        ].join(`
+`),
+        inputSchema: schema,
+        _meta: { "lenso/operation": operation },
+        execution: { taskSupport: "forbidden" },
+        annotations: {
+          readOnlyHint: operation.effect === "read",
+          destructiveHint: operation.destructive ?? true,
+          idempotentHint: operation.retry === "safe",
+          openWorldHint: true
+        }
+      };
+      if (!ToolSchema.safeParse(tool).success)
+        throw failure("unsupported-input-schema", "discovery", "Operation schema cannot be represented as an MCP tool.");
+      tools.push(tool);
+      bindings.set(name, { pluginId: allowed.pluginId, method: allowed.method });
+    }
+    server = new Server({ name: "lenso", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+      const binding = bindings.get(request.params.name);
+      if (!binding)
+        throw new McpError(ErrorCode.InvalidParams, "Tool is not allowlisted.", {
+          code: "unknown-operation"
+        });
+      if (request.params.task)
+        throw new McpError(ErrorCode.InvalidParams, "Task-augmented calls are not supported.");
+      if (closing)
+        return errorResult(failure("adapter-closed", "invoke", "Adapter is shutting down."), maxOutput);
+      if (active)
+        return errorResult(failure("adapter-busy", "invoke", "One operation is already running; no request was queued."), maxOutput);
+      const execute = async () => {
+        try {
+          if (extra.signal.aborted)
+            throw failure("request-cancelled", "invoke", "Request cancelled before invocation.");
+          const input = request.params.arguments ?? {};
+          if (Buffer.byteLength(stableJson(input)) > maxInput)
+            throw failure("input-too-large", "input", "Operation input exceeds the host limit.");
+          const data = await invoke({ ...app, operations: selected, operationBinding: undefined }, binding.pluginId, binding.method, input, async (operation, validatedInput, running) => ({
+            ...options.binding ? await options.binding(operation, validatedInput, running) : {},
+            maxOutputBytes: maxOutput
+          }));
+          if (extra.signal.aborted)
+            throw failure("request-cancelled", "invoke", "Request cancelled; operation may have completed. Cleanup was awaited.");
+          return result(data, maxOutput);
+        } catch (error) {
+          return errorResult(error, maxOutput);
+        }
+      };
+      active = execute();
+      try {
+        return await active;
+      } finally {
+        active = undefined;
+      }
+    });
+    server.onerror = () => {
+      process.stderr.write(`MCP protocol error (details omitted).
+`);
+    };
+    server.onclose = onEnd;
+    process.stdin.once("end", onEnd);
+    process.on("SIGINT", onEnd);
+    process.on("SIGTERM", onEnd);
+    await server.connect(new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: maxFrame }));
+    return { close };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+export {
+  serveStdio
+};

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@lenso/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioRael/lenso.git",
+    "directory": "packages/mcp"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target bun --packages external && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@lenso/cli": "^0.19.0",
+    "@lenso/engine": "^0.2.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@lenso/core": "^0.2.0"
+  }
+}