@agenttax/mcp-server 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 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

@@ -115,12 +115,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`) when you know what you sold. 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 +140,7 @@ 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).
 
 ### Nexus
 

package/classify.js

@@ -0,0 +1,100 @@
+// How track_payment turns its arguments into a POST /api/v1/calculate body.
+// Kept apart from index.js (which starts the stdio server on import) so it can
+// be unit-tested.
+
+export const WORK_TYPES = ["compute", "research", "information_service", "content", "consulting", "trading"];
+
+// transaction_type sent for each work_type.
+export const WORK_TYPE_TO_TX_TYPE = {
+  compute: "compute",
+  research: "api_access",
+  information_service: "api_access",
+  content: "saas",
+  consulting: "consulting",
+  trading: "digital_good",
+};
+
+// 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,13 @@ 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, 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,7 +52,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",
@@ -108,7 +88,8 @@ 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.",
     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,7 +102,8 @@ 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). " +
+          "Pass it only when you know it: it is a declaration. consulting is an exempt professional service in Arizona"),
       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()
         .describe("Maryland only, with is_b2b=true: whether the purchase is solely for use in an enterprise computer system"),
@@ -150,35 +132,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 +172,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,8 +1,8 @@
 {
   "name": "@agenttax/mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.AgentTax/agenttax-mcp",
-  "description": "MCP server for AgentTax \u2014 US sales tax, nexus thresholds, capital gains and 1099-DA tools for AI agents",
+  "description": "MCP server for AgentTax — US sales tax, nexus thresholds, capital gains and 1099-DA tools for AI agents",
   "main": "index.js",
   "type": "module",
   "bin": {
@@ -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"
   },
   "keywords": [
     "1099-da",
@@ -35,7 +38,7 @@
   "homepage": "https://agenttax.io",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AgentTax/agenttax-mcp.git"
+    "url": "git+https://github.com/AgentTax/agenttax-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/AgentTax/agenttax-mcp/issues"

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.0",
+  "version": "1.2.0",
   "websiteUrl": "https://agenttax.io",
   "repository": {
     "url": "https://github.com/AgentTax/agenttax-mcp",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "@agenttax/mcp-server",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },