Refund eligibility notary for US subscriptions. Returns ALLOWED/DENIED/UNKNOWN.
io.github.ndkasndakn/refund-decide (MCP Server)
The io.github.ndkasndakn/refund-decide MCP server is a refund-eligibility notary for US subscriptions. It returns a decision status of ALLOWED, DENIED, or UNKNOWN, acting as a stable MCP-compatible service within decision or policy workflows.
🛠️ Key Features
Refund eligibility determination for US subscriptions
Decision outputs: ALLOWED / DENIED / UNKNOWN
1 available tool
🚀 Use Cases
Customer-support workflows for US subscription refunds
Policy automation and execution gating where refund eligibility must be decided
⚡ Developer Benefits
MCP-compatible notary behavior for workflow integration
Deterministic decision interface for downstream systems
⚠️ Limitations
Scope is stated as US subscriptions only
Decision granularity is limited to ALLOWED / DENIED / UNKNOWN
Evaluate a US consumer subscription refund against versioned source-backed rules. Returns UNKNOWN when required conditions are absent or the vendor requires approval or manual policy review.
Deterministic Decision API engine powering workflow applications, stable MCP notary remotes, decision memo packets, and execution gates
Positioning: Decide Runtime is the general deterministic decision engine. Decide Services are standalone specialized checks built on it; Policy Notaries is the existing family. Krafthaus owns workflow applications built on Decide, including intake, review, and execution handoff. MCP, REST, and SDK interfaces belong to the product they expose, not automatically to Krafthaus.
See the ecosystem ownership contract. Direct
service and runtime integrations do not require a Krafthaus app. Policy checks
are one service family, not the definition of the general Decision API.
Gate agent tool calls before execution
Use Decide to evaluate an agent-proposed action against a deterministic rulebook
before the tool receives authority to change state. The caller gets a replayable
Decision Record and routes yes, no, or review while retaining control of
credentials and execution.
The production core is hybrid_declarative_rulebook_with_trusted_adapters:
direct declarative rulebooks are supported, registered first-party trusted
adapters may supply bounded facts, and customer executable rulebooks are
rejected. In both supported binding modes, Rulebook v1 remains the only binding
verdict selector.
mode: "rulebook" does not call an LLM. It validates the request rulebook
against the published JSON Schema, hashes the rulebook, evaluates bounded
conditions, and returns yes, no, or review alongside the application
verdict, action, reason code, matched rule, and evaluator_version. Responses
also include rulebook_contract with the enforced schema URL/hash,
runtime_binding with the direct or trusted-adapter binding mode, input_hash,
a SHA-256 hash of the canonical inputs or adapter facts consumed by the
declarative evaluator, plus a rulebook_attestation_v1 bundle hash over the
deterministic execution tuple.
Production deployments can sign that bundle hash with a
rulebook_attestation_signature_v1 Ed25519 envelope; verification keys are
published at /.well-known/rulebook-attestation-keys.json. Set
DECIDE_RULEBOOK_ATTESTATION_SIGNATURE_REQUIRED=true in production to fail
closed instead of returning unsigned Rulebook decisions. Publish retired public
verification keys with DECIDE_RULEBOOK_ATTESTATION_KEY_HISTORY_JSON so older
Decision Records remain verifiable after rotation.
Rulebook requests cannot preload Decide-generated Decision Record material.
Fields such as runtime_binding, trusted_adapter, adapter_facts,
rulebook_attestation, application_verdict, and action are response-only at
the request body, context.inputs, and adapter-facts boundaries; attempts return
RULEBOOK_OUTPUT_MATERIAL_FORBIDDEN.
Legacy single, multi, and runtime requests remain available for
AI-assisted exploration, but they are not binding production verdicts. Those
responses include decision_contract with authority: "advisory_only" and
production_verdict: false, plus production_binding_required: true and the
supported production binding modes; callers that need deterministic execution
must use mode: "rulebook" and capture rulebook_contract, runtime_binding,
and the Rulebook attestation material.
At the public Decision Record boundary, successful evaluations are registered
as immutable tenant-scoped snapshots. Historical replay restores the original
canonical input and stored rulebook snapshot rather than trusting a caller
override or the current application deployment.
Rulebook v1 also supports registered first-party trusted adapters for bounded
fact normalization. Adapter requests pin an exact semantic version and manifest
hash; responses attest the bundled implementation source hash plus canonical
input/output hashes and the enforced execution contract. Each invocation runs
once in an empty-environment worker with hard time/resource limits and denied
common ambient capabilities. The declarative rulebook remains the only binding
verdict selector. See docs/TRUSTED_ADAPTERS_V1.md.
The current reference applications prove both production patterns: Solana
Execution Gate, Decision Memo Readiness Gate, and Krafthaus Workflow Readiness Binding
use trusted adapters before Rulebook v1, while the Refund, Trial, Cancel, and
Return Policy MCP notaries supply normalized facts directly to Rulebook v1 and
expose the signed rulebook result through their stable REST and MCP surfaces.
Before evaluator, adapter, or rulebook changes ship, run the local historical
replay gate:
bash
npm run rulebook:migration-dry-run -- --json
Use --candidate-rulebook, --candidate-adapter, and
--candidate-evaluator-version to compare proposed migrations against the
golden replay corpus before production routing changes.
For release gates, prefer a rulebook_migration_v1 manifest so candidate
artifacts, expected drift, and approval status are reviewed together:
bash
npm run rulebook:migration-dry-run -- --migration path/to/migration.json --json
The manifest schema is published at
https://api.decide.fyi/schemas/rulebook-migration-v1.schema.json, and the dry
run validates manifests against that closed schema before replay.
After production routing or runtime-contract changes ship, run the production
runtime smoke:
bash
npm run smoke:rulebook-runtime
This hits https://api.decide.fyi from outside the runtime and always verifies
the published hybrid_declarative_rulebook_with_trusted_adapters manifest,
closed Rulebook v1 schema, attestation key endpoint, and protected Decision API
edge. Supply DECIDE_RULEBOOK_RUNTIME_SMOKE_API_KEY to also exercise live
declarative evaluation, rejection behavior, and advisory-only legacy metadata.
GitHub Actions runs the public boundary checks as the scheduled/manual
Rulebook Runtime Production Smoke workflow and runs the authenticated checks
when its optional smoke credential is configured.
The legacy single, multi, and runtime modes are AI-assisted surfaces.
They are not the production determinism boundary for loosely defined business
judgment.
The public @decide-fyi/sdk
client covers Decision API calls, Decision Record and Decision Packet
verification, Rulebook conformance, replay, execution receipts, and outcome
reporting.
sh
npm install @decide-fyi/sdk
The canonical package source is sdk/, licensed under Apache-2.0.
Package release requirements and source mapping are documented in
sdk/SOURCE_PROVENANCE.md.
Stateless, no auth, 100 req/min. Coverage is policy-specific: 100 existing US individual-plan vendors, plus scoped Typeform Basic cancellation only. Results fail closed to UNKNOWN when scope or current reviewed evidence is missing. See Typeform integration.
Quick Start
Connect via MCP (Claude Desktop / Windsurf / other clients)
Only set evidence fields from facts you have actually verified. A time window alone is not proof that source-specific conditions are satisfied. Approval-dependent policies stay UNKNOWN even when a caller sets qualifying_conditions_met; trial results require a live offer observation.
Local Dev Checks
Start local dev server:
bash
npx vercel dev
In a separate terminal:
bash
# Handler-level smoke checks (no running server required)
npm run smoke
# MCP endpoint checks (requires a running server)
npm run mcp:check
# Self-contained local MCP check; starts/stops vercel dev on localhost:3000
npm run mcp:check:local# End-to-end workflow fixture (example -> result)
npm run workflow:test# Production customer-key verification after provisioning a key
DECIDE_SMOKE_API_KEY='<customer-key>' npm run smoke:customer-key
Protected Zendesk Reference Workflow
The Zendesk routes are protected reference adapters. They return an advisory
classification, a policy result, and a recommended Zendesk action shape, but
they do not write to Zendesk, authorize execution, or create a binding
production Decision Record. Every response sets
workflow_contract.execution_allowed: false.
For the production architecture, including the Rulebook v1 action boundary and
Decision Record that must precede a downstream side effect, see
docs/POLICY_MCP_SUPPORT_WORKFLOW.md.
Endpoints
POST https://refund.decide.fyi/api/v1/workflows/zendesk/refund
POST https://cancel.decide.fyi/api/v1/workflows/zendesk/cancel
POST https://return.decide.fyi/api/v1/workflows/zendesk/return
POST https://trial.decide.fyi/api/v1/workflows/zendesk/trial
Request
json
{"ticket_id":"ZD-9001","workflow_type":"refund","question":"Should this Adobe annual plan refund request proceed under policy?","vendor":"adobe","region":"US","plan":"individual","days_since_purchase":5,"qualifying_conditions_met":true}
Production workflow requests require a server-to-server Bearer token:
For refund and return, include days_since_purchase and source-specific condition evidence when requested. Cancellation may require billing_cadence. Trial automation requires offer_confirmed plus the observed duration, card requirement, and auto-conversion status. The workflow escalates instead of approving when required context is absent.
Test-only fixture mode
decision_override exists only for explicit local and CI tests with both
NODE_ENV=test and WORKFLOW_TEST_MODE=1. It is rejected by deployed routes
and must never be used as an integration mechanism.
Evaluates a refund only when the versioned rule and supplied source-specific facts support automation.
Input:vendor, days_since_purchase, region, plan, and conditionally qualifying_conditions_met
json
{"refundable":true,"verdict":"ALLOWED","code":"WITHIN_WINDOW","message":"Refund is allowed. Purchase is 12 day(s) old, within 14 day window.","vendor":"adobe","window_days":14,"qualifying_conditions_met":true,"automation_safe":true}
Checks cancellation penalties — early termination fees, contract locks, or free cancellation.
Adobe cancellation is review-only: billing cadence cannot identify its contract,
timing, state-specific or renewal branch. This example is a safe review response,
not a fee quote. Retired or non-current policy evidence also requires review.
Input:vendor, region, plan, and conditionally billing_cadence
Known vendor IDs are not a promise that every scope can be automated. Check
automation_safe, policy_decision_mode and policy_evidence on each response.
WeightWatchers refund, cancellation and return sources are retired; their history
remains available, but they are no longer actively fetched or usable for new
automated decisions. See scope reliability and admission.
Evaluates whether a subscription purchase can be reversed when the versioned rule and supplied source-specific facts support automation.
Input:vendor, days_since_purchase, region, plan, and conditionally qualifying_conditions_met
json
{"returnable":true,"verdict":"RETURNABLE","code":"FULL_RETURN","message":"Return is available. Purchase is 5 day(s) old, within 14-day window.","vendor":"adobe","return_type":"full_refund","method":"self_service","qualifying_conditions_met":true,"automation_safe":true}
Evaluates availability and terms from a live offer observation. It does not publish static trial availability.
Input:vendor, region, plan, offer_confirmed; when confirmed, also observed_trial_days, observed_card_required, observed_auto_converts
json
{"verdict":"TRIAL_AVAILABLE","code":"AUTO_CONVERTS","message":"A live 7-day adobe trial offer was confirmed. Credit card required. Auto-converts to paid plan.","vendor":"adobe","trial_days":7,"card_required":true,"auto_converts":true,"offer_confirmed":true,"automation_safe":true}
The versioned JSON registries are the canonical vendor catalog. A compact Markdown
table is intentionally not duplicated here because policy windows, channels, and
approval branches can change independently. Contract tests require each policy's
rules, sources and discovery to agree. Typeform is admitted for cancellation
only, not refund, return or trial.
deterministic: the standard policy is categorical for the supported US individual-plan scope.
conditional: automation requires an explicit caller assertion that the source-specific conditions were verified.
review_only: the policy depends on approval, channel, commitment, exceptions, or source language that is not categorical enough to automate.
observed: the current account or promotion must expose a live offer before trial terms can be returned.
Scope: US individual plans by default. Typeform cancellation has an explicit Basic, direct, self-serve platform-subscription override.
Data Freshness
Each policy family has versioned rules and source metadata. Cancellation has 101 vendor identifiers; the other three families have 100 each.
The source tracker monitors official vendor documentation and terms of service;
it does not automatically promote page text into a verdict.
Daily source checks — The Daily Policy Check workflow runs once daily across refund, cancellation, return, and trial sources. Material signals enter a human review queue; fetching does not renew applicability verification.
Human-verification freshness: npm run audit:policy-freshness reports reviewed-source age independently from tracker uptime. New policy evaluations also require current, request-bound evidence; missing or stale evidence routes to review.
Policy source URLs tracked — Each policy family has its own sources file in rules/ linking to official policy pages.
Compliance export — GET /api/compliance-export returns a CSV snapshot of tracked sources, hashes, and pending candidate changes (?format=json for machine-readable output).
Versioned rules — Each rules file includes a rules_version field for staleness detection.
Architecture
Stateless verdict runtime — Policy calls do not create sessions or mutate policy rules
Deterministic — Same input always produces same output
Versioned Rules — Rules files include version for tracking changes
Scheduled Monitoring — GitHub Action checks all vendor policy pages every six hours
Serverless — Runs on Vercel serverless functions
Zero Dependencies — Core compute logic has no external dependencies
GET /api/compliance-export endpoint for policy monitoring evidence export (CSV default, JSON via ?format=json).
Smoke test coverage for compliance export JSON and CSV paths.
Private report:mcp-adoption operator report that separates remote-server discovery, probes, and completed Policy Notaries evaluations.
Token-gated Console adoption snapshot with declared MCP client attribution, conservative follow-on inference, and aggregate-only output.
Service-only Policy Notaries guide funnel that keeps connection intent, public REST proof, MCP evaluation, and Krafthaus workflow handoff metrics distinct.
Changed:
Landing pages now position Decide as the Decision API engine and frame Policy MCP Notaries as one reference application.
Zendesk reference routes require server-to-server authentication in production, fail closed when unconfigured, and mark all returned action shapes as non-executing.
v1.2.1 (2026-02-08)
Changed:
Subdomain homepage now shows the relevant notary card (refund/cancel/return/trial).
Version metadata is consistent across server.json, MCP initialize, and /.well-known/*.
Hostname-based middleware routing for all subdomains
Policy source files and daily checking for cancel, return, and trial policies
Systems/Agents mode framing on landing page
MCP catalog with cards for all 4 servers
Fixed:
Daily policy checker: added contents:write permission and fixed shell logic
Removed dead Cloudflare email-decode scripts causing 404s
v1.1.0 (2026-02-01)
Added:
Expanded from 64 to 100 supported vendors
Daily policy-check GitHub Action (cron at 08:00 UTC)
Policy source URLs tracked in rules/policy-sources.json
MCP vendor enum in inputSchema for agent discoverability
Fixed:
ERR_IMPORT_ATTRIBUTE_MISSING crash on Vercel (Node 22 import attributes)
v1.0.0 (2026-01-15)
Added:
Initial release with REST API and MCP server
Support for 9 vendors
Public Policy APIs And Protected Decision API
All 4 policy servers are free to use. No authentication. No API keys.
The read-only policy support catalogue
lists per-policy US individual scopes as supported, review-only, observed-offer,
retired or degraded. Filter with ?policy=cancel&vendor=adobe. A known vendor
identifier is not a support promise: inspect the current scope status and the
actual decision's automation_safe, evidence and required context. Catalogue
reads neither evaluate a tool nor execute an action. Missing monitoring is
explicit, not reported as healthy. See the catalogue contract.
/api/decide requires a trusted proxy or API credential in production. Local and preview deployments can opt into the same boundary with DECIDE_API_AUTH_REQUIRED=1; configuring DECIDE_API_KEY or DECIDE_PROXY_SHARED_TOKEN also enables it.
If you run decide behind the decidesite proxy with dynamic customer keys, also set:
DECIDE_PROXY_SHARED_TOKEN: shared secret required in x-decide-proxy-token header for trusted proxy calls.
DECIDE_API_KEY: optional direct backend credential for trusted server-side callers.
DECIDE_GEMINI_MODE: defaults to disabled. In this hard-zero state, legacy advisory single, multi, and runtime requests return DECIDE_AI_DISABLED_ZERO_COST without reading an API key or making a provider request. Rulebook v1 remains available and never uses Gemini.
DECIDE_GEMINI_MODE=paid: explicit nonzero-cost opt-in for advisory modes. This mode also requires a restricted server-side GEMINI_API_KEY. DECIDE_GEMINI_MODEL may only be gemini-3.1-flash-lite; changing models requires a reviewed code release rather than an environment-only switch.
DECIDE_GEMINI_BUDGET_KV_REST_API_URL and DECIDE_GEMINI_BUDGET_KV_REST_API_TOKEN: dedicated Redis-compatible REST store for the atomic provider-attempt guard. Paid advisory fails closed before Gemini if this store is absent or unavailable. The legacy DECIDE_KV_REST_API_*/KV_REST_API_* names are compatibility fallbacks; dedicated credentials are preferred.
Compiled provider-attempt ceilings are 10/day, 100/month, 500 lifetime, and one concurrent request. DECIDE_GEMINI_DAILY_CALL_CAP, DECIDE_GEMINI_MONTHLY_CALL_CAP, and DECIDE_GEMINI_LIFETIME_CALL_CAP may only lower those ceilings.
DECIDE_GEMINI_TIMEOUT_MS: the single paid-mode provider deadline (defaults to and cannot exceed 8 seconds).
DECIDE_GEMINI_MAX_PROMPT_CHARS: the pre-fetch advisory prompt cap (defaults to and cannot exceed 4,096 characters; it may be lowered to 256).
Paid mode makes exactly one provider attempt and never falls back to another model. Gemini 3.1 Flash-Lite uses the provider's one-candidate default, lowest supported minimal thinking level, and default temperature; output is capped at 8 tokens for single, 128 for multi, and 512 for runtime. Keep the Gemini Google Cloud project unlinked from billing for a provider-side zero-dollar boundary; the application counters limit calls but do not prove a currency amount.
General /api/decide rate limit: 20 requests/minute per IP per serverless instance. This is an abuse control, not the Gemini cost boundary; the durable provider-attempt guard applies even when a trusted proxy bypasses the general limiter.
Authorization: Bearer <POLICY_CHECK_BROWSER_HOOK_TOKEN> or x-hook-token: <token>
Server env:
POLICY_CHECK_BROWSER_HOOK_TOKEN (required for endpoint auth)
POLICY_FETCH_CLOUDFLARE_ACCOUNT_ID and POLICY_FETCH_CLOUDFLARE_API_TOKEN (optional; enables Cloudflare Browser Run first, using a token limited to Browser Rendering Write)
POLICY_FETCH_CLOUDFLARE_CACHE_TTL_SECONDS (optional; defaults to 21600 seconds to reuse renders across policy types)
