@cleocode/lafs-protocol 0.1.1 → 1.0.0

package/dist/examples/mcp-lafs-server.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * MCP-LAFS Server Example
+ *
+ * A working MCP server that wraps all tool responses in LAFS-compliant envelopes.
+ * Demonstrates how LAFS complements MCP by adding structured metadata and budget enforcement.
+ *
+ * Usage: npx ts-node examples/mcp-lafs-server.ts
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { wrapMCPResult } from "../src/mcpAdapter.js";
+const simulatedDatabase = new Map([
+    ["1", { id: "1", name: "Product A", value: 100, createdAt: new Date().toISOString() }],
+    ["2", { id: "2", name: "Product B", value: 200, createdAt: new Date().toISOString() }],
+    ["3", { id: "3", name: "Product C", value: 300, createdAt: new Date().toISOString() }],
+]);
+// Tool definitions
+const TOOLS = [
+    {
+        name: "weather",
+        description: "Get current weather for a location",
+        inputSchema: {
+            type: "object",
+            properties: {
+                location: {
+                    type: "string",
+                    description: "City name or coordinates",
+                },
+                units: {
+                    type: "string",
+                    enum: ["celsius", "fahrenheit"],
+                    description: "Temperature units",
+                    default: "celsius",
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 10000,
+                },
+            },
+            required: ["location"],
+        },
+    },
+    {
+        name: "calculator",
+        description: "Perform mathematical calculations",
+        inputSchema: {
+            type: "object",
+            properties: {
+                operation: {
+                    type: "string",
+                    enum: ["add", "subtract", "multiply", "divide", "power", "sqrt"],
+                    description: "Mathematical operation to perform",
+                },
+                a: {
+                    type: "number",
+                    description: "First operand",
+                },
+                b: {
+                    type: "number",
+                    description: "Second operand (not needed for sqrt)",
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 1000,
+                },
+            },
+            required: ["operation", "a"],
+        },
+    },
+    {
+        name: "database_query",
+        description: "Query the simulated database",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["get", "list", "search"],
+                    description: "Query action to perform",
+                },
+                id: {
+                    type: "string",
+                    description: "Record ID (for get action)",
+                },
+                query: {
+                    type: "string",
+                    description: "Search query (for search action)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum results to return",
+                    default: 10,
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 5000,
+                },
+            },
+            required: ["action"],
+        },
+    },
+];
+// Weather simulation
+async function getWeather(location, units) {
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    // Generate deterministic but varied weather based on location
+    const hash = location.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
+    const conditions = ["sunny", "cloudy", "rainy", "partly cloudy", "clear"];
+    const condition = conditions[hash % conditions.length];
+    // Temperature based on condition and some randomness
+    let baseTemp = 20; // celsius
+    if (condition === "sunny")
+        baseTemp = 25;
+    if (condition === "rainy")
+        baseTemp = 15;
+    if (condition === "clear")
+        baseTemp = 22;
+    const tempC = baseTemp + (hash % 10) - 5;
+    const tempF = Math.round((tempC * 9) / 5 + 32);
+    return {
+        location,
+        temperature: units === "fahrenheit" ? tempF : tempC,
+        temperatureUnit: units,
+        conditions: condition,
+        humidity: 40 + (hash % 50),
+        windSpeed: 5 + (hash % 20),
+        windUnit: "km/h",
+        forecast: [
+            { day: "Today", high: tempC + 2, low: tempC - 3, condition },
+            { day: "Tomorrow", high: tempC + 1, low: tempC - 4, condition: conditions[(hash + 1) % conditions.length] },
+            { day: "Day after", high: tempC + 3, low: tempC - 2, condition: conditions[(hash + 2) % conditions.length] },
+        ],
+    };
+}
+// Calculator implementation
+function calculate(operation, a, b) {
+    let result;
+    let expression;
+    switch (operation) {
+        case "add":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for addition");
+            result = a + b;
+            expression = `${a} + ${b}`;
+            break;
+        case "subtract":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for subtraction");
+            result = a - b;
+            expression = `${a} - ${b}`;
+            break;
+        case "multiply":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for multiplication");
+            result = a * b;
+            expression = `${a} * ${b}`;
+            break;
+        case "divide":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for division");
+            if (b === 0)
+                throw new Error("Cannot divide by zero");
+            result = a / b;
+            expression = `${a} / ${b}`;
+            break;
+        case "power":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for power operation");
+            result = Math.pow(a, b);
+            expression = `${a} ^ ${b}`;
+            break;
+        case "sqrt":
+            if (a < 0)
+                throw new Error("Cannot calculate square root of negative number");
+            result = Math.sqrt(a);
+            expression = `sqrt(${a})`;
+            break;
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+    return {
+        operation,
+        expression,
+        operands: { a, b },
+        result,
+        resultType: Number.isInteger(result) ? "integer" : "float",
+    };
+}
+// Database operations
+function databaseQuery(action, id, query, limit) {
+    switch (action) {
+        case "get": {
+            if (!id) {
+                throw new Error("ID required for get action");
+            }
+            const record = simulatedDatabase.get(id);
+            if (!record) {
+                throw new Error(`Record with ID '${id}' not found`);
+            }
+            return {
+                action,
+                record,
+                found: true,
+            };
+        }
+        case "list": {
+            const records = Array.from(simulatedDatabase.values()).slice(0, limit ?? 10);
+            return {
+                action,
+                records,
+                count: records.length,
+                total: simulatedDatabase.size,
+            };
+        }
+        case "search": {
+            if (!query) {
+                throw new Error("Query required for search action");
+            }
+            const queryLower = query.toLowerCase();
+            const records = Array.from(simulatedDatabase.values())
+                .filter((r) => r.name.toLowerCase().includes(queryLower))
+                .slice(0, limit ?? 10);
+            return {
+                action,
+                query,
+                records,
+                count: records.length,
+                total: simulatedDatabase.size,
+            };
+        }
+        default:
+            throw new Error(`Unknown action: ${action}`);
+    }
+}
+// Create MCP server
+const server = new Server({
+    name: "lafs-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: TOOLS,
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const budget = typeof args?._budget === "number" ? args._budget : undefined;
+    try {
+        let result;
+        switch (name) {
+            case "weather": {
+                const location = String(args?.location ?? "");
+                const units = String(args?.units ?? "celsius");
+                if (!location) {
+                    throw new Error("Location is required");
+                }
+                result = await getWeather(location, units);
+                break;
+            }
+            case "calculator": {
+                const operation = String(args?.operation ?? "");
+                const a = Number(args?.a);
+                const b = args?.b !== undefined ? Number(args?.b) : undefined;
+                if (!operation || Number.isNaN(a)) {
+                    throw new Error("Operation and operand 'a' are required");
+                }
+                result = calculate(operation, a, b);
+                break;
+            }
+            case "database_query": {
+                const action = String(args?.action ?? "");
+                const id = args?.id !== undefined ? String(args?.id) : undefined;
+                const query = args?.query !== undefined ? String(args?.query) : undefined;
+                const limit = args?.limit !== undefined ? Number(args?.limit) : undefined;
+                if (!action) {
+                    throw new Error("Action is required");
+                }
+                result = databaseQuery(action, id, query, limit);
+                break;
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        // Create MCP result
+        const mcpResult = {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: false,
+        };
+        // Wrap in LAFS envelope
+        const envelope = wrapMCPResult(mcpResult, `tools/${name}`, budget);
+        // Return the LAFS envelope as text content
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(envelope),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        // Create error MCP result
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const mcpResult = {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessage,
+                },
+            ],
+            isError: true,
+        };
+        // Wrap in LAFS error envelope
+        const envelope = wrapMCPResult(mcpResult, `tools/${name}`, budget);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(envelope),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    console.error("LAFS-MCP Server starting...");
+    console.error("Available tools: weather, calculator, database_query");
+    console.error("All responses are wrapped in LAFS-compliant envelopes");
+    await server.connect(transport);
+    console.error("LAFS-MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/schemas/v1/envelope.schema.json

@@ -3,14 +3,11 @@
     "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
     "title": "LAFS Envelope v1",
     "type": "object",
-    "additionalProperties": false,
     "required": [
         "$schema",
         "_meta",
         "success",
-        "result",
-        "error",
-        "page"
+        "result"
     ],
     "properties": {
         "$schema": {
@@ -62,11 +59,28 @@
                     "type": "boolean"
                 },
                 "mvi": {
-                    "type": "boolean"
+                    "type": "string",
+                    "enum": ["minimal", "standard", "full", "custom"],
+                    "description": "Disclosure level: minimal (MVI only), standard (common fields), full (all fields), custom (per _fields parameter)"
                 },
                 "contextVersion": {
                     "type": "integer",
                     "minimum": 0
+                },
+                "warnings": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "code": { "type": "string", "description": "Warning identifier (e.g., DEPRECATED_FIELD)" },
+                            "message": { "type": "string", "description": "Human-readable warning" },
+                            "deprecated": { "type": "string", "description": "The deprecated feature or field name" },
+                            "replacement": { "type": "string", "description": "Suggested replacement, if any" },
+                            "removeBy": { "type": "string", "description": "Version when the deprecated feature will be removed" }
+                        },
+                        "required": ["code", "message"]
+                    },
+                    "description": "Non-fatal advisory warnings (deprecations, migration hints)"
                 }
             }
         },
@@ -127,14 +141,7 @@
         "page": {
             "type": ["object", "null"],
             "additionalProperties": false,
-            "required": [
-                "mode",
-                "limit",
-                "offset",
-                "nextCursor",
-                "hasMore",
-                "total"
-            ],
+            "required": ["mode"],
             "properties": {
                 "mode": {
                     "type": "string",
@@ -160,7 +167,61 @@
                     "type": ["integer", "null"],
                     "minimum": 0
                 }
-            }
+            },
+            "allOf": [
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "cursor" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode", "nextCursor", "hasMore"],
+                        "properties": {
+                            "mode": true,
+                            "nextCursor": true,
+                            "hasMore": true,
+                            "limit": true,
+                            "total": true
+                        }
+                    }
+                },
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "offset" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode", "limit", "offset", "hasMore"],
+                        "properties": {
+                            "mode": true,
+                            "limit": true,
+                            "offset": true,
+                            "hasMore": true,
+                            "total": true
+                        }
+                    }
+                },
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "none" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode"],
+                        "properties": {
+                            "mode": true
+                        }
+                    }
+                }
+            ]
+        },
+        "_extensions": {
+            "type": "object",
+            "description": "Vendor extensions. Keys SHOULD use x- prefix (e.g., x-myvendor-trace-id).",
+            "additionalProperties": true
         }
     },
     "allOf": [
@@ -183,11 +244,39 @@
                 }
             },
             "then": {
+                "required": ["error"],
                 "properties": {
                     "result": { "type": "null" },
                     "error": { "type": "object" }
                 }
             }
+        },
+        {
+            "if": {
+                "properties": {
+                    "_meta": {
+                        "type": "object",
+                        "properties": {
+                            "strict": { "const": true }
+                        }
+                    }
+                }
+            },
+            "then": {
+                "additionalProperties": false,
+                "properties": {
+                    "$schema": true,
+                    "_meta": true,
+                    "success": true,
+                    "result": true,
+                    "error": true,
+                    "page": true,
+                    "_extensions": true
+                }
+            },
+            "else": {
+                "additionalProperties": true
+            }
         }
     ]
 }

package/dist/schemas/v1/error-registry.json

@@ -1,5 +1,5 @@
 {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$schema": "http://json-schema.org/draft-07/schema#",
     "version": "1.0.0",
     "codes": [
         {
@@ -91,6 +91,24 @@
             "httpStatus": 426,
             "grpcStatus": "FAILED_PRECONDITION",
             "cliExit": 10
+        },
+        {
+            "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+            "category": "VALIDATION",
+            "description": "Unrecognized expansion field in _expand parameter",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2
+        },
+        {
+            "code": "E_MVI_BUDGET_EXCEEDED",
+            "category": "VALIDATION",
+            "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+            "retryable": false,
+            "httpStatus": 413,
+            "grpcStatus": "RESOURCE_EXHAUSTED",
+            "cliExit": 2
         }
     ]
 }

package/dist/src/budgetEnforcement.d.ts

@@ -0,0 +1,84 @@
+/**
+ * LAFS Budget Enforcement
+ *
+ * Middleware for enforcing MVI (Minimal Viable Interface) token budgets on LAFS envelopes.
+ * Provides budget checking, truncation, and error generation for exceeded budgets.
+ */
+import type { LAFSEnvelope } from "./types.js";
+import type { BudgetEnforcementOptions, TokenEstimate, BudgetEnforcementResult } from "./types.js";
+import { TokenEstimator } from "./tokenEstimator.js";
+/**
+ * Budget exceeded error code from LAFS error registry
+ */
+declare const BUDGET_EXCEEDED_CODE = "E_MVI_BUDGET_EXCEEDED";
+/**
+ * Apply budget enforcement to an envelope.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Enforce result with potentially modified envelope
+ */
+export declare function applyBudgetEnforcement(envelope: LAFSEnvelope, budget: number, options?: BudgetEnforcementOptions): BudgetEnforcementResult;
+/**
+ * Type for middleware function
+ */
+type EnvelopeMiddleware = (envelope: LAFSEnvelope, next: () => LAFSEnvelope | Promise<LAFSEnvelope>) => Promise<LAFSEnvelope> | LAFSEnvelope;
+/**
+ * Create a budget enforcement middleware function.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget
+ *
+ * @example
+ * ```typescript
+ * const middleware = withBudget(1000, { truncateOnExceed: true });
+ * const result = await middleware(envelope, async () => nextEnvelope);
+ * ```
+ */
+export declare function withBudget(budget: number, options?: BudgetEnforcementOptions): EnvelopeMiddleware;
+/**
+ * Check if an envelope has exceeded its budget without modifying it.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @returns Budget check result
+ */
+export declare function checkBudget(envelope: LAFSEnvelope, budget: number): {
+    exceeded: boolean;
+    estimated: number;
+    remaining: number;
+};
+/**
+ * Synchronous version of withBudget for non-async contexts.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget synchronously
+ */
+export declare function withBudgetSync(budget: number, options?: BudgetEnforcementOptions): (envelope: LAFSEnvelope, next: () => LAFSEnvelope) => LAFSEnvelope;
+/**
+ * Higher-order function that wraps a handler with budget enforcement.
+ *
+ * @param handler - The handler function to wrap
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Wrapped handler with budget enforcement
+ *
+ * @example
+ * ```typescript
+ * const myHandler = async (request: Request) => ({ success: true, result: { data } });
+ * const budgetedHandler = wrapWithBudget(myHandler, 1000, { truncateOnExceed: true });
+ * const result = await budgetedHandler(request);
+ * ```
+ */
+export declare function wrapWithBudget<TArgs extends unknown[], TResult extends LAFSEnvelope>(handler: (...args: TArgs) => TResult | Promise<TResult>, budget: number, options?: BudgetEnforcementOptions): (...args: TArgs) => Promise<LAFSEnvelope>;
+/**
+ * Compose multiple middleware functions into a single middleware.
+ * Middleware is executed in order (left to right).
+ */
+export declare function composeMiddleware(...middlewares: EnvelopeMiddleware[]): EnvelopeMiddleware;
+export type { BudgetEnforcementOptions, TokenEstimate, BudgetEnforcementResult };
+export { TokenEstimator };
+export { BUDGET_EXCEEDED_CODE };