@columenlabs/lumen-ai 0.0.0-stage → 0.1.38

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Columen Labs
+
+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/NOTICE

@@ -0,0 +1,12 @@
+Lumen
+Copyright (c) 2026 Columen Labs. Licensed under the MIT License (see LICENSE).
+
+Lumen draws price and market charts with TradingView Lightweight Charts™
+(https://github.com/tradingview/lightweight-charts), Copyright (c) 2025
+TradingView, Inc., licensed under the Apache License 2.0. Lumen turns off the
+chart's own logo, so per that library's NOTICE, an app that shows these charts
+should link to https://www.tradingview.com/ somewhere a user can find it (an
+About page or footer is enough).
+
+The components under packages/ui/src/ui are based on shadcn/ui
+(https://ui.shadcn.com), MIT License, Copyright (c) 2023 shadcn.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @columenlabs/lumen-ai
 
-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.
+Assistant and agent parts for apps on Cloudflare Workers. Today: serving an MCP server from a Worker, keeping only the read tools for a read-only caller, and metering every tool call. A product-neutral assistant joins later.
+
+## Install
+
+```sh
+bun add @columenlabs/lumen-ai @columenlabs/lumen-ops @modelcontextprotocol/sdk
+```
+
+Pin every `@columenlabs/lumen-*` package to the same exact version. `@modelcontextprotocol/sdk` is a peer: the app's own copy builds the server.
+
+## Serve an MCP server
+
+Build one server per request for the caller you have already checked, then hand it the request. Each request stands alone (stateless Streamable HTTP, JSON responses), since a Worker keeps nothing between requests.
+
+```ts
+import { jsonResult, keepReadTools, meterTools, serveMcp } from '@columenlabs/lumen-ai';
+import { setToolSink } from '@columenlabs/lumen-ops/tools';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+setToolSink(env.TOOL_CALLS); // once per isolate; tool calls are metered only when it is set
+
+function build(person: string) {
+  const mcp = new McpServer({ name: 'my-app', version: '1.0.0' });
+  mcp.registerTool(
+    'account_list',
+    { description: 'Accounts and balances', annotations: { readOnlyHint: true } },
+    async () => jsonResult(await accounts(person)),
+  );
+  return mcp;
+}
+
+app.all('/mcp', async (c) => {
+  const server = meterTools(build(c.get('person')), { app: 'my-app' });
+  if (c.get('viewOnly')) keepReadTools(server);
+  return serveMcp(server, c.req.raw, { onRequest: ({ tool }) => c.set('tool', tool) });
+});
+```
+
+## Exports
+
+| Export | What it does |
+|---|---|
+| `serveMcp(server, request, opts?)` | Answers one MCP request and closes the server; `onRequest` hears the method and tool first |
+| `jsonResult(value)` | A tool result holding one JSON value as text |
+| `keepReadTools(server, isRead?)` | Removes every tool that writes; by default a tool is read-only when its `readOnlyHint` is set |
+| `meterTools(server, opts)` | Wraps every registered tool so each call is one tool-call point: wall time, outcome, rows of a JSON list, input and output size |
+| `registeredTools(server)` | Every tool on a server, by name |
+| `mcpCallOf(body)` | The method and tool a JSON-RPC body asks for |
+
+`meterTools` writes through `@columenlabs/lumen-ops/tools`; see its README for the columns.
+
+## Versions
+
+Every merge to `main` publishes the next patch of every Lumen package at once.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './mcp.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './mcp.js';

package/dist/mcp.d.ts

@@ -0,0 +1,47 @@
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** A tool result holding one JSON value as text, what most tools return. */
+export declare function jsonResult(value: unknown): {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};
+/** What one JSON-RPC request asks for, for a request log: its method and, for a call, the tool. */
+export declare function mcpCallOf(body: unknown): {
+    method?: string;
+    tool?: string;
+};
+export interface ServeMcpOptions {
+    /** Told what the request asks for before it runs (the method, and the tool for a call). */
+    onRequest?: (call: {
+        method?: string;
+        tool?: string;
+    }) => void;
+}
+/**
+ * Answers one MCP request with `server`, built for this caller, then closes it. JSON responses, no
+ * session: each request stands alone. The caller is already checked.
+ */
+export declare function serveMcp(server: McpServer, request: Request, opts?: ServeMcpOptions): Promise<Response>;
+/** Every tool registered on `server`, by name. */
+export declare function registeredTools(server: McpServer): Record<string, RegisteredTool>;
+/** A tool marked read-only (`readOnlyHint`), the default test for `keepReadTools`. */
+export declare const readOnlyHint: (_name: string, tool: RegisteredTool) => boolean;
+/** Removes every tool `isRead` says writes, for a caller who may only read. Returns `server`. */
+export declare function keepReadTools(server: McpServer, isRead?: (name: string, tool: RegisteredTool) => boolean): McpServer;
+export interface MeterToolsOptions {
+    /** The app, or the part of it, the server belongs to. */
+    app: string;
+    /** Who is calling: `mcp` for an outside client, or the app's own word (an assistant). */
+    source?: string;
+    /** The turn or run the calls belong to. */
+    run?: string;
+    /** A short error kind for a throw; default `error`. */
+    errorKind?: (err: unknown) => string;
+}
+/**
+ * Wraps every tool registered on `server` so each call is one tool-call point (lumen-ops/tools):
+ * its wall time, rows when the result is a JSON list, the size of its input and output, and
+ * whether it failed. Call it after the tools are registered. Returns `server`.
+ */
+export declare function meterTools(server: McpServer, opts: MeterToolsOptions): McpServer;

package/dist/mcp.js

@@ -0,0 +1,112 @@
+/**
+ * Serving an MCP server from a Worker: one stateless Streamable HTTP request at a time (a Worker
+ * keeps nothing between requests), plus the small pieces every app's server repeats: a JSON
+ * result, keeping only the read tools for a read-only caller, and metering every tool call.
+ */
+import { meterToolCall } from '@columenlabs/lumen-ops/tools';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/** A tool result holding one JSON value as text, what most tools return. */
+export function jsonResult(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value) }] };
+}
+/** What one JSON-RPC request asks for, for a request log: its method and, for a call, the tool. */
+export function mcpCallOf(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const b = body;
+    return {
+        method: typeof b.method === 'string' ? b.method : undefined,
+        tool: typeof b.params?.name === 'string' ? b.params.name : undefined,
+    };
+}
+/**
+ * Answers one MCP request with `server`, built for this caller, then closes it. JSON responses, no
+ * session: each request stands alone. The caller is already checked.
+ */
+export async function serveMcp(server, request, opts = {}) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    try {
+        const body = await request
+            .clone()
+            .json()
+            .catch(() => undefined);
+        opts.onRequest?.(mcpCallOf(body));
+        return await transport.handleRequest(request, body === undefined ? undefined : { parsedBody: body });
+    }
+    finally {
+        // JSON-response mode has fully answered by now.
+        void server.close();
+    }
+}
+/** Every tool registered on `server`, by name. */
+export function registeredTools(server) {
+    return server
+        ._registeredTools;
+}
+/** A tool marked read-only (`readOnlyHint`), the default test for `keepReadTools`. */
+export const readOnlyHint = (_name, tool) => tool.annotations?.readOnlyHint === true;
+/** Removes every tool `isRead` says writes, for a caller who may only read. Returns `server`. */
+export function keepReadTools(server, isRead = readOnlyHint) {
+    for (const [name, tool] of Object.entries(registeredTools(server))) {
+        if (!isRead(name, tool))
+            tool.remove();
+    }
+    return server;
+}
+/**
+ * Wraps every tool registered on `server` so each call is one tool-call point (lumen-ops/tools):
+ * its wall time, rows when the result is a JSON list, the size of its input and output, and
+ * whether it failed. Call it after the tools are registered. Returns `server`.
+ */
+export function meterTools(server, opts) {
+    for (const [name, tool] of Object.entries(registeredTools(server))) {
+        const handler = tool.handler;
+        tool.handler = (async (...args) => {
+            const point = {
+                app: opts.app,
+                tool: name,
+                kind: 'call',
+                source: opts.source ?? 'mcp',
+                run: opts.run,
+            };
+            const bytesIn = args.length > 1 ? JSON.stringify(args[0] ?? null).length : 0;
+            const t0 = performance.now();
+            try {
+                const out = (await handler(...args));
+                const text = out?.content?.[0]?.text ?? '';
+                let rows;
+                try {
+                    const v = JSON.parse(text);
+                    if (Array.isArray(v))
+                        rows = v.length;
+                }
+                catch { }
+                meterToolCall({
+                    ...point,
+                    ok: !out?.isError,
+                    ms: performance.now() - t0,
+                    ...(out?.isError ? { error: 'tool_error' } : {}),
+                    rows,
+                    bytesIn,
+                    bytesOut: text.length,
+                });
+                return out;
+            }
+            catch (err) {
+                meterToolCall({
+                    ...point,
+                    ok: false,
+                    ms: performance.now() - t0,
+                    error: opts.errorKind?.(err) ?? 'error',
+                    bytesIn,
+                });
+                throw err;
+            }
+        });
+    }
+    return server;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.38",
+  "description": "Lumen's assistant and agent parts: serving an MCP server from a Worker, read-only tool sets and metered tool calls.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "homepage": "https://github.com/columenlabs/lumen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/columenlabs/lumen.git",
+    "directory": "packages/ai"
+  },
+  "bugs": "https://github.com/columenlabs/lumen/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@columenlabs/lumen-ops": "0.1.38"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}