@usekaval/mcp - npm Package Compare versions

Comparing version 0.2.0 to 0.2.1

dist/server.d.ts.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAkDzD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,GAAG,SAAS,CAiKxD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AA+EzD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,GAAG,SAAS,CAoMxD"}

dist/server.js

 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { KavalError } from "@usekaval/kaval";
 import { z } from "zod";
+const idempotencyKeyInput = z
+    .string()
+    .min(8)
+    .max(200)
+    .regex(/^[\x21-\x7e]+$/)
+    .optional()
+    .describe("reuse the operation key returned by an ambiguous prior attempt; omit for a new operation");
+const RECOVERABLE_API_CODES = new Set([
+    "idempotency_in_progress",
+    "idempotency_resolution_pending",
+    "event_persistence_pending",
+]);
 function json(data) {
@@ -43,4 +55,17 @@ return { content: [{ type: "text", text: JSON.stringify(data) }] };
                 status: e.status,
+                ...(code && RECOVERABLE_API_CODES.has(code) && e.idempotencyKey
+                    ? { idempotency_key: e.idempotencyKey }
+                    : {}),
             });
         }
+        const idempotencyKey = e && typeof e === "object" && "idempotencyKey" in e
+            ? e.idempotencyKey
+            : undefined;
+        if (typeof idempotencyKey === "string") {
+            return toolError({
+                error: "request_ambiguous",
+                message: "retry later with the same idempotency_key",
+                idempotency_key: idempotencyKey,
+            });
+        }
         return toolError({ error: "internal error" });
@@ -55,3 +80,3 @@ }
 export function createMcpServer(client) {
-    const server = new McpServer({ name: "kaval", version: "0.1.2" });
+    const server = new McpServer({ name: "kaval", version: "0.2.1" });
     // THE hero tool: the pre-action gate. Registered first so agents reach for it at the act-moment.
@@ -91,4 +116,5 @@ server.registerTool("currentness_verify", {
                 .describe("speed/depth tier — instant (cache/prior only, no fetch/LLM) · fast (cheap model) · auto (default) · deep (full multi-source + a cited `explanation`). The result echoes `tier`; on deep it adds `explanation` { content, citations, confidence }."),
+            idempotency_key: idempotencyKeyInput,
         },
-    }, async (args) => safe(() => client.verify(args)));
+    }, async ({ idempotency_key, ...args }) => safe(() => client.verify(args, idempotency_key ? { idempotencyKey: idempotency_key } : undefined)));
     server.registerTool("currentness_check", {
@@ -110,4 +136,5 @@ description: "Like currentness_verify but returns the raw freshness gap WITHOUT the act/don't-act decision (status: current | stale | contradicted | unsupported | conflicting | insufficient). Prefer currentness_verify when you're about to act on the belief; use this when you just want the status. If status is not 'current', do not rely on the belief.",
             proof_standard: z.string().optional(),
+            idempotency_key: idempotencyKeyInput,
         },
-    }, async (args) => safe(() => client.check(args)));
+    }, async ({ idempotency_key, ...args }) => safe(() => client.check(args, idempotency_key ? { idempotencyKey: idempotency_key } : undefined)));
     server.registerTool("currentness_extract_and_check", {
@@ -119,4 +146,5 @@ description: "Hand it a paragraph; it finds the checkable factual beliefs itself and re-grounds each. Use when you don't know which facts in some text need checking.",
             freshness_sla: z.string().optional(),
+            idempotency_key: idempotencyKeyInput,
         },
-    }, async (args) => safe(() => client.extractAndCheck(args)));
+    }, async ({ idempotency_key, ...args }) => safe(() => client.extractAndCheck(args, idempotency_key ? { idempotencyKey: idempotency_key } : undefined)));
     server.registerTool("currentness_scan_store", {
@@ -134,4 +162,5 @@ description: "Re-ground a batch of beliefs your system holds on a freshness SLA (self-sweep). Returns a summary by status + the riskiest (stale/contradicted/unsupported) beliefs, plus the `tier` the sweep ran at. Defaults to the `fast` tier — re-`currentness_verify` a flagged belief at `deep` for the cited explanation.",
                 .describe("speed/depth tier for the whole sweep (default fast)"),
+            idempotency_key: idempotencyKeyInput,
         },
-    }, async (args) => safe(() => client.scanStore(args)));
+    }, async ({ idempotency_key, ...args }) => safe(() => client.scanStore(args, idempotency_key ? { idempotencyKey: idempotency_key } : undefined)));
     server.registerTool("currentness_monitor", {
@@ -157,4 +186,5 @@ description: "Sweep a batch of beliefs like currentness_scan_store, then POST the NEWLY-risky ones to a `webhook` (server-side delivery). Pass the `state` from the previous run's result to deliver only beliefs that became risky since then (a still-stale belief isn't re-sent each sweep). Run on a schedule (cron) for continuous drift monitoring. The result echoes the `tier` it ran at and the `state` to carry into the next run.",
                 .describe("the `state` from the previous run → deliver only newly-risky beliefs"),
+            idempotency_key: idempotencyKeyInput,
         },
-    }, async (args) => safe(() => client.monitor(args)));
+    }, async ({ idempotency_key, ...args }) => safe(() => client.monitor(args, idempotency_key ? { idempotencyKey: idempotency_key } : undefined)));
     server.registerTool("report_outcome", {
@@ -161,0 +191,0 @@ description: "Report what actually happened for a prior check (by id) so the service can calibrate.",

dist/server.js.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package.json

 {
   "name": "@usekaval/mcp",
   "mcpName": "io.github.LufeMC/kaval",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "Apache-2.0",
@@ -50,3 +50,3 @@ "description": "MCP server for kaval — the freshness gate for AI. Pre-action currentness checks (verify/check/scan/monitor) as MCP tools; a thin client over the hosted Kaval API (BYO Kaval API key).",
     "zod": "^3.24.1",
-    "@usekaval/kaval": "^0.2.0"
+    "@usekaval/kaval": "^0.2.1"
   },
@@ -53,0 +53,0 @@ "devDependencies": {

README.md

@@ -12,2 +12,10 @@ # @usekaval/mcp
 
+Billable tool calls automatically carry a unique operation key. The underlying client reuses it for
+one bounded retry only when the transport outcome is ambiguous or the API is still finalizing the
+same operation, preventing duplicate billing without retrying terminal errors.
+
+If both attempts remain ambiguous, the tool error includes `idempotency_key`. Retry later by passing
+that exact value back as the optional `idempotency_key` argument on the same billable tool. Omit it
+for a genuinely new operation.
+
 ## Run it
@@ -54,5 +62,5 @@
 
-| Var              | Required | Purpose                                                                |
-| ---------------- | -------- | --------------------------------------------------------------------- |
-| `KAVAL_API_KEY`  | yes      | Bearer key for the hosted Kaval API (create one at https://usekaval.com) |
+| Var              | Required | Purpose                                                                                   |
+| ---------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `KAVAL_API_KEY`  | yes      | Bearer key for the hosted Kaval API (create one at https://usekaval.com)                  |
 | `KAVAL_BASE_URL` | no       | Override the API base URL (self-hosted / staging). Defaults to `https://api.usekaval.com` |
@@ -79,3 +87,5 @@
 
-const server = createMcpServer(new Kaval({ apiKey: process.env.KAVAL_API_KEY }));
+const server = createMcpServer(
+  new Kaval({ apiKey: process.env.KAVAL_API_KEY }),
+);
 ```

No alert changes

Improved metrics

Total package byte prevSize

40406

9.55%

Lines of code

275

12.24%

Number of lines in readme file

89

12.66%

Dependency changes

• Updated

  @usekaval/kaval@^0.2.1