@decionis/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright version 2.0 (c) 2026 Decionis, Inc.
+
+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,233 @@
+# @decionis/mcp — agent policy tools and execution hooks
+
+A stdio [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI coding
+agents (Claude Code, Cursor, Codex, OpenHands, …) read a repository's `DECIONIS_POLICY.md`
+and evaluate candidate actions **before** they commit, deploy, or migrate anything.
+
+It is not a re-implementation: `decionis_evaluate` boots the real `@decionis/protocol`
+service in-process with an in-memory store, publishes the repo policy through the
+protocol's own schema-validated bundle ingestion, and evaluates through
+`POST /v1/protocol/evaluate-decision` via fastify `inject()`. The verdict an agent sees
+locally is the verdict the platform would produce — with **zero network, zero database,
+zero credentials, and nothing recorded**.
+
+(The protocol service separately exposes a _remote_, authenticated MCP surface for
+org-connected agents; this package is the local, offline complement for repo checkouts.)
+
+The package now exposes two complementary surfaces:
+
+- **MCP tools** let the model read policy, evaluate an intended action, and understand the
+  verdict vocabulary.
+- **Native `PreToolUse` hooks** intercept every supported tool call outside the model's
+  discretion. Codex, GitHub Copilot, and Claude Code all normalize into one
+  `AgentToolCall` contract and one `AgentGateEvaluator` interface.
+
+MCP is the discovery and explanation surface. The native hook is the binding enforcement
+surface.
+
+## Tools
+
+| Tool                    | Purpose                                                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `decionis_read_policy`  | Path, sha256, and compiled rules (or compile errors) of the repo's `DECIONIS_POLICY.md`.                               |
+| `decionis_evaluate`     | Evaluate a candidate action payload against the policy through the real evaluator; returns the verdict + matched rule. |
+| `decionis_verdict_help` | The verdict vocabulary, rules-block grammar, and how an agent should behave on each verdict.                           |
+
+The policy file resolves from the tool's `path` argument, then `$DECIONIS_POLICY_PATH`,
+then `./DECIONIS_POLICY.md` in the working directory.
+
+## Install
+
+```bash
+npm install -g @decionis/mcp
+```
+
+Or skip the install entirely — every client config below can launch the server
+through `npx -y @decionis/mcp`.
+
+## Wire it up
+
+**Claude Code** — `.mcp.json` at the repo root:
+
+```json
+{
+  "mcpServers": {
+    "decionis": {
+      "command": "npx",
+      "args": ["-y", "@decionis/mcp"]
+    }
+  }
+}
+```
+
+**Codex** — add the stdio server to `~/.codex/config.toml` or a trusted project's
+`.codex/config.toml`:
+
+```toml
+[mcp_servers.decionis]
+command = "npx"
+args = ["-y", "@decionis/mcp"]
+required = true
+```
+
+**Cursor** — use the Claude server block in `.cursor/mcp.json`. During development,
+`"command": "pnpm", "args": ["--filter", "@decionis/mcp", "dev"]` also works.
+
+**Source checkout** — build once (`pnpm --filter @decionis/mcp build`) and point the
+client at the bin directly: `"command": "node", "args": ["<repo>/apps/mcp/dist/index.js"]`.
+
+## Native execution gate
+
+Install the package globally so `decionis-agent-hook` (and the other bins) land on the
+host's `PATH`:
+
+```bash
+npm install -g @decionis/mcp
+```
+
+Copy the provider template to its native repository location:
+
+| Host                                   | Template                        | Native location               |
+| -------------------------------------- | ------------------------------- | ----------------------------- |
+| Codex                                  | `templates/CodexHooks.json`     | `.codex/hooks.json`           |
+| Claude Code                            | `templates/ClaudeSettings.json` | `.claude/settings.json`       |
+| GitHub Copilot CLI/cloud agent/VS Code | `templates/CopilotHooks.json`   | `.github/hooks/Decionis.json` |
+
+For a source checkout, replace the template's `decionis-agent-hook …` command with:
+
+```text
+node "$(git rev-parse --show-toplevel)/apps/mcp/dist/AgentHookCli.js" <provider>
+```
+
+where `<provider>` is `codex`, `copilot`, or `claude`.
+
+### Evaluation modes
+
+The hook defaults to **local mode**. It loads `DECIONIS_POLICY.md`, publishes it into the
+real in-process protocol evaluator, and enforces the result without network access or
+credentials.
+
+Set these variables to use the enterprise policy graph and signed decision pipeline:
+
+```bash
+DECIONIS_AGENT_GATE_MODE=remote
+DECIONIS_AGENT_GATE_URL=https://protocol.decionis.com/v1/protocol/evaluate-decision
+DECIONIS_API_KEY=<org-scoped-key>
+DECIONIS_ORG_ID=<org-uuid>
+```
+
+`DECIONIS_AGENT_GATE_TIMEOUT_MS` optionally changes the remote request timeout (default:
+4 seconds). Partial remote configuration is rejected; network errors, invalid hook input,
+missing policy, and evaluator failures all produce a native deny response.
+
+An `APPROVE` result returns no permission override, so the host's normal sandbox and user
+approval flow still applies. `REJECT`, `REVIEW`, and `ESCALATE` all stop the tool call;
+the latter two remain blocked until a human resolves them through the policy workflow.
+
+### Reusable interface
+
+Other runtimes can import the same contracts and orchestration layer:
+
+```ts
+import {
+  AgentHookRunner,
+  type AgentGateEvaluator,
+  type AgentHostAdapter,
+  type AgentToolCall,
+} from "@decionis/mcp/agent";
+```
+
+A new provider implements only `AgentHostAdapter`; a new decision backend implements only
+`AgentGateEvaluator`. Neither needs to understand the other provider formats.
+
+For pre-prompt enforcement, `@decionis/sdk-node` exposes the complementary
+`DecionisAgentTaskGateway` interface. It reserves the model budget before an OpenAI or
+Anthropic proxy call, verifies sandbox egress, consumes the same bound grant at the proxy,
+and reconciles provider usage. Copilot embeddings use the same reserve/egress/reconcile
+contract when model transport itself is not replaceable.
+
+See
+[`docs/integrations/agents/AgentBoundaryGateway.md`](../../docs/integrations/agents/AgentBoundaryGateway.md)
+for the provider SDK configuration and four-boundary deployment model.
+
+### Managed distribution
+
+Device-management templates are under `templates/managed`:
+
+- `CodexRequirements.toml` pins the managed `PreToolUse` hook in
+  `requirements.toml`.
+- `CopilotPolicyHooks.json` is the root-owned Copilot CLI policy hook; cloud agent
+  continues to use the repository template.
+- `ClaudeManagedSettings.json` is the organization-controlled Claude Code settings
+  fragment.
+- `AgentPolicyBundle.json` is a fail-closed, source-dated policy-graph skeleton. It
+  contains explicit official list-price cards retrieved on 2026-07-27. Negotiated rates
+  are stored separately under the organization policy's
+  `agentExecution.providerContracts`; a contract overrides the public baseline only while
+  it is effective and independently maker-checker approved.
+- `AgentGateConfig.example.json` documents the protected, org-scoped runtime
+  configuration. The package never embeds its API key.
+
+Build the deterministic deployment ZIP with:
+
+```bash
+pnpm --filter @decionis/mcp package:managed
+```
+
+The ZIP contains Linux, macOS, and Windows payload trees, the bundled managed runner,
+native policy files, the organization policy template, an install manifest, and
+`SHA256SUMS`. Codex executes the runner from its declared managed hook directory. Render
+the example runtime configuration at the manifest destination, protect it with
+administrator-only permissions, and distribute the matching payload through the
+organization's package or device-management system.
+
+### Host boundaries
+
+- `PreToolUse` happens after the host has already spent tokens choosing a tool. It prevents
+  the side effect, but it cannot prevent the model cost incurred before that point. Put the
+  Decionis API/network gateway in front of model traffic when pre-prompt token and cost
+  reservation is required.
+- Codex hooks cover shell commands, `apply_patch`, MCP calls, and supported local
+  function tools. Hosted tools that do not traverse the local hook path need a separate
+  gateway boundary.
+- Copilot command-hook timeouts are fail-open at the host level. Keep the Decionis
+  request timeout below the hook timeout (the defaults are 4 seconds and 10 seconds)
+  and deploy the executable inside the cloud-agent image.
+- Copilot cloud agent requires the Decionis endpoint to be permitted by its network
+  firewall when remote mode is used.
+- VS Code agent hooks are currently a preview surface. VS Code reads the same
+  `.github/hooks/*.json` template, emits the PascalCase-compatible snake-case payload,
+  and receives the nested native denial shape from the adapter.
+- Copilot's `userPromptSubmitted` event is observational and cannot block prompt
+  processing. Copilot pre-prompt spend enforcement therefore belongs at the enterprise
+  proxy/API boundary, not in a repository hook.
+- Hook inputs may contain secrets inside commands or tool arguments. The gate evaluates
+  them in memory and does not log them.
+
+## Development
+
+```bash
+pnpm --filter @decionis/mcp test        # vitest (includes the real evaluator)
+pnpm --filter @decionis/mcp typecheck
+pnpm --filter @decionis/mcp build       # self-contained dist/index.js (shebang bin)
+pnpm --filter @decionis/mcp package:managed
+```
+
+Smoke test over stdio:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"decionis_evaluate","arguments":{"payload":{"action":"production-deploy","change_freeze":true}}}}' \
+  | node dist/index.js
+```
+
+## Notes
+
+- The rules-block compiler here mirrors
+  `apps/api/src/services/policyEncoding/decionisRulesBlock.ts` and must stay in lockstep
+  (local difference: JSON-only block bodies; the platform also accepts YAML).
+- Rules without `"domain": "*"` are filtered by the platform's decision-domain match —
+  the evaluate tool detects this and tells the agent how to fix the policy.
+- Local evaluations mint no signed Decision Dossier; CI runs through
+  [`decionis/govern`](https://github.com/decionis/govern) produce the verifiable record.

package/dist/AgentHookCli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/AgentHookCli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import {
+  AgentHookCommand
+} from "./chunk-UN67W5FH.js";
+import "./chunk-QSCP7MRQ.js";
+
+// src/AgentHookCli.ts
+void AgentHookCommand.run(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+}).catch((error) => {
+  process.stderr.write(
+    `decionis-agent-hook: ${error instanceof Error ? error.message : error}
+`
+  );
+  process.exitCode = 2;
+});
+//# sourceMappingURL=AgentHookCli.js.map

package/dist/AgentHookCli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/AgentHookCli.ts"],"sourcesContent":["import { AgentHookCommand } from \"./agent/AgentHookCommand.js\";\n\nvoid AgentHookCommand.run(process.argv.slice(2))\n  .then((exitCode) => {\n    process.exitCode = exitCode;\n  })\n  .catch((error) => {\n    process.stderr.write(\n      `decionis-agent-hook: ${error instanceof Error ? error.message : error}\\n`,\n    );\n    process.exitCode = 2;\n  });\n"],"mappings":";;;;;;;AAEA,KAAK,iBAAiB,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC,EAC5C,KAAK,CAAC,aAAa;AAClB,UAAQ,WAAW;AACrB,CAAC,EACA,MAAM,CAAC,UAAU;AAChB,UAAQ,OAAO;AAAA,IACb,wBAAwB,iBAAiB,QAAQ,MAAM,UAAU,KAAK;AAAA;AAAA,EACxE;AACA,UAAQ,WAAW;AACrB,CAAC;","names":[]}

package/dist/ManagedAgentHookCli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }