@keelcodes/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Keel contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,104 @@
+# @keelcodes/mcp
+
+A **policy-aware MCP server**: it exposes an agent account's on-chain actions to a
+model as [Model Context Protocol](https://modelcontextprotocol.io) tools, and every
+action is checked against `@keelcodes/policy` **before it runs**.
+
+The difference between *policy-aware* and *policy-documented* is where the gate
+sits. A denied call never reaches the tool handler — the gate stands in front of
+`run`, so a misbehaving model cannot talk the account past its policy, and no
+amount of prompt injection changes the outcome.
+
+## What it speaks
+
+- Protocol revision **`2025-06-18`** (also accepts `2025-03-26` / `2024-11-05` on
+  `initialize`, and answers in the client's version when known).
+- Methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`,
+  `tools/call`.
+- Transport: newline-delimited JSON over stdio — one JSON-RPC 2.0 message per
+  line, no embedded newlines.
+- Errors use the standard JSON-RPC codes (`-32700`, `-32600`, `-32601`, `-32602`,
+  `-32603`). A *policy denial* is **not** a protocol error: it is a tool result
+  with `isError: true`, so the reason is visible to the model.
+
+## Built-in tools
+
+`createPolicyTools` ships the three moves an agent needs in front of a
+policy-bounded account, in the order it needs them:
+
+| Tool | Gated? | Does |
+|---|---|---|
+| `keel_policy` | no | Return the commitment hash and the normalised rules. |
+| `keel_check_call` | no | Dry-run a call; returns `allowed` plus the refusing rule. |
+| `keel_execute_call` | **yes** | Execute — a denied call never reaches the executor. |
+
+Reading and dry-running are deliberately ungated: refusing them would only hide
+the policy from the model and push it to guess.
+
+### PIM tools (ERC-8313)
+
+`createPimTools` adds consumption of **Protocol Interaction Manifests** — a PIM
+is untrusted JSON, so the model can check it before acting on it. Both tools are
+read-only and ungated, and take the manifest inline as `{ pim: <object> }` (this
+package never touches the filesystem):
+
+| Tool | Does |
+|---|---|
+| `pim_validate` | Validate against the nine mandatory sections; returns `{ valid, errors, warnings }`. |
+| `pim_inspect` | Summarise protocol/chains/intents/contracts and the assigned trust level (0–3). |
+
+## Usage
+
+```ts
+import { createMcpServer, createPolicyGate, createPolicyTools, serveStdio } from '@keelcodes/mcp';
+import type { Policy } from '@keelcodes/policy';
+
+const policy: Policy = /* normalisePolicy({ … }) */;
+
+const server = createMcpServer({
+  name: 'keel',
+  version: '0.1.0',
+  tools: createPolicyTools({
+    policy,
+    // Wire this to a bundler/paymaster; without it keel_execute_call reports unavailable.
+    executor: async (call) => ({ transactionHash: '0x…' }),
+  }),
+  gate: createPolicyGate({ policy }),
+});
+
+serveStdio({ server });
+```
+
+This is a library: the process entry point is yours. Point an MCP client at that
+entry (an `mcp-stdio.js` that imports `serveStdio` as above):
+
+```json
+{
+  "mcpServers": {
+    "keel": { "command": "node", "args": ["./dist/mcp-stdio.js"] }
+  }
+}
+```
+
+When no policy is configured, use the safe default `DENY_ALL`: the server can still
+describe itself and dry-run, but it cannot execute. That is "cannot act", never
+"acts by default".
+
+## Design
+
+- **One source of truth.** The gate calls `evaluateCall` from `@keelcodes/policy` —
+  the same function the on-chain hook mirrors — so an MCP verdict and the eventual
+  transaction cannot disagree.
+- **Ports, not wiring.** `PolicyGate`, `CallExecutor` and `serveStdio`'s
+  `ReadableLike` / `WritableLike` are structural interfaces, so tests inject fakes
+  and the package needs no `@types/node`.
+
+## Develop
+
+```bash
+pnpm --filter @keelcodes/mcp build
+pnpm --filter @keelcodes/mcp test
+```
+
+The integration point is described in
+[`docs/KEEL_PLAN.md`](../../docs/KEEL_PLAN.md) §4.4 ⑥.

package/dist/builtin.d.ts

@@ -0,0 +1,32 @@
+import { type Call, type Policy } from '@keelcodes/policy';
+import { type McpTool } from './tools.js';
+/**
+ * The built-in, policy-aware tools.
+ *
+ * These are the three moves an agent needs in front of a policy-bounded account,
+ * in the order it needs them:
+ *
+ * 1. `keel_policy` — read what it is allowed to do.
+ * 2. `keel_check_call` — dry-run a call and learn the verdict before spending.
+ * 3. `keel_execute_call` — execute, gated: a denied call never reaches the
+ *    executor.
+ *
+ * Reading and dry-running are deliberately **not** gated — refusing them would
+ * only hide the policy from the model and push it to guess.
+ */
+/** Runs a policy-approved call. Wire it to a bundler/paymaster via `@keelcodes/adapters`. */
+export type CallExecutor = (call: Call) => Promise<Record<string, unknown>> | Record<string, unknown>;
+export interface PolicyToolsOptions {
+    /** The normalised policy these tools describe and enforce. */
+    policy: Policy;
+    /** Required for `keel_execute_call`; without it that tool reports unavailable. */
+    executor?: CallExecutor;
+    /** Clock for the dry-run; defaults to the wall clock. */
+    now?: () => bigint;
+}
+export declare function createPolicyTools(options: PolicyToolsOptions): McpTool[];
+/** A JSON-safe rendering of a normalised policy (bigints become decimal strings). */
+export declare function describePolicy(policy: Policy): Record<string, unknown>;
+/** A JSON-safe rendering of a call. */
+export declare function describeCall(call: Call): Record<string, unknown>;
+//# sourceMappingURL=builtin.d.ts.map

package/dist/builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../src/builtin.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAA4C,KAAK,OAAO,EAAiB,MAAM,YAAY,CAAC;AAEnG;;;;;;;;;;;;;GAaG;AAEH,6FAA6F;AAC7F,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtG,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAeD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,EAAE,CAgDxE;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBtE;AAED,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOhE"}

package/dist/builtin.js

@@ -0,0 +1,114 @@
+import { evaluateCall, policyCommitment, toCall } from '@keelcodes/policy';
+import { errorResult, jsonResult } from './tools.js';
+const CALL_SCHEMA = {
+    type: 'object',
+    properties: {
+        target: { type: 'string', description: 'Contract or recipient address, 0x-prefixed.' },
+        value: { type: 'string', description: 'Native value in wei as a decimal string. Defaults to "0".' },
+        data: { type: 'string', description: 'Call data, 0x-prefixed. Defaults to "0x", a plain value transfer.' },
+    },
+    required: ['target'],
+    additionalProperties: false,
+};
+const EMPTY_SCHEMA = { type: 'object', properties: {}, additionalProperties: false };
+export function createPolicyTools(options) {
+    const { policy } = options;
+    const now = options.now ?? (() => BigInt(Math.floor(Date.now() / 1000)));
+    const policyTool = {
+        name: 'keel_policy',
+        title: 'Keel policy',
+        description: 'Return the authorization policy this server enforces: its canonical commitment hash and normalised rules. Read-only.',
+        inputSchema: EMPTY_SCHEMA,
+        run: () => jsonResult({ commitment: policyCommitment(policy), policy: describePolicy(policy) }),
+    };
+    const checkTool = {
+        name: 'keel_check_call',
+        title: 'Dry-run a call against the policy',
+        description: 'Evaluate a proposed call against the policy without executing it. Returns whether it would be allowed and, if not, the exact rule that refused it. Read-only and never gated.',
+        inputSchema: CALL_SCHEMA,
+        run: (args) => {
+            const call = callFromArgs(args);
+            const decision = evaluateCall(policy, { now: now(), usage: [] }, call);
+            return jsonResult({
+                allowed: decision.allowed,
+                ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+                ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
+            });
+        },
+    };
+    const executeTool = {
+        name: 'keel_execute_call',
+        title: 'Execute a policy-approved call',
+        description: 'Execute a call on the agent account. The call is checked against the policy first; a denied call is never executed.',
+        inputSchema: CALL_SCHEMA,
+        action: (args) => ({ kind: 'execute-call', call: callFromArgs(args) }),
+        run: async (args) => {
+            if (options.executor === undefined) {
+                return errorResult('this server has no call executor configured; keel_execute_call is unavailable');
+            }
+            const call = callFromArgs(args);
+            const outcome = await options.executor(call);
+            return jsonResult({ executed: true, call: describeCall(call), ...outcome });
+        },
+    };
+    return [policyTool, checkTool, executeTool];
+}
+/** A JSON-safe rendering of a normalised policy (bigints become decimal strings). */
+export function describePolicy(policy) {
+    return {
+        version: policy.version,
+        validAfter: policy.validAfter.toString(),
+        validUntil: policy.validUntil.toString(),
+        rules: policy.rules.map((rule) => ({
+            target: rule.target,
+            selectors: [...rule.selectors],
+            maxPerTx: rule.maxPerTx.toString(),
+            maxDaily: rule.maxDaily.toString(),
+            maxCalls: rule.maxCalls,
+            tokenLimits: rule.tokenLimits.map((limit) => ({
+                token: limit.token,
+                maxPerTx: limit.maxPerTx.toString(),
+                maxDaily: limit.maxDaily.toString(),
+            })),
+        })),
+    };
+}
+/** A JSON-safe rendering of a call. */
+export function describeCall(call) {
+    return {
+        target: call.target,
+        value: call.value.toString(),
+        data: call.data,
+        selector: call.selector,
+    };
+}
+function callFromArgs(args) {
+    const target = requireString(args, 'target');
+    const data = args.data === undefined ? undefined : requireString(args, 'data');
+    const value = args.value === undefined ? 0n : parseWei(args.value);
+    return toCall({
+        target: target,
+        value,
+        ...(data !== undefined ? { data: data } : {}),
+    });
+}
+function parseWei(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value !== 'string')
+        throw new Error('"value" must be a decimal string of wei');
+    try {
+        return BigInt(value);
+    }
+    catch {
+        throw new Error(`"value" is not a valid integer: "${value}"`);
+    }
+}
+function requireString(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`"${name}" is required and must be a non-empty string`);
+    }
+    return value;
+}
+//# sourceMappingURL=builtin.js.map

package/dist/builtin.js.map

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

package/dist/gate.d.ts

@@ -0,0 +1,46 @@
+import { type Call, type Policy, type RuleUsage } from '@keelcodes/policy';
+/**
+ * What a tool wants to do, in terms the policy engine understands.
+ *
+ * A tool that performs no call (a read, a dry-run) declares no `call` and is
+ * always allowed through — the gate only stands in front of actions.
+ */
+export interface ToolAction {
+    /** Short label used in denial messages, e.g. `transfer`. */
+    kind: string;
+    /** The call to evaluate. When absent, the action is not gated. */
+    call?: Call;
+}
+export type GateVerdict = 'allow' | 'deny';
+export interface GateDecision {
+    verdict: GateVerdict;
+    /** Set when `verdict` is `deny`. */
+    reason?: string;
+    /** The policy rule that decided it, when one matched. */
+    ruleIndex?: number;
+}
+/** Decides whether a tool action may proceed. */
+export interface PolicyGate {
+    check(action: ToolAction): Promise<GateDecision> | GateDecision;
+}
+export interface PolicyGateOptions {
+    /** The normalised policy to enforce. */
+    policy: Policy;
+    /** Current unix time in seconds. Defaults to the wall clock. */
+    now?: () => bigint;
+    /**
+     * Usage aligned to `policy.rules` by index. Defaults to zero, which is right
+     * for a stateless server; a stateful one advances it as calls are allowed.
+     */
+    usage?: () => readonly RuleUsage[];
+}
+/**
+ * Wraps `@keelcodes/policy`'s off-chain pre-check as a {@link PolicyGate}.
+ *
+ * The gate never widens what the on-chain module allows: it runs the same
+ * `evaluateCall` the account's hook mirrors, so a denial here is a denial there.
+ */
+export declare function createPolicyGate(options: PolicyGateOptions): PolicyGate;
+/** A gate that denies every action — the safe default when no policy is wired. */
+export declare const DENY_ALL: PolicyGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,IAAI,EAAmB,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE1G;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;CACjE;AAED,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,SAAS,SAAS,EAAE,CAAC;CACpC;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAqBvE;AAED,kFAAkF;AAClF,eAAO,MAAM,QAAQ,EAAE,UAEtB,CAAC"}

package/dist/gate.js

@@ -0,0 +1,38 @@
+import { evaluateCall } from '@keelcodes/policy';
+const noUsage = [];
+/**
+ * Wraps `@keelcodes/policy`'s off-chain pre-check as a {@link PolicyGate}.
+ *
+ * The gate never widens what the on-chain module allows: it runs the same
+ * `evaluateCall` the account's hook mirrors, so a denial here is a denial there.
+ */
+export function createPolicyGate(options) {
+    const now = options.now ?? (() => BigInt(Math.floor(Date.now() / 1000)));
+    const usage = options.usage ?? (() => noUsage);
+    return {
+        check(action) {
+            if (action.call === undefined)
+                return { verdict: 'allow' };
+            const decision = evaluateCall(options.policy, { now: now(), usage: usage() }, action.call);
+            if (decision.allowed) {
+                return decision.ruleIndex === undefined
+                    ? { verdict: 'allow' }
+                    : { verdict: 'allow', ruleIndex: decision.ruleIndex };
+            }
+            return {
+                verdict: 'deny',
+                reason: describeDenial(decision.reason, action.kind),
+                ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
+            };
+        },
+    };
+}
+/** A gate that denies every action — the safe default when no policy is wired. */
+export const DENY_ALL = {
+    check: () => ({ verdict: 'deny', reason: 'no policy configured; all actions are denied' }),
+};
+function describeDenial(reason, kind) {
+    const detail = reason ?? 'unknown';
+    return `policy denied ${kind}: ${detail}`;
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA2D,MAAM,mBAAmB,CAAC;AA0C1G,MAAM,OAAO,GAAyB,EAAE,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IAE/C,OAAO;QACL,KAAK,CAAC,MAAkB;YACtB,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAE3D,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAC3F,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrB,OAAO,QAAQ,CAAC,SAAS,KAAK,SAAS;oBACrC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE;oBACtB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;YAC1D,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,MAAM;gBACf,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;gBACpD,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,QAAQ,GAAe;IAClC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,8CAA8C,EAAE,CAAC;CAC3F,CAAC;AAEF,SAAS,cAAc,CAAC,MAA8B,EAAE,IAAY;IAClE,MAAM,MAAM,GAAG,MAAM,IAAI,SAAS,CAAC;IACnC,OAAO,iBAAiB,IAAI,KAAK,MAAM,EAAE,CAAC;AAC5C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @keelcodes/mcp
+ *
+ * A **policy-aware MCP server**: it exposes on-chain actions to a model as MCP
+ * tools, and every action passes through `@keelcodes/policy` before it runs.
+ *
+ * The server implements the server side of the Model Context Protocol revision
+ * `2025-06-18` — `initialize`, `tools/list`, `tools/call` — over the
+ * newline-delimited stdio transport, and ships three built-in tools
+ * ({@link createPolicyTools}): read the policy, dry-run a call, execute a call.
+ *
+ * What makes it *policy-aware* rather than merely *policy-documented*: a denied
+ * call never reaches the tool's handler. The gate stands in front of `run`, so
+ * the account cannot be instructed past the policy even by a misbehaving model.
+ *
+ * @packageDocumentation
+ */
+export { JSONRPC_ERROR, MCP_METHODS, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, rpcError, } from './protocol.js';
+export type { JsonRpcErrorBody, JsonRpcFailure, JsonRpcId, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccess, McpInitializeResult, McpServerInfo, McpTextContent, McpToolResult, } from './protocol.js';
+export { DENY_ALL, createPolicyGate } from './gate.js';
+export type { GateDecision, GateVerdict, PolicyGate, PolicyGateOptions, ToolAction, } from './gate.js';
+export { ToolRegistry, errorResult, jsonReplacer, jsonResult, textResult } from './tools.js';
+export type { JsonSchema, McpTool, ToolArgs, ToolDescriptor } from './tools.js';
+export { createMcpServer } from './server.js';
+export type { McpServer, McpServerOptions } from './server.js';
+export { serveStdio } from './stdio.js';
+export type { ReadableLike, ServeStdioOptions, WritableLike } from './stdio.js';
+export { createPolicyTools, describeCall, describePolicy } from './builtin.js';
+export type { CallExecutor, PolicyToolsOptions } from './builtin.js';
+export { createPimTools } from './pim.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,cAAc,EACd,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,UAAU,GACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @keelcodes/mcp
+ *
+ * A **policy-aware MCP server**: it exposes on-chain actions to a model as MCP
+ * tools, and every action passes through `@keelcodes/policy` before it runs.
+ *
+ * The server implements the server side of the Model Context Protocol revision
+ * `2025-06-18` — `initialize`, `tools/list`, `tools/call` — over the
+ * newline-delimited stdio transport, and ships three built-in tools
+ * ({@link createPolicyTools}): read the policy, dry-run a call, execute a call.
+ *
+ * What makes it *policy-aware* rather than merely *policy-documented*: a denied
+ * call never reaches the tool's handler. The gate stands in front of `run`, so
+ * the account cannot be instructed past the policy even by a misbehaving model.
+ *
+ * @packageDocumentation
+ */
+export { JSONRPC_ERROR, MCP_METHODS, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, rpcError, } from './protocol.js';
+export { DENY_ALL, createPolicyGate } from './gate.js';
+export { ToolRegistry, errorResult, jsonReplacer, jsonResult, textResult } from './tools.js';
+export { createMcpServer } from './server.js';
+export { serveStdio } from './stdio.js';
+export { createPolicyTools, describeCall, describePolicy } from './builtin.js';
+export { createPimTools } from './pim.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,QAAQ,GACT,MAAM,eAAe,CAAC;AAcvB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AASvD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7F,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG/E,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/pim.d.ts

@@ -0,0 +1,16 @@
+import { type McpTool } from './tools.js';
+/**
+ * ERC-8313 Protocol Interaction Manifest tools.
+ *
+ * A manifest is an *untrusted input*: it arrives as JSON from a dApp, a
+ * registry or a peer agent. These tools let a model validate and summarise one
+ * before it is ever acted on. Both are read-only and therefore ungated —
+ * refusing to validate a manifest would only push the model to guess at its
+ * shape, which is exactly the failure mode the PIM standard exists to remove.
+ *
+ * `pim` is passed inline as a parsed object (not a path): this package
+ * deliberately has no `@types/node` dependency, so it never touches the
+ * filesystem. A host that wants path input reads the file itself.
+ */
+export declare function createPimTools(): McpTool[];
+//# sourceMappingURL=pim.d.ts.map

package/dist/pim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pim.d.ts","sourceRoot":"","sources":["../src/pim.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,OAAO,EAAiB,MAAM,YAAY,CAAC;AAEtF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,OAAO,EAAE,CA+C1C"}