@agenttax/mcp-server 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 1.3.0
+
+Adds `intent` and documents `resolution` on `calculate_tax`. No result changes when you omit `intent`.
+
+Needs the AgentTax API release that accepts `intent` and returns `resolution` (live on agenttax.io since 2026-10-21). If you point `AGENTTAX_BASE_URL` at an older API, omit `intent`.
+
+- **New optional `intent` argument on `calculate_tax`** (`estimate` | `record`). `estimate` quotes a price before a wallet signs: it is computed and counts toward your monthly quota, but nothing is saved to transaction history, it never counts toward nexus revenue, and it ignores the Idempotency-Key. `record` (the default for keyed calls) logs the calculation as before. Keyless demo calls are always estimates. The server sends `intent` only when you pass it, so existing calls are byte-for-byte unchanged.
+- **`resolution` in the `calculate_tax` response** (from the same API deploy). `resolution.location`, `resolution.nexus` and `resolution.taxability` each report `status` (`resolved` | `partial` | `unknown`), `basis` and `detail`. `total_tax` is never withheld; to treat "unknown" as "do not charge", branch on `resolution.*.status`. The README has an example.
+- `calculate_tax` keeps its writing annotation (`readOnlyHint: false`): annotations are static and a keyed call without `intent: "estimate"` still writes to history.
+- **`work_type` accepts the five classification work types** on `calculate_tax` and `track_payment`: `payment_processing`, `web_hosting`, `software_maintenance`, `it_support`, `custom_software` (the API has accepted them since 2026-10-16; the 1.2.0 enum rejected them). `track_payment` maps each to its own `transaction_type` (`payment_processing_fee`, `web_hosting`, `software_maintenance`, `it_support`; `custom_software` is answered as a SaaS sale, since `track_payment` has no attestation). The Stripe webhook's `metadata.work_type` still accepts its five original values. Description guessing is unchanged and never produces these types.
+- **`calculate_tax` carries the classification facts** and passes them through to the API unchanged, all optional: `payment_provider_type` (with `transaction_type: "payment_processing_fee"`), `it_support_scope` (`it_support`), `includes_prewritten_software_access` (`web_hosting`), `custom_software_attestation` (required with `work_type: "custom_software"` for the custom-software answer) and `maintenance_contract` (`software_maintenance`, including `itemized_amounts`). Names, nesting, enum values and strictness match the API: an unknown key inside `custom_software_attestation`, `maintenance_contract` or `itemized_amounts` is refused before the call is sent. Without them the API gives its conservative default, as before.
+- **`transaction_type` accepts the four classification transaction types** on `calculate_tax` and `ingest_transactions`: `payment_processing_fee`, `web_hosting`, `software_maintenance`, `it_support` (the API has accepted them since 2026-10-16).
+- `payment_provider_type`, `it_support_scope`, `use_context` and `digital_content_type` on `calculate_tax` are trimmed and lowercased before the enum check, as the API does, so `"Bank "` is accepted and sent as `"bank"`. `ingest_transactions` records already pass the same facts through to the API.
+- The enums now live in `classify.js` and a test pins them to a copy of the API's values (`test/fixtures/api-calculate-enums.json`).
+- No other tool changed.
+
+## 1.2.0
+
+Tax-safety release for `track_payment`. Some results change; read before upgrading.
+
+- **Guessed consulting and trading are no longer exempt.** 1.1.1 guessed a work type from `description` and sent it as if you had declared it. A description that looked like consulting ("SOC 2 audit platform subscription", "tax advice") sold to an Arizona buyer came back $0 under the AZ professional-services exemption, and one that looked like trading ("game asset pack", "token swap fee") came back $0 in every state as a financial service. Both guesses are now taxed as SaaS. If the sale really is consulting or trading, pass `work_type` and the exemption applies as before.
+- **New optional `work_type` argument on `track_payment`** (`compute` | `research` | `information_service` | `content` | `consulting` | `trading`). It overrides the description and is treated as a declaration. Pass it for an exact answer.
+- **Guessed compute and research are unchanged** from 1.1.1. They are not exemptions, but those categories can tax less than SaaS in some states (e.g. CT, MD, SC, TN, WV). Pass `work_type` for an exact answer.
+- **`is_b2b` is sent only when you pass it.** 1.1.1 always sent `is_b2b: false`, which silently declared every buyer a consumer. Ohio sellers to consumers: pass `is_b2b: false`, or the sale is now taxed (Ohio exempts SaaS and data processing only for a declared consumer; an unknown buyer is taxed). With `is_b2b` omitted, AgentTax may also auto-detect a business buyer when the counterparty has a KYA principal record marked as a business, and apply B2B rules (e.g. Maryland 3%, Iowa B2B exemption); 1.1.1's explicit `false` blocked that. Pass `is_b2b` yourself if you know the buyer.
+- The `track_payment` response has a new `classification` field saying where the work type came from (`explicit`, `inferred_from_description` or `default`) and, when a consulting or trading guess was not used, a note telling you to resend with `work_type`.
+- No other tool changed. `calculate_tax` and `ingest_transactions` already sent only what you gave them.

package/README.md

@@ -59,8 +59,7 @@ Every payment is automatically classified, taxed, and logged. No code changes re
 ### Claude Code
 
 ```bash
-claude mcp add agenttax -- npx @agenttax/mcp-server
-export AGENTTAX_API_KEY=atx_live_your_key
+claude mcp add agenttax -e AGENTTAX_API_KEY=atx_live_your_key -- npx -y @agenttax/mcp-server
 ```
 
 ### Claude Desktop / Cursor / Windsurf
@@ -81,7 +80,7 @@ Add to your MCP config file:
 }
 ```
 
-Demo mode works without a key (50 calls/day, no account required). Tools marked "Yes" below need `AGENTTAX_API_KEY`.
+Demo mode works without a key (10 calls/day, no account required). Tools marked "Yes" below need `AGENTTAX_API_KEY`.
 
 ---
 
@@ -115,12 +114,15 @@ track_payment({
   buyer_state: "TX",
   buyer_zip: "78701",
   description: "MCP tool subscription",
+  work_type: "content",
   payment_id: "pi_stripe_abc123",
   source: "stripe"
 })
 ```
 
-Returns `tax_owed`, `tax_rate`, `taxable`, `transaction_id` and a `compliance_note`. Classification comes from `description`. Sellers get $0 in states where no nexus is configured; the response says so in `nexus_warning`.
+Returns `tax_owed`, `tax_rate`, `taxable`, `transaction_id`, a `classification` (where the work type came from) and a `compliance_note`. Sellers get $0 in states where no nexus is configured; the response says so in `nexus_warning`.
+
+**Pass `work_type` explicitly** (`compute` | `research` | `information_service` | `content` | `consulting` | `trading` | `payment_processing` | `web_hosting` | `software_maintenance` | `it_support` | `custom_software`) when you know what you sold. The last five are the classification work types the API added in October 2026: a payment or facilitator fee, hosting the buyer's own site, a software maintenance contract, IT support, and software written for one buyer. Each sends its own `transaction_type` and the API answers with that state's rule for it. It is a declaration and gives the exact answer, and it is the only way the consulting or trading exemption applies: for example, AI consulting sold to an Arizona buyer is an exempt professional service (A.R.S. §42-5061(A)(1), TPR 93-48), so `work_type: "consulting"` returns $0 in AZ. Without `work_type` the server guesses from `description`, but a guess never takes the consulting or trading exemption: a description that looks like consulting (e.g. "SOC 2 audit platform subscription") or trading is taxed as SaaS, and `classification.note` tells you to resend with `work_type` if the guess was right. A description that looks like compute or research keeps the 1.1.1 classification, which can tax less than SaaS in some states (e.g. CT, MD, SC, TN, WV); pass `work_type` for an exact answer. Leave `is_b2b` out when you don't know the buyer; `false` declares a consumer. Upgrading from 1.1.1? Some `track_payment` results change; see [CHANGELOG.md](CHANGELOG.md).
 
 ### calculate_tax
 
@@ -137,7 +139,48 @@ calculate_tax({
 })
 ```
 
-Optional fields: `seller_state` / `seller_zip` (origin-sourced intrastate sales in TX, UT, AZ, TN and some OH sales), `use_context` (Maryland B2B), `digital_content_type` (with `transaction_type: "digital_good"`), `seller_remitting`.
+Optional fields: `seller_state` / `seller_zip` (origin-sourced intrastate sales in TX, UT, AZ, TN and some OH sales), `use_context` (Maryland B2B), `digital_content_type` (with `transaction_type: "digital_good"`), `seller_remitting`. `transaction_type` and `work_type` are sent exactly as given and treated as declared facts; don't guess them (`consulting` is exempt in Arizona).
+
+**Classification facts** (optional; sent to the API as given, except that `payment_provider_type` and `it_support_scope` are trimmed and lowercased first, as the API does). Each one applies to one of the classification types; leave it out and the API gives its conservative default for that type.
+
+- `payment_provider_type` (`bank` | `licensed_money_transmitter` | `card_network` | `processor_routing_to_bank_or_network` | `other`), with `transaction_type: "payment_processing_fee"`: who provides the payment processing.
+- `it_support_scope` (`help_desk_advice` | `remote_repair_or_config` | `software_installation` | `monitoring` | `security_monitoring` | `managed_bundle`), with `it_support`: what the engagement is. Absent means `managed_bundle`.
+- `includes_prewritten_software_access` (boolean), with `transaction_type: "web_hosting"`: `true` when the plan gives the buyer vendor software beyond an incidental control panel or file manager (site builder, CMS or app platform, email or office suite, managed application).
+- `custom_software_attestation`, required with `work_type: "custom_software"`; without a complete one the sale is answered as prewritten software / SaaS. Required keys: `written_for_buyer`, `not_offered_to_others`, `deliverable` (`source_code` | `compiled_artifact` | `hosted`), `is_modification_of_prewritten`. Optional state facts: `separately_stated_charge`, `all_rights_transferred`, `delivery` (`electronic` | `tangible`), `il_requirements_analysis_and_adaptation`, `il_assembled_modules_50pct`.
+- `maintenance_contract`, with `transaction_type: "software_maintenance"`. All keys optional: `mandatory`, `includes_upgrades`, `includes_support`, `separately_itemized`, `itemized_amounts` (`{ updates, support }`, summing to `amount`), `update_delivery` (`electronic` | `tangible`), `support_kind` (`help_desk_only` | `includes_fixes`), `seller_sold_software`, `business_use`.
+
+Both objects are strict, as in the API: an unknown key is refused before the call is sent. The facts are your representation and are recorded with the transaction. `track_payment` does not take them; use `calculate_tax` when you have them. `ingest_transactions` records take the same facts per record and pass them through to the API, which validates them; leave them out and an ingested classification sale gets the conservative answer.
+
+```
+calculate_tax({
+  role: "seller", amount: 12000, buyer_state: "TX", counterparty_id: "client-42",
+  transaction_type: "saas", work_type: "custom_software",
+  custom_software_attestation: {
+    written_for_buyer: true, not_offered_to_others: true,
+    deliverable: "source_code", is_modification_of_prewritten: false
+  }
+})
+```
+
+**`intent`** (optional, `"estimate"` | `"record"`). Pass `"estimate"` to quote a price before a wallet signs. An estimate is computed and counts toward your monthly quota, but it is never saved to your transaction history, never counts toward nexus revenue, and ignores any idempotency key. With an API key and no `intent`, the call is a `"record"` and is logged. Keyless demo calls are always estimates. The server sends `intent` only when you pass it. It needs the AgentTax API release that accepts `intent` (live on agenttax.io since 2026-10-21).
+
+**`resolution`** in the response says how sure each part of the answer is. `resolution.location`, `resolution.nexus` and `resolution.taxability` each carry a `status` (`resolved`, `partial` or `unknown`), a `basis` (for example `zip_local_rate`, `state_only`, `no_nexus_profile`, `fact_not_declared`) and a `detail` sentence. `total_tax` is always returned, never withheld. If your rule is "unknown means do not charge", branch on the status yourself:
+
+```js
+// Pseudo-code. quote = the parsed JSON result of the calculate_tax tool call
+const price = 20;
+const quote = await calculate_tax({
+  role: "seller", amount: price, buyer_state: "NY", buyer_zip: "10001",
+  transaction_type: "saas", counterparty_id: "buyer-agent-7", intent: "estimate"
+});
+
+if (quote.resolution.nexus.status === "unknown") {
+  // No nexus profile configured: total_tax may be $0 only because nexus was never set up.
+  // Run configure_nexus, or hold the sale for review, instead of charging $0.
+} else {
+  charge(price + quote.total_tax);
+}
+```
 
 ### Nexus
 
@@ -165,7 +208,7 @@ curl -X POST https://agenttax.io/api/v1/auth/signup \
   -d '{"email": "you@example.com", "password": "securepass", "agent_name": "my-mcp-server", "agent_work_type": "compute"}'
 ```
 
-All four fields are required; `agent_work_type` is one of `compute`, `research`, `information_service`, `content`, `consulting`, `trading`. Save the `api_key.key` from the response — it's only shown once.
+All four fields are required; `agent_work_type` is one of `compute`, `research`, `information_service`, `content`, `consulting`, `trading`, `payment_processing`, `web_hosting`, `software_maintenance`, `it_support`, `custom_software`. Save the `api_key.key` from the response — it's only shown once.
 
 ## Pricing
 

package/classify.js

@@ -0,0 +1,207 @@
+// How track_payment turns its arguments into a POST /api/v1/calculate body,
+// plus the enums and classification-fact schema calculate_tax shares with the
+// API. Kept apart from index.js (which starts the stdio server on import) so
+// it can be unit-tested.
+
+import { z } from "zod";
+
+// The work types the AgentTax API accepts (api/_lib/schemas/common.js
+// WORK_TYPES). 1.3.0 adds the five classification work types the API has
+// taken since 2026-10-16; before this the zod enum rejected them, so an MCP
+// caller could not declare a payment fee, hosting, maintenance, IT support or
+// custom software at all. The API decides taxability; nothing here does.
+export const WORK_TYPES = [
+  "compute", "research", "information_service", "content", "consulting", "trading",
+  "payment_processing", "web_hosting", "software_maintenance", "it_support", "custom_software",
+];
+
+// The transaction types the AgentTax API accepts (api/_lib/schemas/common.js
+// TRANSACTION_TYPES), including the four classification types the API has
+// taken since 2026-10-16.
+export const TRANSACTION_TYPES = [
+  "compute", "api_access", "data_purchase", "saas", "ai_labor", "storage",
+  "digital_good", "consulting", "data_processing", "cloud_infrastructure",
+  "ai_model_access", "marketplace_fee", "subscription", "license", "service",
+  "payment_processing_fee", "web_hosting", "software_maintenance", "it_support",
+];
+
+// digital_content_type values (api/_lib/schemas/common.js DIGITAL_CONTENT_TYPES).
+export const DIGITAL_CONTENT_TYPES = [
+  "ebook", "audio", "video", "art_image", "photograph", "printable_document", "software", "data", "other",
+];
+
+// Classification-fact enums, copied from api/_lib/schemas/common.js. Pinned
+// against the API by test/enum-parity.test.js.
+export const PAYMENT_PROVIDER_TYPES = [
+  "bank", "licensed_money_transmitter", "card_network", "processor_routing_to_bank_or_network", "other",
+];
+export const IT_SUPPORT_SCOPES = [
+  "help_desk_advice", "remote_repair_or_config", "software_installation", "monitoring", "security_monitoring", "managed_bundle",
+];
+export const MAINTENANCE_UPDATE_DELIVERY = ["electronic", "tangible"];
+export const MAINTENANCE_SUPPORT_KINDS = ["help_desk_only", "includes_fixes"];
+export const CUSTOM_SOFTWARE_DELIVERABLES = ["source_code", "compiled_artifact", "hosted"];
+export const CUSTOM_SOFTWARE_DELIVERY = ["electronic", "tangible"];
+
+// The API trims and lowercases these string facts before its enum check
+// (api/_lib/schemas/calculate.js: .trim().transform(toLowerCase).pipe(z.enum)),
+// so "Bank " is valid there. Mirror that here, the way index.js stateCode
+// uppercases, so the MCP layer does not refuse what the API accepts. The
+// normalised value is what gets forwarded. The published JSON Schema still
+// shows the enum.
+export const lowerEnum = (values) =>
+  z.preprocess((v) => (typeof v === "string" ? v.trim().toLowerCase() : v), z.enum(values));
+
+// The optional classification facts calculate_tax forwards to the API.
+// Names, nesting, enum values and strictness match calculateRequest in
+// api/_lib/schemas/calculate.js; the API decides what each fact does to the
+// answer. Every field is optional: absent means the API's conservative
+// default.
+export const CLASSIFICATION_FACTS_SHAPE = {
+  payment_provider_type: lowerEnum(PAYMENT_PROVIDER_TYPES).optional()
+    .describe("With transaction_type payment_processing_fee: who provides the payment processing. " +
+      "Changes the answer in some states; absent = the conservative answer. Your representation, recorded with the transaction"),
+  it_support_scope: lowerEnum(IT_SUPPORT_SCOPES).optional()
+    .describe("With transaction_type or work_type it_support: what the remote IT support engagement is. " +
+      "Absent = managed_bundle, the per-state default; some states answer specific scopes differently"),
+  includes_prewritten_software_access: z.boolean().optional()
+    .describe("With transaction_type web_hosting: true when the plan gives the buyer vendor prewritten software beyond an incidental " +
+      "control panel or file manager (site builder, CMS or app platform, email or office suite, managed application). " +
+      "Absent or false = plain hosting of the buyer's own site or application"),
+  custom_software_attestation: z.object({
+    written_for_buyer: z.boolean(),
+    not_offered_to_others: z.boolean(),
+    deliverable: z.enum(CUSTOM_SOFTWARE_DELIVERABLES),
+    is_modification_of_prewritten: z.boolean(),
+    separately_stated_charge: z.boolean().optional(),
+    all_rights_transferred: z.boolean().optional(),
+    delivery: z.enum(CUSTOM_SOFTWARE_DELIVERY).optional(),
+    il_requirements_analysis_and_adaptation: z.boolean().optional(),
+    il_assembled_modules_50pct: z.boolean().optional(),
+  }).strict().optional()
+    .describe("Required with work_type custom_software; without a complete attestation the sale is answered as prewritten software / SaaS. " +
+      "Complete = written_for_buyer true, not_offered_to_others true, deliverable source_code or compiled_artifact (hosted is SaaS), " +
+      "is_modification_of_prewritten set, and separately_stated_charge true when it is a modification. The other fields are state-specific facts. " +
+      "Your representation, recorded with the transaction; not a state safe harbor"),
+  maintenance_contract: z.object({
+    mandatory: z.boolean().optional(),
+    includes_upgrades: z.boolean().optional(),
+    includes_support: z.boolean().optional(),
+    separately_itemized: z.boolean().optional(),
+    update_delivery: z.enum(MAINTENANCE_UPDATE_DELIVERY).optional(),
+    support_kind: z.enum(MAINTENANCE_SUPPORT_KINDS).optional(),
+    seller_sold_software: z.boolean().optional(),
+    business_use: z.boolean().optional(),
+    itemized_amounts: z.object({
+      updates: z.number().nonnegative().finite(),
+      support: z.number().nonnegative().finite(),
+    }).strict().optional(),
+  }).strict().optional()
+    .describe("With transaction_type software_maintenance: facts about a maintenance contract on prewritten software. Every field is optional; " +
+      "a missing fact is answered conservatively (updates assumed included). separately_itemized + itemized_amounts {updates, support} " +
+      "(summing to amount) split the charge where a state taxes the parts differently"),
+};
+
+// transaction_type sent for each work_type. The classification work types
+// have their own transaction types (AGENTS.md "Classification facts");
+// custom_software is a work_type on a SaaS/service sale, and without a
+// complete custom_software_attestation the API answers it as prewritten
+// software or SaaS, which is the conservative default a payment log wants.
+export const WORK_TYPE_TO_TX_TYPE = {
+  compute: "compute",
+  research: "api_access",
+  information_service: "api_access",
+  content: "saas",
+  consulting: "consulting",
+  trading: "digital_good",
+  payment_processing: "payment_processing_fee",
+  web_hosting: "web_hosting",
+  software_maintenance: "software_maintenance",
+  it_support: "it_support",
+  custom_software: "saas",
+};
+
+// Work types that, in the AgentTax engine, can route a sale to an exemption:
+//   consulting -> exempt professional service in Arizona (A.R.S. 42-5061(A)(1),
+//                 TPR 93-48), and the engine also exempts AZ when only
+//                 transaction_type "consulting" is sent;
+//   trading    -> financial_service, exempt in every state.
+// The engine grants these only on a DECLARED fact. The public calculate API
+// has no way to mark a work type as guessed, so a keyword match on the
+// description must never send either one. A guess that lands here is
+// treated as unclassified (the same default as a description with no
+// keyword), which is taxed the way the engine taxes SaaS.
+export const EXEMPTION_BEARING_WORK_TYPES = new Set(["consulting", "trading"]);
+
+// Guess a work type from a plain-English description. Returns null when no
+// keyword matches. A guess is a hint only: see buildTrackPaymentRequest.
+export function guessWorkType(description) {
+  if (!description) return null;
+  const d = description.toLowerCase();
+  if (/\b(compute|inference|gpu|process|api[\s-]?call|token)\b/.test(d)) return "compute";
+  if (/\b(research|analysis|analytics|data[\s-]?(process|feed))\b/.test(d)) return "research";
+  if (/\b(consult|consulting|advisory|advice|audit)\b/.test(d)) return "consulting";
+  if (/\b(trade|trading|swap|asset)\b/.test(d)) return "trading";
+  return null;
+}
+
+// Returns { body, classification } where body is the calculate request and
+// classification says where the work type came from.
+//
+//   explicit work_type          -> sent as work_type, with its transaction_type
+//   guessed compute / research  -> sent as in 1.1.1. Not an exemption, but their
+//                                  categories can tax less than SaaS in some states
+//                                  (e.g. CT, MD, SC, TN, WV); changing that is a
+//                                  tax-value decision, so it is left as is.
+//   guessed consulting/trading  -> NOT sent; transaction_type "saas", no work_type
+//   no guess                    -> transaction_type "saas", no work_type
+//   is_b2b                      -> sent only when the caller passed a boolean
+export function buildTrackPaymentRequest(params, { now = Date.now } = {}) {
+  const counterpartyId = params.payment_id || `payment_${now()}`;
+  let workType;
+  let transactionType;
+  let classification;
+
+  if (params.work_type) {
+    workType = params.work_type;
+    transactionType = WORK_TYPE_TO_TX_TYPE[workType] || "saas";
+    classification = { source: "explicit", work_type: workType };
+  } else {
+    const guess = guessWorkType(params.description);
+    if (guess && !EXEMPTION_BEARING_WORK_TYPES.has(guess)) {
+      workType = guess;
+      transactionType = WORK_TYPE_TO_TX_TYPE[guess];
+      classification = { source: "inferred_from_description", work_type: guess };
+    } else {
+      workType = undefined; // let the API default from transaction_type
+      transactionType = "saas";
+      classification = guess
+        ? {
+            source: "default",
+            work_type: null,
+            guess_not_used: guess,
+            note:
+              `The description looks like "${guess}", but a guess never takes the ${guess} exemption, so this sale was ` +
+              `taxed as a SaaS / digital service. If the sale really is ${guess}, call track_payment again with ` +
+              `work_type: "${guess}".`,
+          }
+        : { source: "default", work_type: null };
+    }
+  }
+
+  const body = {
+    role: "seller",
+    amount: params.amount,
+    buyer_state: params.buyer_state,
+    buyer_zip: params.buyer_zip,
+    transaction_type: transactionType,
+    counterparty_id: counterpartyId,
+  };
+  if (workType) body.work_type = workType;
+  // Send is_b2b only when the caller said. The API treats a present
+  // is_b2b:false as a DECLARED consumer, which takes explicit-only consumer
+  // exemptions (e.g. Ohio SaaS, R.C. 5739.01(B)(3)(e)); an unknown buyer must
+  // stay unknown so it is taxed conservatively.
+  if (typeof params.is_b2b === "boolean") body.is_b2b = params.is_b2b;
+  return { body, classification };
+}

package/index.js

@@ -4,32 +4,15 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "node:module";
 import { z } from "zod";
+import {
+  WORK_TYPES, TRANSACTION_TYPES, DIGITAL_CONTENT_TYPES, CLASSIFICATION_FACTS_SHAPE, lowerEnum, buildTrackPaymentRequest,
+} from "./classify.js";
 
 const { version: PKG_VERSION } = createRequire(import.meta.url)("./package.json");
 
 const BASE_URL = process.env.AGENTTAX_BASE_URL || "https://agenttax.io";
 const API_KEY = process.env.AGENTTAX_API_KEY || "";
 
-// Classify work type from a plain-English description.
-// Developers can describe what they sold and we auto-classify for tax purposes.
-function classifyWorkType(description) {
-  if (!description) return "content";
-  const d = description.toLowerCase();
-  if (/\b(compute|inference|gpu|process|api[\s-]?call|token)\b/.test(d)) return "compute";
-  if (/\b(research|analysis|analytics|data[\s-]?(process|feed))\b/.test(d)) return "research";
-  if (/\b(consult|advisory|advice|audit)\b/.test(d)) return "consulting";
-  if (/\b(trade|trading|swap|asset)\b/.test(d)) return "trading";
-  return "content"; // Default: SaaS / digital service
-}
-
-const WORK_TYPE_TO_TX_TYPE = {
-  compute: "compute",
-  research: "api_access",
-  content: "saas",
-  consulting: "consulting",
-  trading: "digital_good",
-};
-
 async function apiCall(method, path, body = null) {
   const headers = { "Content-Type": "application/json" };
   if (API_KEY) headers["X-API-Key"] = API_KEY;
@@ -71,16 +54,6 @@ const STATES = [
 const stateCode = z.preprocess((v) => (typeof v === "string" ? v.toUpperCase() : v), z.enum(STATES));
 const zip5 = z.string().regex(/^\d{5}$/);
 
-const WORK_TYPES = ["compute", "research", "information_service", "content", "consulting", "trading"];
-const TRANSACTION_TYPES = [
-  "compute", "api_access", "data_purchase", "saas", "ai_labor", "storage",
-  "digital_good", "consulting", "data_processing", "cloud_infrastructure",
-  "ai_model_access", "marketplace_fee", "subscription", "license", "service",
-];
-const DIGITAL_CONTENT_TYPES = [
-  "ebook", "audio", "video", "art_image", "photograph", "printable_document", "software", "data", "other",
-];
-
 const jsonResult = (result) => ({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
 
 function withQuery(path, params) {
@@ -108,7 +81,12 @@ server.registerTool(
     description:
       "Calculate US sales tax (seller) or use tax (buyer) for an AI agent transaction. Returns tax amount, rate, jurisdiction, " +
       "audit trail, confidence score, and advisories. Sellers get $0 sales tax in states without configured nexus " +
-      "(see configure_nexus); a $0 total means no collection obligation, not necessarily no tax, so read nexus_warning and advisories.",
+      "(see configure_nexus); a $0 total means no collection obligation, not necessarily no tax, so read nexus_warning and advisories. " +
+      "work_type and transaction_type are sent as you give them and treated as declared facts (e.g. consulting is exempt in Arizona), so do not guess them. " +
+      "The response carries resolution.location / resolution.nexus / resolution.taxability, each with status resolved, partial or unknown plus a basis; " +
+      "total_tax is always returned, so if you want \"unknown means do not charge\", branch on resolution.*.status. " +
+      "Pass intent \"estimate\" to quote before a wallet signs: nothing is saved to history or nexus revenue, but it counts toward your monthly quota. " +
+      "Without intent (or with \"record\"), a keyed call is logged to your history, which is why this tool is annotated as writing even for estimates.",
     inputSchema: {
       role: z.enum(["buyer", "seller"]).describe("Your role in the transaction"),
       amount: z.number().positive().max(100_000_000).describe("Transaction amount in USD"),
@@ -121,15 +99,25 @@ server.registerTool(
       seller_zip: zip5.optional()
         .describe("Seller's 5-digit zip. Required for TX/UT/AZ/TN origin-sourced intrastate sales and intrastate OH license/digital_good sales"),
       work_type: z.enum(WORK_TYPES).optional()
-        .describe("What the agent's work is economically; drives per-state taxability (compute, research, information_service, content, consulting, trading)"),
+        .describe("What the agent's work is economically; drives per-state taxability (compute, research, information_service, content, consulting, trading, " +
+          "payment_processing, web_hosting, software_maintenance, it_support, custom_software). " +
+          "Pass it only when you know it: it is a declaration. consulting is an exempt professional service in Arizona. " +
+          "custom_software needs a complete custom_software_attestation, or it is answered as prewritten software / SaaS"),
       is_b2b: z.boolean().optional().describe("Business-to-business transaction (triggers state B2B rules, e.g. IA, MD)"),
-      use_context: z.enum(["enterprise_system", "individual", "mixed"]).optional()
+      use_context: lowerEnum(["enterprise_system", "individual", "mixed"]).optional()
         .describe("Maryland only, with is_b2b=true: whether the purchase is solely for use in an enterprise computer system"),
-      digital_content_type: z.enum(DIGITAL_CONTENT_TYPES).optional()
+      digital_content_type: lowerEnum(DIGITAL_CONTENT_TYPES).optional()
         .describe("With transaction_type digital_good: what the download is. Several states tax e-books, music and video but not digital art or printables"),
       seller_remitting: z.boolean().optional().describe("Buyer side: whether the seller is already collecting the tax"),
+      intent: z.enum(["estimate", "record"]).optional()
+        .describe("\"estimate\" = quote before a wallet signs; nothing is saved to history or nexus revenue; counts toward your quota. " +
+          "\"record\" (the default with an API key) logs the calculation. Keyless demo calls are always estimates. Omit it if your AgentTax API does not accept intent yet"),
+      // Classification facts for the five classification work types. Optional;
+      // forwarded verbatim like every other argument.
+      ...CLASSIFICATION_FACTS_SHAPE,
     },
-    annotations: WRITES, // with an API key the calculation is logged to your history
+    // Static annotation: with an API key and no intent "estimate", the calculation is logged to your history.
+    annotations: WRITES,
   },
   async (params) => {
     try {
@@ -150,35 +138,28 @@ server.registerTool(
     title: "Track a payment you received",
     description:
       "Track a payment you received and calculate your sales tax liability. Call this after receiving any payment — Stripe, x402, or direct. " +
-      "Classifies the sale from its description, calculates tax owed, and logs it to your AgentTax account (requires API key for history).",
+      "Calculates tax owed and logs it to your AgentTax account (requires API key for history). " +
+      "Pass work_type when you know what you sold, for an exact answer; it is the only way to get the consulting exemption (AI consulting is exempt in Arizona) or the trading exemption. " +
+      "Without it the sale is classified from description: a description that looks like consulting or trading is taxed as SaaS, never exempt; " +
+      "one that looks like compute or research keeps that classification, which can tax less than SaaS in some states (e.g. CT, MD, SC, TN, WV).",
     inputSchema: {
       amount: z.number().positive().max(100_000_000).describe("Payment amount in USD"),
       buyer_state: stateCode.describe("2-letter US state where the buyer is located (e.g. TX, NY, CA)"),
       buyer_zip: zip5.optional().describe("Buyer's 5-digit zip code for local tax rates (more precise)"),
-      description: z.string().optional().describe("What you sold — used to classify the transaction (e.g. 'API access', 'MCP tool subscription', 'compute credits', 'AI consulting')"),
+      description: z.string().optional().describe("What you sold (e.g. 'API access', 'MCP tool subscription', 'compute credits'). Used only when work_type is not given; a guess never takes the consulting or trading exemption"),
+      work_type: z.enum(WORK_TYPES).optional()
+        .describe("What you sold, declared: compute, research, information_service, content, consulting, trading. Overrides description. consulting is an exempt professional service in Arizona"),
       payment_id: z.string().regex(/^[A-Za-z0-9_\-.:@]{1,200}$/).optional()
         .describe("Your payment reference ID (Stripe payment_intent ID, x402 receipt, invoice number); letters, digits and _-.:@ only"),
       source: z.enum(["stripe", "x402", "direct", "other"]).optional().describe("Payment processor used"),
-      is_b2b: z.boolean().optional().describe("Buyer is a business (affects rates in MD, IA, NJ)"),
+      is_b2b: z.boolean().optional().describe("Buyer is a business (affects rates in MD, IA, NJ, OH). Omit if unknown: false declares a consumer"),
     },
     annotations: WRITES,
   },
   async (params) => {
     try {
-      const workType = classifyWorkType(params.description);
-      const transactionType = WORK_TYPE_TO_TX_TYPE[workType] || "saas";
-      const counterpartyId = params.payment_id || `payment_${Date.now()}`;
-
-      const result = await apiCall("POST", "/api/v1/calculate", {
-        role: "seller",
-        amount: params.amount,
-        buyer_state: params.buyer_state,
-        buyer_zip: params.buyer_zip,
-        transaction_type: transactionType,
-        work_type: workType,
-        counterparty_id: counterpartyId,
-        is_b2b: params.is_b2b || false,
-      });
+      const { body, classification } = buildTrackPaymentRequest(params);
+      const result = await apiCall("POST", "/api/v1/calculate", body);
 
       if (!result.success) {
         return {
@@ -197,6 +178,7 @@ server.registerTool(
         tax_rate: result.sales_tax?.rate || result.combined_rate || 0,
         taxable: taxOwed > 0,
         work_type: result.work_type,
+        classification,
         transaction_id: result.transaction_id,
         nexus_warning: result.nexus_warning,
         compliance_note: taxOwed > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenttax/mcp-server",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "mcpName": "io.github.AgentTax/agenttax-mcp",
   "description": "MCP server for AgentTax — US sales tax, nexus thresholds, capital gains and 1099-DA tools for AI agents",
   "main": "index.js",
@@ -10,12 +10,15 @@
   },
   "files": [
     "index.js",
+    "classify.js",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "server.json"
   ],
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "test": "node --test test/track-payment.test.js test/tools.test.js test/enum-parity.test.js test/calculate-facts.test.js"
   },
   "keywords": [
     "1099-da",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.AgentTax/agenttax-mcp",
   "title": "AgentTax",
   "description": "US sales/use tax, nexus thresholds, capital gains and 1099-DA tools for AI agent transactions.",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "websiteUrl": "https://agenttax.io",
   "repository": {
     "url": "https://github.com/AgentTax/agenttax-mcp",
@@ -13,14 +13,14 @@
     {
       "registryType": "npm",
       "identifier": "@agenttax/mcp-server",
-      "version": "1.1.1",
+      "version": "1.3.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "AGENTTAX_API_KEY",
-          "description": "AgentTax API key (free tier at agenttax.io). Optional: without it the server runs in demo mode, 50 calls/day.",
+          "description": "AgentTax API key (free tier at agenttax.io). Optional: without it the server runs in demo mode, 10 calls/day.",
           "isRequired": false,
           "isSecret": true
         }