@criterionx/mcp 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomas Maritano
+
+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

@@ -0,0 +1,199 @@
+# @criterionx/mcp
+
+MCP (Model Context Protocol) server for Criterion decisions. Exposes business rules as MCP tools for use with LLM applications like Claude Desktop.
+
+## Installation
+
+```bash
+npm install @criterionx/mcp @criterionx/core zod
+```
+
+## Quick Start
+
+```typescript
+import { createMcpServer } from "@criterionx/mcp";
+import { defineDecision } from "@criterionx/core";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Define a decision
+const pricingDecision = defineDecision({
+  id: "pricing-tier",
+  version: "1.0.0",
+  inputSchema: z.object({ revenue: z.number() }),
+  outputSchema: z.object({ tier: z.string(), discount: z.number() }),
+  profileSchema: z.object({
+    tiers: z.array(z.object({ min: z.number(), name: z.string(), discount: z.number() }))
+  }),
+  rules: [
+    {
+      id: "enterprise",
+      when: (ctx, profile) => ctx.revenue >= profile.tiers[2].min,
+      emit: (ctx, profile) => ({ tier: profile.tiers[2].name, discount: profile.tiers[2].discount }),
+      explain: () => "Revenue qualifies for enterprise tier",
+    },
+    {
+      id: "growth",
+      when: (ctx, profile) => ctx.revenue >= profile.tiers[1].min,
+      emit: (ctx, profile) => ({ tier: profile.tiers[1].name, discount: profile.tiers[1].discount }),
+      explain: () => "Revenue qualifies for growth tier",
+    },
+    {
+      id: "starter",
+      when: () => true,
+      emit: (ctx, profile) => ({ tier: profile.tiers[0].name, discount: profile.tiers[0].discount }),
+      explain: () => "Default starter tier",
+    },
+  ],
+});
+
+// Create MCP server
+const mcpServer = createMcpServer({
+  name: "my-decisions",
+  decisions: [pricingDecision],
+  profiles: {
+    "pricing-tier": {
+      tiers: [
+        { min: 0, name: "Starter", discount: 0 },
+        { min: 100000, name: "Growth", discount: 10 },
+        { min: 1000000, name: "Enterprise", discount: 25 },
+      ]
+    }
+  }
+});
+
+// Connect via stdio transport
+const transport = new StdioServerTransport();
+await mcpServer.server.connect(transport);
+```
+
+## MCP Tools
+
+The server exposes four MCP tools:
+
+### `list_decisions`
+
+List all registered decisions with their metadata.
+
+**Input:** None
+
+**Output:**
+```json
+{
+  "decisions": [
+    {
+      "id": "pricing-tier",
+      "version": "1.0.0",
+      "description": "Determine pricing tier based on revenue",
+      "rulesCount": 3
+    }
+  ]
+}
+```
+
+### `get_decision_schema`
+
+Get the JSON schemas for a specific decision.
+
+**Input:**
+- `decisionId` (string): The ID of the decision
+
+**Output:**
+```json
+{
+  "id": "pricing-tier",
+  "version": "1.0.0",
+  "inputSchema": { "type": "object", "properties": { "revenue": { "type": "number" } } },
+  "outputSchema": { "type": "object", "properties": { "tier": { "type": "string" } } },
+  "profileSchema": { ... }
+}
+```
+
+### `evaluate_decision`
+
+Evaluate a decision with the given input and optional profile.
+
+**Input:**
+- `decisionId` (string): The ID of the decision to evaluate
+- `input` (object): Input data matching the decision's input schema
+- `profile` (object, optional): Profile to use (overrides default)
+
+**Output:**
+```json
+{
+  "status": "OK",
+  "data": { "tier": "Growth", "discount": 10 },
+  "meta": {
+    "decisionId": "pricing-tier",
+    "decisionVersion": "1.0.0",
+    "matchedRule": "growth",
+    "explanation": "Revenue qualifies for growth tier",
+    "evaluatedRules": [
+      { "ruleId": "enterprise", "matched": false },
+      { "ruleId": "growth", "matched": true, "explanation": "Revenue qualifies for growth tier" }
+    ],
+    "evaluatedAt": "2024-12-29T22:00:00.000Z"
+  }
+}
+```
+
+### `explain_result`
+
+Get a human-readable explanation of a decision result.
+
+**Input:**
+- `result` (object): The evaluation result to explain
+
+**Output:**
+```
+Decision: pricing-tier v1.0.0
+Status: OK
+Matched: growth
+Reason: Revenue qualifies for growth tier
+
+Evaluation trace:
+  ✗ enterprise
+  ✓ growth
+```
+
+## Claude Desktop Configuration
+
+Add to `~/.claude/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "criterion": {
+      "command": "node",
+      "args": ["/path/to/your/criterion-mcp-server.js"]
+    }
+  }
+}
+```
+
+## API Reference
+
+### `createMcpServer(options)`
+
+Create a new Criterion MCP server.
+
+**Options:**
+- `name` (string, optional): Server name exposed to MCP clients
+- `version` (string, optional): Server version
+- `decisions` (Decision[]): Decisions to expose as MCP tools
+- `profiles` (Record<string, unknown>, optional): Default profiles keyed by decision ID
+
+**Returns:** `CriterionMcpServer`
+
+### `CriterionMcpServer`
+
+The MCP server class.
+
+**Properties:**
+- `server`: The underlying MCP server instance (for transport connection)
+- `decisionRegistry`: Map of registered decisions
+- `profileRegistry`: Map of registered profiles
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { Decision } from '@criterionx/core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * MCP Server configuration options
+ */
+interface McpServerOptions {
+    /** Server name exposed to MCP clients */
+    name?: string;
+    /** Server version */
+    version?: string;
+    /** Decisions to expose as MCP tools */
+    decisions: Decision<any, any, any>[];
+    /** Default profiles for decisions (keyed by decision ID) */
+    profiles?: Record<string, unknown>;
+}
+/**
+ * Decision info returned by list_decisions tool
+ */
+interface DecisionListItem {
+    id: string;
+    version: string;
+    description?: string;
+    rulesCount: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Schema response for get_decision_schema tool
+ */
+interface DecisionSchemaResponse {
+    id: string;
+    version: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    profileSchema: Record<string, unknown>;
+}
+/**
+ * Error codes for MCP tool responses
+ */
+type McpErrorCode = "DECISION_NOT_FOUND" | "MISSING_PROFILE" | "EVALUATION_ERROR" | "EXPLAIN_ERROR";
+
+/**
+ * Criterion MCP Server
+ *
+ * Exposes Criterion decisions as MCP tools for use with LLM applications.
+ *
+ * @example
+ * ```typescript
+ * import { createMcpServer } from "@criterionx/mcp";
+ * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ * const mcpServer = createMcpServer({
+ *   decisions: [myDecision],
+ *   profiles: { "my-decision": { threshold: 100 } },
+ * });
+ *
+ * const transport = new StdioServerTransport();
+ * await mcpServer.server.connect(transport);
+ * ```
+ */
+declare class CriterionMcpServer {
+    private mcpServer;
+    private engine;
+    private decisions;
+    private profiles;
+    constructor(options: McpServerOptions);
+    private registerTools;
+    /**
+     * Get the underlying MCP server instance
+     */
+    get server(): McpServer;
+    /**
+     * Get the decision registry (for testing/introspection)
+     */
+    get decisionRegistry(): Map<string, Decision<any, any, any>>;
+    /**
+     * Get the profile registry (for testing/introspection)
+     */
+    get profileRegistry(): Map<string, unknown>;
+}
+/**
+ * Create a new Criterion MCP server
+ *
+ * @example
+ * ```typescript
+ * import { createMcpServer } from "@criterionx/mcp";
+ * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ * const server = createMcpServer({
+ *   decisions: [myDecision],
+ *   profiles: { "my-decision": { threshold: 100 } },
+ * });
+ *
+ * const transport = new StdioServerTransport();
+ * await server.server.connect(transport);
+ * ```
+ */
+declare function createMcpServer(options: McpServerOptions): CriterionMcpServer;
+
+export { CriterionMcpServer, type DecisionListItem, type DecisionSchemaResponse, type McpErrorCode, type McpServerOptions, createMcpServer };

package/dist/index.js

@@ -0,0 +1,241 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import {
+  Engine,
+  extractDecisionSchema
+} from "@criterionx/core";
+var PACKAGE_VERSION = "0.3.3";
+var CriterionMcpServer = class {
+  mcpServer;
+  engine;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  decisions;
+  profiles;
+  constructor(options) {
+    this.mcpServer = new McpServer({
+      name: options.name ?? "criterion-mcp-server",
+      version: options.version ?? PACKAGE_VERSION
+    });
+    this.engine = new Engine();
+    this.decisions = /* @__PURE__ */ new Map();
+    this.profiles = /* @__PURE__ */ new Map();
+    for (const decision of options.decisions) {
+      this.decisions.set(decision.id, decision);
+    }
+    if (options.profiles) {
+      for (const [id, profile] of Object.entries(options.profiles)) {
+        this.profiles.set(id, profile);
+      }
+    }
+    this.registerTools();
+  }
+  registerTools() {
+    this.mcpServer.tool(
+      "list_decisions",
+      "List all registered Criterion decisions with their metadata. Returns decision IDs, versions, descriptions, and rule counts.",
+      {},
+      async () => {
+        const decisions = Array.from(
+          this.decisions.values()
+        ).map((d) => ({
+          id: d.id,
+          version: d.version,
+          description: d.meta?.description,
+          rulesCount: d.rules.length,
+          meta: d.meta
+        }));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ decisions }, null, 2)
+            }
+          ]
+        };
+      }
+    );
+    this.mcpServer.tool(
+      "get_decision_schema",
+      "Get the JSON schemas for a specific decision. Returns input, output, and profile schemas that define the decision's contract.",
+      {
+        decisionId: z.string().describe("The ID of the decision to get schemas for")
+      },
+      async (args) => {
+        const decision = this.decisions.get(args.decisionId);
+        if (!decision) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "DECISION_NOT_FOUND",
+                  message: `Decision not found: ${args.decisionId}`,
+                  availableDecisions: Array.from(this.decisions.keys())
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        const schema = extractDecisionSchema(decision);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(schema, null, 2)
+            }
+          ]
+        };
+      }
+    );
+    this.mcpServer.tool(
+      "evaluate_decision",
+      "Evaluate a Criterion decision with the given input and optional profile. Returns the decision result including status, data, and evaluation metadata with full explainability.",
+      {
+        decisionId: z.string().describe("The ID of the decision to evaluate"),
+        input: z.record(z.unknown()).describe("Input data matching the decision's input schema"),
+        profile: z.record(z.unknown()).optional().describe("Optional profile to use (overrides default profile)")
+      },
+      async (args) => {
+        const decision = this.decisions.get(args.decisionId);
+        if (!decision) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "DECISION_NOT_FOUND",
+                  message: `Decision not found: ${args.decisionId}`,
+                  availableDecisions: Array.from(this.decisions.keys())
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        let profile = args.profile;
+        if (!profile) {
+          profile = this.profiles.get(args.decisionId);
+          if (!profile) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "MISSING_PROFILE",
+                    message: `No profile provided and no default profile for decision: ${args.decisionId}`
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        try {
+          const result = this.engine.run(decision, args.input, { profile });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "EVALUATION_ERROR",
+                  message: err.message
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+    );
+    this.mcpServer.tool(
+      "explain_result",
+      "Get a human-readable explanation of a decision evaluation result. Formats the result metadata, matched rules, and evaluation trace into an easy-to-understand summary.",
+      {
+        result: z.object({
+          status: z.enum(["OK", "NO_MATCH", "INVALID_INPUT", "INVALID_OUTPUT"]),
+          data: z.unknown().nullable(),
+          meta: z.object({
+            decisionId: z.string(),
+            decisionVersion: z.string(),
+            profileId: z.string().optional(),
+            matchedRule: z.string().optional(),
+            evaluatedRules: z.array(
+              z.object({
+                ruleId: z.string(),
+                matched: z.boolean(),
+                explanation: z.string().optional()
+              })
+            ),
+            explanation: z.string(),
+            evaluatedAt: z.string()
+          })
+        }).describe("The evaluation result to explain")
+      },
+      async (args) => {
+        try {
+          const explanation = this.engine.explain(args.result);
+          return {
+            content: [
+              {
+                type: "text",
+                text: explanation
+              }
+            ]
+          };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "EXPLAIN_ERROR",
+                  message: err.message
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+  /**
+   * Get the underlying MCP server instance
+   */
+  get server() {
+    return this.mcpServer;
+  }
+  /**
+   * Get the decision registry (for testing/introspection)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get decisionRegistry() {
+    return this.decisions;
+  }
+  /**
+   * Get the profile registry (for testing/introspection)
+   */
+  get profileRegistry() {
+    return this.profiles;
+  }
+};
+function createMcpServer(options) {
+  return new CriterionMcpServer(options);
+}
+export {
+  CriterionMcpServer,
+  createMcpServer
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@criterionx/mcp",
+  "version": "0.3.3",
+  "description": "MCP server for Criterion decisions - expose business rules as LLM tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "criterion",
+    "decision-engine",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai-tools",
+    "business-rules"
+  ],
+  "author": {
+    "name": "Tomas Maritano",
+    "url": "https://github.com/tomymaritano"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/tomymaritano/criterionx/issues"
+  },
+  "homepage": "https://github.com/tomymaritano/criterionx#readme",
+  "dependencies": {
+    "@criterionx/core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.16",
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}