@anteros/core 0.0.20 → 0.0.21

package/server/mcp.ts

@@ -0,0 +1,232 @@
+import type { Hono, Context } from "hono";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+    ListToolsRequestSchema,
+    CallToolRequestSchema,
+    ListResourcesRequestSchema,
+    ListResourceTemplatesRequestSchema,
+    ReadResourceRequestSchema,
+    McpError,
+    ErrorCode,
+} from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPTransport } from "@hono/mcp";
+import type Joi from "joi";
+import { cfg } from "./config";
+import { useRest } from "../database/rest";
+import type { McpTool, McpResource } from "../types/mcp";
+import type { HonoVariables } from "./env";
+
+// ─── Joi → JSON Schema (for the MCP protocol) ────────────────────────────
+
+function joiTypeToJson(type: string): string {
+    switch (type) {
+        case 'number': return 'number';
+        case 'integer': return 'integer';
+        case 'boolean': return 'boolean';
+        case 'date': return 'string';
+        default: return 'string';
+    }
+}
+
+/** Minimal Joi → JSON Schema converter (covers the common field types). */
+function joiToJsonSchema(schema: Joi.Schema, describe = schema.describe() as any): any {
+    const node: any = {};
+    const type = describe?.type;
+
+    switch (type) {
+        case 'object': {
+            node.type = 'object';
+            const properties: Record<string, any> = {};
+            const required: string[] = [];
+            for (const [key, child] of Object.entries(describe.keys ?? {})) {
+                properties[key] = joiToJsonSchema(child as any, child);
+                if ((child as any)?.flags?.presence === 'required') required.push(key);
+            }
+            node.properties = properties;
+            if (required.length) node.required = required;
+            break;
+        }
+        case 'array': {
+            node.type = 'array';
+            if (describe.items?.length) node.items = joiToJsonSchema(describe.items[0], describe.items[0]);
+            break;
+        }
+        default: {
+            node.type = joiTypeToJson(type);
+            if (type === 'date') node.format = 'date-time';
+            if (type === 'string') {
+                for (const rule of describe.rules ?? []) {
+                    if (['email', 'uri', 'uuid', 'isoDate', 'ip'].includes(rule.name)) {
+                        node.format = rule.name;
+                    }
+                    if (rule.name === 'pattern' && rule.args?.regex) {
+                        node.pattern = String(rule.args.regex).replace(/^\/|\/[gimsuy]*$/g, '');
+                    }
+                }
+            }
+            if (describe.valids?.length && describe.valids.length <= 50) {
+                node.enum = describe.valids;
+            }
+            break;
+        }
+    }
+
+    if (describe?.flags?.presence === 'required') node.description = node.description ?? 'required';
+    if (describe?.flags?.description) node.description = describe.flags.description;
+    return node;
+}
+
+// ─── URI template matching (users://{id} → params) ───────────────────────
+
+function compileTemplate(template: string): { regex: RegExp; params: string[] } {
+    const params: string[] = [];
+    const pattern = template.replace(/\{([^}]+)\}/g, (_, name) => {
+        params.push(name);
+        return '([^/]+)';
+    });
+    return { regex: new RegExp(`^${pattern}$`), params };
+}
+
+function matchUri(uri: string, resources: McpResource[]): { resource: McpResource; params: Record<string, string> } | null {
+    // Exact static match first
+    const staticMatch = resources.find((r) => r.uri === uri);
+    if (staticMatch) return { resource: staticMatch, params: {} };
+
+    // Template match
+    for (const resource of resources) {
+        if (!resource.uri.includes('{')) continue;
+        const { regex, params } = compileTemplate(resource.uri);
+        const m = uri.match(regex);
+        if (!m) continue;
+        const extracted: Record<string, string> = {};
+        params.forEach((name, i) => { extracted[name] = m[i + 1] ?? ''; });
+        return { resource, params: extracted };
+    }
+    return null;
+}
+
+// ─── MCP server (one fresh instance per request — stateless) ─────────────
+
+function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[]): Server {
+    const server = new Server(
+        { name: 'anteros-mcp', version: cfg.version ?? '1.0.0' },
+        { capabilities: { tools: {}, resources: {} } }
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            name: t.name,
+            title: t.name,
+            description: t.description,
+            inputSchema: joiToJsonSchema(t.inputSchema),
+        })),
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = tools.find((t) => t.name === req.params.name);
+        if (!tool) {
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${req.params.name}`);
+        }
+
+        const raw = req.params.arguments ?? {};
+        const { error, value } = tool.inputSchema.validate(raw, { allowUnknown: false });
+        if (error) {
+            return {
+                content: [{ type: 'text' as const, text: `Invalid arguments: ${error.message}` }],
+                isError: true,
+            };
+        }
+
+        const rest = new useRest({ tenant_id: tenantId });
+        try {
+            const result = await tool.exec({ c: undefined as any, rest, args: value });
+            if (result && Array.isArray(result.content)) return result;
+            const text = typeof result === 'string' ? result : JSON.stringify(result);
+            return { content: [{ type: 'text' as const, text }] };
+        } catch (err: any) {
+            return {
+                content: [{ type: 'text' as const, text: `Error: ${err?.message ?? 'unknown'}` }],
+                isError: true,
+            };
+        }
+    });
+
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: resources
+            .filter((r) => !r.uri.includes('{')) // static only; templates are listed separately
+            .map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+    }));
+
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+        resourceTemplates: resources
+            .filter((r) => r.uri.includes('{'))
+            .map((r) => ({
+                uriTemplate: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+    }));
+
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const uri = req.params.uri;
+        const matched = matchUri(uri, resources);
+        if (!matched) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown resource URI: ${uri}`);
+        }
+
+        const rest = new useRest({ tenant_id: tenantId });
+        try {
+            const result = await matched.resource.read({
+                c: undefined as any,
+                rest,
+                params: matched.params,
+                uri,
+            });
+            return result;
+        } catch (err: any) {
+            throw new McpError(ErrorCode.InternalError, `Failed to read resource: ${err?.message ?? 'unknown'}`);
+        }
+    });
+
+    return server;
+}
+
+/**
+ * Expose each tenant's MCP tools & resources over the Model Context Protocol
+ * at `GET/POST /mcp/:tenant_id` (Streamable HTTP transport — works with
+ * Claude, Cursor, VS Code, and any MCP client).
+ */
+export function initializeMcp(app: Hono<{ Variables: HonoVariables }>) {
+    const toolsByTenant = new Map<string, McpTool[]>();
+    for (const tool of cfg.mcpTools ?? []) {
+        const list = toolsByTenant.get(tool._tenant_ ?? '') ?? [];
+        list.push(tool);
+        toolsByTenant.set(tool._tenant_ ?? '', list);
+    }
+    const resourcesByTenant = new Map<string, McpResource[]>();
+    for (const resource of cfg.mcpResources ?? []) {
+        const list = resourcesByTenant.get(resource._tenant_ ?? '') ?? [];
+        list.push(resource);
+        resourcesByTenant.set(resource._tenant_ ?? '', list);
+    }
+
+    app.all('/mcp/:tenant_id', async (c: Context<{ Variables: HonoVariables }>) => {
+        const tenantId = c.req.param('tenant_id') ?? '';
+        const tools = toolsByTenant.get(tenantId) ?? [];
+        const resources = resourcesByTenant.get(tenantId) ?? [];
+        if (!tools.length && !resources.length) {
+            return c.json({ error: `No MCP tools or resources for tenant '${tenantId}'` }, 404);
+        }
+
+        const server = buildServer(tenantId, tools, resources);
+        const transport = new StreamableHTTPTransport();
+        await server.connect(transport);
+        return transport.handleRequest(c);
+    });
+}

package/server/metrics.ts

@@ -0,0 +1,110 @@
+import type { Server } from "bun";
+import os from "node:os";
+
+// ─── Zero-dependency runtime metrics (memory, CPU, requests) ─────────────────
+
+export type MetricsSnapshot = {
+  pid: number;
+  startedAt: number;
+  uptime: number;
+  env: string;
+  connections: number;
+  pendingRequests: number;
+  pendingWebSockets: number;
+  requests: {
+    total: number;
+    active: number;
+    errors: number;
+    byMethod: Record<string, number>;
+    byStatus: Record<string, number>;
+  };
+  memory: {
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+  };
+  cpu: {
+    /** % of a single core over the last sample window (0..100*cores) */
+    percent: number;
+    cores: number;
+    user: number;
+    system: number;
+  };
+};
+
+let serverRef: Server<any> | null = null;
+
+const startedAt = Date.now();
+let totalRequests = 0;
+let totalErrors = 0;
+const byMethod = new Map<string, number>();
+const byStatus = new Map<string, number>();
+
+let lastCpu = process.cpuUsage();
+let lastCpuAt = Date.now();
+
+/** Attach the running Bun server (used for connection / pending request counts). */
+export function registerMetrics(server: Server<any>) {
+  serverRef = server;
+}
+
+/** Count a finished request (call once the response is resolved). */
+export function trackRequest(req: Request, res: Response) {
+  totalRequests++;
+  const method = req.method || 'UNKNOWN';
+  byMethod.set(method, (byMethod.get(method) ?? 0) + 1);
+  const status = String(res.status);
+  byStatus.set(status, (byStatus.get(status) ?? 0) + 1);
+  if (res.status >= 500) totalErrors++;
+}
+
+/** Count an error that did not produce a response. */
+export function trackError() {
+  totalErrors++;
+}
+
+/** Build a serializable metrics snapshot for the current process. */
+export function getMetrics(): MetricsSnapshot {
+  const mem = process.memoryUsage();
+  const now = Date.now();
+  const cpu = process.cpuUsage();
+
+  const user = cpu.user - lastCpu.user;
+  const system = cpu.system - lastCpu.system;
+  const elapsedMs = Math.max(1, now - lastCpuAt);
+  const cores = Math.max(1, os.availableParallelism());
+  lastCpu = cpu;
+  lastCpuAt = now;
+
+  const cpuPercent = Math.min(100 * cores, ((user + system) / 1000 / elapsedMs) * 100);
+
+  return {
+    pid: process.pid,
+    startedAt,
+    uptime: Math.floor((now - startedAt) / 1000),
+    env: process.env.NODE_ENV || Bun.env.NODE_ENV || 'dev',
+    connections: serverRef?.pendingWebSockets ?? 0,
+    pendingRequests: serverRef?.pendingRequests ?? 0,
+    pendingWebSockets: serverRef?.pendingWebSockets ?? 0,
+    requests: {
+      total: totalRequests,
+      active: serverRef?.pendingRequests ?? 0,
+      errors: totalErrors,
+      byMethod: Object.fromEntries(byMethod),
+      byStatus: Object.fromEntries(byStatus),
+    },
+    memory: {
+      rss: mem.rss,
+      heapUsed: mem.heapUsed,
+      heapTotal: mem.heapTotal,
+      external: mem.external,
+    },
+    cpu: {
+      percent: Math.round(cpuPercent * 10) / 10,
+      cores,
+      user,
+      system,
+    },
+  };
+}

package/server/security.ts

@@ -1,5 +1,6 @@
 import type { Context } from "hono";
 import { getConnInfo } from "hono/bun";
+import type { ConnInfo } from "hono/conninfo";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -96,15 +97,18 @@ export function createRedisStore(redis: RedisClient): RateLimitStore {
 // ─── Default key generator ───────────────────────────────────────────────────
 
 function defaultKeyGenerator(c: Context): string {
-  const connInfo = getConnInfo(c);
-  const ip =
-    connInfo.remote.address ??
-    c.req.header("CF-Connecting-IP") ??
-    c.req.header("True-Client-IP") ??
-    c.req.header("X-Forwarded-For") ??
-    "unknown";
-
-  return `rn:rl:${ip}`;
+  // Prefer the client IP resolved once by the app middleware (trustProxy-aware).
+  const clientIp = (c as any).get('clientIp') as string | undefined;
+  if (clientIp) return `rn:rl:${clientIp}`;
+
+  // Fallback: real socket address only (no spoofable proxy headers)
+  let connInfo: ConnInfo | null = null;
+  try {
+    connInfo = getConnInfo(c);
+  } catch {
+    // getConnInfo throws outside a real Bun.serve (e.g. unit tests)
+  }
+  return `rn:rl:${connInfo?.remote.address ?? 'unknown'}`;
 }
 
 // ─── Middleware ──────────────────────────────────────────────────────────────

package/tests/cache.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Cache, useMemoryCache, useFilesystemCache } from "../utils/cache";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("Cache (memory)", () => {
+    let c: Cache;
+
+    beforeEach(() => {
+        c = useMemoryCache();
+    });
+
+    it("set + get round-trip", async () => {
+        await c.set({ key: "k", value: { id: 1 }, ttl: "5m" });
+        expect(await c.get({ key: "k" })).toEqual({ id: 1 });
+    });
+
+    it("setForever never expires", async () => {
+        await c.setForever({ key: "cfg", value: { theme: "dark" } });
+        expect(await c.get({ key: "cfg" })).toEqual({ theme: "dark" });
+    });
+
+    it("get returns null on miss", async () => {
+        expect(await c.get({ key: "nope" })).toBeUndefined();
+    });
+
+    it("has / missing", async () => {
+        await c.set({ key: "a", value: 1 });
+        expect(await c.has({ key: "a" })).toBe(true);
+        expect(await c.missing({ key: "a" })).toBe(false);
+        expect(await c.missing({ key: "b" })).toBe(true);
+    });
+
+    it("ttl expiry (ms)", async () => {
+        await c.set({ key: "x", value: 1, ttl: 50 });
+        expect(await c.get({ key: "x" })).toBe(1);
+        await sleep(80);
+        expect(await c.get({ key: "x" })).toBeUndefined();
+    });
+
+    it("getOrSet uses factory and caches", async () => {
+        let calls = 0;
+        const factory = async () => {
+            calls++;
+            return { n: calls };
+        };
+        expect(await c.getOrSet({ key: "g", factory })).toEqual({ n: 1 });
+        expect(await c.getOrSet({ key: "g", factory })).toEqual({ n: 1 });
+        expect(calls).toBe(1);
+    });
+
+    it("getOrSetForever", async () => {
+        const value = await c.getOrSetForever({ key: "f", factory: () => 42 });
+        expect(value).toBe(42);
+        expect(await c.get({ key: "f" })).toBe(42);
+    });
+
+    it("delete removes entry", async () => {
+        await c.set({ key: "d", value: 1 });
+        await c.delete({ key: "d" });
+        expect(await c.get({ key: "d" })).toBeUndefined();
+    });
+
+    it("deleteMany removes several keys", async () => {
+        await c.set({ key: "d1", value: 1 });
+        await c.set({ key: "d2", value: 2 });
+        await c.deleteMany({ keys: ["d1", "d2"] });
+        expect(await c.missing({ key: "d1" })).toBe(true);
+        expect(await c.missing({ key: "d2" })).toBe(true);
+    });
+
+    it("pull returns and removes", async () => {
+        await c.set({ key: "p", value: 7 });
+        expect(await c.pull("p")).toBe(7);
+        expect(await c.get({ key: "p" })).toBeUndefined();
+    });
+
+    it("clear empties everything", async () => {
+        await c.set({ key: "a", value: 1 });
+        await c.set({ key: "b", value: 2 });
+        await c.clear();
+        expect(await c.get({ key: "a" })).toBeUndefined();
+        expect(await c.get({ key: "b" })).toBeUndefined();
+    });
+
+    it("getOrSet recovers after ttl expiry (grace accepted)", async () => {
+        // miss → factory
+        const v1 = await c.getOrSet({ key: "e", factory: () => "fresh", ttl: 30, grace: 500 });
+        expect(v1).toBe("fresh");
+
+        await sleep(60); // past ttl
+        expect(await c.get({ key: "e" })).toBeUndefined(); // expired
+
+        // getOrSet re-runs the factory after expiry
+        const v2 = await c.getOrSet({ key: "e", factory: () => "fresh2" });
+        expect(v2).toBe("fresh2");
+    });
+
+    it("namespace groups keys", async () => {
+        const users = c.namespace("users");
+        await users.set({ key: "1", value: { name: "John" }, ttl: "5m" });
+        await users.set({ key: "2", value: { name: "Jane" } });
+        expect(await users.get({ key: "1" })).toEqual({ name: "John" });
+        expect(await c.get({ key: "1" })).toBeUndefined(); // not in root
+        await users.clear();
+        expect(await users.missing({ key: "1" })).toBe(true);
+        expect(await users.missing({ key: "2" })).toBe(true);
+    });
+});
+
+describe("Cache (filesystem)", () => {
+    it("persists across instances", async () => {
+        const dir = "/tmp/anteros-cache-test";
+        const a = useFilesystemCache({ directory: dir });
+        await a.set({ key: "persist", value: { ok: true }, ttl: "10m" });
+        await a.disconnect();
+
+        const b = useFilesystemCache({ directory: dir });
+        expect(await b.get({ key: "persist" })).toEqual({ ok: true });
+        await b.delete({ key: "persist" });
+        expect(await b.get({ key: "persist" })).toBeUndefined();
+        await b.disconnect();
+    });
+});

package/tests/crypto.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "bun:test";
+import { useSymCrypt, useAsymCrypt } from "../utils/crypto";
+
+describe("crypto — symmetric AES-256-GCM", () => {
+    it("round-trips a string", async () => {
+        const c = useSymCrypt({ secret: "test-secret" });
+        const enc = await c.encrypt("hello world");
+        const dec = await c.decrypt(enc);
+        expect(dec).toBe("hello world");
+    });
+
+    it("round-trips an object (parseJson)", async () => {
+        const c = useSymCrypt({ secret: "s" });
+        const enc = await c.encrypt({ a: 1, b: "x", nested: { ok: true } });
+        const dec = await c.decrypt<{ a: number; b: string; nested: { ok: boolean } }>(enc, true);
+        expect(dec).toEqual({ a: 1, b: "x", nested: { ok: true } });
+    });
+
+    it("produces different ciphertexts each time (random IV)", async () => {
+        const c = useSymCrypt({ secret: "s" });
+        const a = await c.encrypt("same");
+        const b = await c.encrypt("same");
+        expect(a).not.toBe(b);
+    });
+
+    it("rejects tampered ciphertext (AES-GCM tag)", async () => {
+        const c = useSymCrypt({ secret: "s" });
+        const enc = await c.encrypt("data");
+        const buf = Buffer.from(enc, "base64");
+        buf[buf.length - 1]! ^= 0xff; // corrupt the tag
+        await expect(c.decrypt(buf.toString("base64"))).rejects.toThrow();
+    });
+
+    it("cannot decrypt with a different secret", async () => {
+        const c1 = useSymCrypt({ secret: "one" });
+        const c2 = useSymCrypt({ secret: "two" });
+        const enc = await c1.encrypt("secret");
+        await expect(c2.decrypt(enc)).rejects.toThrow();
+    });
+
+    it("binds ciphertext to its context via AAD (substitution-proof)", async () => {
+        const c = useSymCrypt({ secret: "s" });
+        // Alice encrypts with her context
+        const enc = await c.encrypt({ apiKey: "sk-alice" }, "users:alice:apiKey");
+
+        // Same context → OK
+        const dec = await c.decrypt<{ apiKey: string }>(enc, true, "users:alice:apiKey");
+        expect(dec.apiKey).toBe("sk-alice");
+
+        // Swapped into Bob's context (substitution) → rejected
+        await expect(c.decrypt(enc, true, "users:bob:apiKey")).rejects.toThrow();
+        // Missing context → rejected
+        await expect(c.decrypt(enc, true)).rejects.toThrow();
+    });
+
+    it("rejects truncated ciphertext with a clear error", async () => {
+        const c = useSymCrypt({ secret: "s" });
+        await expect(c.decrypt("YWJjZA==")).rejects.toThrow();
+    });
+});
+
+describe("crypto — asymmetric RSA-OAEP envelope", () => {
+    it("round-trips via exportPrivateKey / reuse", async () => {
+        const a = useAsymCrypt();
+        const enc = await a.encrypt({ secret: 42, list: [1, 2] });
+        const priv = await a.exportPrivateKey();
+        const b = useAsymCrypt({ privateKey: priv });
+        const dec = await b.decrypt<{ secret: number; list: number[] }>(enc, true);
+        expect(dec).toEqual({ secret: 42, list: [1, 2] });
+    });
+
+    it("encrypts with an external public key and decrypts with the private key", async () => {
+        const a = useAsymCrypt();
+        const pubJwk = await a.exportPublicKey();
+        const pubKey = await a.importPublicKey(pubJwk);
+        const enc = await a.encrypt("external-msg", pubKey);
+        const dec = await a.decrypt(enc);
+        expect(dec).toBe("external-msg");
+    });
+
+    it("rejects tampered ciphertext", async () => {
+        const a = useAsymCrypt();
+        const enc = await a.encrypt("data");
+        const buf = Buffer.from(enc, "base64");
+        buf[0]! ^= 0xff; // corrupt the wrapped key
+        await expect(a.decrypt(buf.toString("base64"))).rejects.toThrow();
+    });
+
+    it("binds ciphertext to its context via AAD (asym)", async () => {
+        const a = useAsymCrypt();
+        const enc = await a.encrypt({ doc: "sensitive" }, undefined, "tenant:acme:record:42");
+
+        const ok = await a.decrypt<{ doc: string }>(enc, true, "tenant:acme:record:42");
+        expect(ok.doc).toBe("sensitive");
+
+        // Wrong context → rejected
+        await expect(a.decrypt(enc, true, "tenant:acme:record:43")).rejects.toThrow();
+        // Missing context → rejected
+        await expect(a.decrypt(enc, true)).rejects.toThrow();
+    });
+});

package/tests/fixtures/heavy/collections/items.model.ts

@@ -0,0 +1,8 @@
+export default {
+    _isCollection_: true,
+    slug: 'items',
+    type: 'document',
+    fields: [
+        { name: 'name', type: 'string', required: true },
+    ],
+};

package/tests/fixtures/heavy/scripts/heavy-import.run.ts

@@ -0,0 +1,14 @@
+export default {
+    _isScript_: true,
+    enabled: true,
+    heavy: true,
+    exec: async ({ rest, progress }: any) => {
+        const items = Array.from({ length: 10 }, (_, i) => ({ name: `item-${i}` }));
+        await rest.insertMany('items', items);
+        progress?.(50, { inserted: 10 });
+
+        await rest.insertMany('items', items.map((it) => ({ ...it, name: it.name + '-b' })));
+        progress?.(100, { inserted: 20 });
+        return { ok: true, total: 20 };
+    },
+};

package/tests/fixtures/mcp-tenant/mcp/resources/orders.summary.resource.ts

@@ -0,0 +1,17 @@
+import { define } from "../../../../../index";
+
+// Static resource — fixed URI
+export default define.McpResource({
+    name: "orders-summary",
+    description: "Summary of orders",
+    uri: "orders://summary",
+    read: async ({ params }) => {
+        return {
+            contents: [{
+                uri: "orders://summary",
+                mimeType: "application/json",
+                text: JSON.stringify({ total: 42, pending: 7, params }),
+            }],
+        };
+    },
+});

package/tests/fixtures/mcp-tenant/mcp/resources/users.id.resource.ts

@@ -0,0 +1,18 @@
+import { define, v } from "../../../../../index";
+
+// Template resource — dynamic URI (params extracted from the URI)
+export default define.McpResource({
+    name: "users-by-id",
+    description: "Fetch a user by id",
+    uri: "users://{id}",
+    mimeType: "application/json",
+    read: async ({ params, uri }) => {
+        return {
+            contents: [{
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({ id: params.id, name: `User ${params.id}` }),
+            }],
+        };
+    },
+});

package/tests/fixtures/mcp-tenant/mcp/tools/badge.tool.ts

@@ -0,0 +1,16 @@
+import { define, v } from "../../../../../index";
+
+export default define.McpTool({
+    name: "badge",
+    description: "Returns an image content block (protocol passthrough)",
+    inputSchema: v.object({}),
+    exec: async () => {
+        return {
+            content: [{
+                type: "image",
+                data: "aGVsbG8=", // "hello" base64
+                mimeType: "image/png",
+            }],
+        };
+    },
+});