profitlee-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LEE I HSIU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# profitlee-mcp
+
+[![npm version](https://img.shields.io/npm/v/profitlee-mcp.svg)](https://www.npmjs.com/package/profitlee-mcp)
+[![license](https://img.shields.io/npm/l/profitlee-mcp.svg)](./LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server for [Profitlee](https://profitlee.com) — compute **country-accurate Amazon FBA/FBM and TikTok Shop profit margins**, and manage saved scenarios, from any MCP client (Claude Desktop, Claude Code, Cursor, …).
+
+`calculate_profit` is **free and needs no token**. The scenario tools require a Profitlee Pro API token.
+
+> MCP registry name: `io.github.aronleedev/profitlee-mcp`
+
+## Quick start
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "profitlee": {
+      "command": "npx",
+      "args": ["-y", "profitlee-mcp"],
+      "env": {
+        "PROFITLEE_API_TOKEN": "eck_live_xxx"
+      }
+    }
+  }
+}
+```
+
+`PROFITLEE_API_TOKEN` is **optional** — omit the whole `env` block to use `calculate_profit` only. Create a token on your Profitlee [account page](https://profitlee.com/account) to unlock the scenario tools.
+
+Requires Node.js 20+.
+
+## Tools
+
+| Tool | Auth | Description |
+| --- | --- | --- |
+| `calculate_profit` | none | Full per-unit cost stack, gross/net margin, and monthly P&L. |
+| `list_scenarios` | Pro token | List your saved scenarios. |
+| `get_scenario` | Pro token | Read one scenario (inputs + outputs) by id. |
+| `save_scenario` | Pro token | Save a named scenario from calculator inputs. |
+| `update_scenario` | Pro token | Rename and/or replace a scenario's inputs. |
+| `delete_scenario` | Pro token | Delete a scenario by id. |
+
+### `calculate_profit` inputs
+
+Pick a `platform` + `mode`, give the product's physical and cost details, and Profitlee folds every fee into a single net margin. Rates are **0–1 decimals** (e.g. `0.15` = 15%). US uses inches + pounds; DE/JP use cm + kg.
+
+| Field | Notes |
+| --- | --- |
+| `platform` | `amazon` (default) or `tiktok_shop`. |
+| `region` | `us`, `de`, or `jp`. |
+| `mode` | amazon: `fba` \| `fbm`. tiktok_shop: `fbt` \| `self_fulfilled`. |
+| `L`, `W`, `H`, `weight` | Dimensions + unit weight. |
+| `fob`, `headShip`, `duty` | Unit cost, inbound freight/unit, import duty/unit. |
+| `price` | Selling price (gross; VAT-inclusive for DE/JP). |
+| `ppcAcos`, `returnRate` | Ad ACoS and return rate (0–1). |
+| `monthlyVolume` | Units/month (scales the P&L). |
+| `referralPct` | Referral fee (0–1). Preferred over `referralCategory`. |
+| `isApparel` | Affects some fees. |
+| mode-specific | FBA: `inboundOption`, `storageMonths`, `storageSeason`. FBM / TikTok self-fulfilled: `outboundShipPerUnit`, `pickPackPerUnit`, `monthly3plStorage`. TikTok FBT: `storageMonthsPastFree`. |
+
+The Profitlee API is the source of truth for validation — incomplete or out-of-range inputs come back as a clear error listing the offending fields. Full field reference: <https://profitlee.com/docs/api>.
+
+## Environment variables
+
+| Var | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `PROFITLEE_API_TOKEN` | No | — | Pro token (`eck_live_…`); needed only for the scenario tools. |
+| `PROFITLEE_BASE_URL` | No | `https://profitlee.com` | Override the API origin (testing). |
+
+## How it works
+
+The server is a thin wrapper over Profitlee's public HTTP API:
+
+- `calculate_profit` → `POST /api/v1/calculate` (public, no token).
+- scenario tools → `/api/v1/scenarios*` (require the Pro token; the server fails fast with a clear message if it's missing).
+
+No fee logic is reimplemented here, so results always match the live Profitlee calculator and current fee tables.
+
+## Development
+
+```bash
+npm install
+npm test       # vitest (27 tests)
+npm run build  # tsc -> dist/
+npm run dev    # run from source with tsx
+```
+
+## Releasing
+
+Maintainers: see [PUBLISHING.md](./PUBLISHING.md) for npm publish + MCP registry steps. The registry manifest lives in [server.json](./server.json).
+
+## License
+
+[MIT](./LICENSE)

package/dist/client.js

@@ -0,0 +1,55 @@
+/** Error type for every failure surfaced to the MCP caller. */
+export class ProfitleeError extends Error {
+}
+/** Stable API `reason` codes to human messages. See https://profitlee.com/docs/api. */
+const REASON_MESSAGES = {
+    auth_required: "Set PROFITLEE_API_TOKEN to a valid Pro API token.",
+    invalid_token: "PROFITLEE_API_TOKEN is not valid. Check it on your Profitlee account page.",
+    pro_required: "Saved scenarios require a Profitlee Pro plan.",
+    scenario_limit: "You've reached the saved-scenario limit. Delete one before creating another.",
+    invalid_input: "The calculator inputs failed validation.",
+    invalid_json: "The request body was not valid JSON.",
+    not_found: "Scenario not found.",
+};
+/** Abort a request that takes longer than this so a hung API can't hang the tool call. */
+const REQUEST_TIMEOUT_MS = 15_000;
+export async function apiRequest(config, opts) {
+    const headers = { "content-type": "application/json" };
+    if (opts.auth) {
+        if (!config.apiToken) {
+            throw new ProfitleeError("This action needs a Pro API token. Set PROFITLEE_API_TOKEN.");
+        }
+        headers.authorization = `Bearer ${config.apiToken}`;
+    }
+    let res;
+    try {
+        res = await fetch(`${config.baseUrl}${opts.path}`, {
+            method: opts.method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : "network error";
+        throw new ProfitleeError(`Could not reach Profitlee (${detail}).`);
+    }
+    const text = await res.text();
+    let json;
+    if (text) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // Leave undefined; HTTP status handling below still reports the failure.
+        }
+    }
+    if (!res.ok) {
+        const obj = (json ?? {});
+        const base = (obj.reason && REASON_MESSAGES[obj.reason]) || `Profitlee request failed (HTTP ${res.status}).`;
+        const limit = typeof obj.limit === "number" ? ` (limit ${obj.limit})` : "";
+        const issues = obj.issues ? ` Issues: ${JSON.stringify(obj.issues)}` : "";
+        throw new ProfitleeError(base + limit + issues);
+    }
+    return json;
+}

package/dist/config.js

@@ -0,0 +1,5 @@
+export function loadConfig(env = process.env) {
+    const baseUrl = (env.PROFITLEE_BASE_URL ?? "https://profitlee.com").replace(/\/+$/, "");
+    const token = env.PROFITLEE_API_TOKEN?.trim();
+    return { baseUrl, apiToken: token ? token : undefined };
+}

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { registerCalculateTool } from "./tools/calculate.js";
+import { registerScenarioTools } from "./tools/scenarios.js";
+async function main() {
+    const config = loadConfig();
+    const server = new McpServer({ name: "profitlee-mcp", version: "0.1.0" });
+    registerCalculateTool(server, config);
+    registerScenarioTools(server, config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("profitlee-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("profitlee-mcp failed to start:", err);
+    process.exit(1);
+});

package/dist/result.js

@@ -0,0 +1,12 @@
+import { ProfitleeError } from "./client.js";
+/** Run an async producer; serialize success to JSON text, map errors to an error result. */
+export async function toToolResult(fn) {
+    try {
+        const value = await fn();
+        return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+    }
+    catch (e) {
+        const msg = e instanceof ProfitleeError ? e.message : e instanceof Error ? e.message : String(e);
+        return { content: [{ type: "text", text: msg }], isError: true };
+    }
+}

package/dist/schemas.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/**
+ * Flat, richly-described shape for calculator inputs. Mode-specific fields are
+ * optional here; the Profitlee API remains the strict validation authority.
+ *
+ * Units: US uses inches and pounds; DE/JP use cm and kg. All rates are 0-1 decimals.
+ */
+export const calcInputShape = {
+    platform: z.enum(["amazon", "tiktok_shop"]).default("amazon").describe("Sales platform. Default: amazon."),
+    region: z.enum(["us", "de", "jp"]).describe("Marketplace. US uses inches+pounds; DE/JP use cm+kg."),
+    mode: z
+        .enum(["fba", "fbm", "fbt", "self_fulfilled"])
+        .describe("Fulfillment mode. amazon: fba or fbm. tiktok_shop: fbt or self_fulfilled."),
+    L: z.number().positive().describe("Length. US: inches; DE/JP: cm."),
+    W: z.number().positive().describe("Width. US: inches; DE/JP: cm."),
+    H: z.number().positive().describe("Height. US: inches; DE/JP: cm."),
+    weight: z.number().positive().describe("Unit weight. US: pounds; DE/JP: kg."),
+    fob: z.number().nonnegative().describe("Unit manufacturing / FOB cost in the marketplace currency."),
+    headShip: z.number().nonnegative().describe("Inbound freight cost allocated per unit."),
+    duty: z.number().nonnegative().describe("Import duty per unit."),
+    price: z.number().min(0.01).describe("Selling price per unit (gross; VAT-inclusive for DE/JP)."),
+    ppcAcos: z.number().min(0).max(1).describe("Advertising ACoS as a 0-1 decimal (0.15 = 15%)."),
+    adSalesShare: z.number().min(0).max(1).optional().describe("Ad-attributed share of sales, 0-1. Omit to default to 1."),
+    returnRate: z.number().min(0).max(1).describe("Return rate as a 0-1 decimal (0.05 = 5%)."),
+    unsellableReturnRate: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Unsellable share of returned units, 0-1. Omit to default to 1."),
+    monthlyVolume: z.number().int().nonnegative().describe("Units sold per month."),
+    referralPct: z.number().min(0).max(1).describe("Referral/commission fee as a 0-1 decimal (0.15 = 15%). Preferred."),
+    referralCategory: z
+        .string()
+        .nullish()
+        .describe("Advanced: a category slug that overrides referralPct. Leave unset and use referralPct."),
+    isApparel: z.boolean().describe("Whether the product is apparel (affects some fees)."),
+    inboundOption: z.enum(["optimized", "partial", "single"]).optional().describe("Amazon FBA only: inbound placement option."),
+    storageMonths: z.number().positive().optional().describe("Amazon FBA only: number of months in storage."),
+    storageSeason: z.enum(["janSep", "octDec"]).optional().describe("Amazon FBA only: storage season (octDec is the Q4 peak)."),
+    outboundShipPerUnit: z.number().nonnegative().optional().describe("FBM or TikTok self_fulfilled: outbound shipping per unit."),
+    pickPackPerUnit: z.number().nonnegative().optional().describe("FBM or TikTok self_fulfilled: pick & pack per unit."),
+    monthly3plStorage: z.number().nonnegative().optional().describe("FBM or TikTok self_fulfilled: total monthly 3PL storage."),
+    storageMonthsPastFree: z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe("TikTok fbt only: months stored past the 60-day free window (0 if shipped before it ends)."),
+};
+/** Object form for runtime parsing of calculator inputs. */
+export const calcInputObject = z.object(calcInputShape);

package/dist/tools/calculate.js

@@ -0,0 +1,21 @@
+import { apiRequest } from "../client.js";
+import { toToolResult } from "../result.js";
+import { calcInputShape } from "../schemas.js";
+/** Core calculate call: public endpoint, no token. Returns the `result` object. */
+export async function runCalculate(config, args) {
+    const out = await apiRequest(config, {
+        method: "POST",
+        path: "/api/v1/calculate",
+        body: args,
+        auth: false,
+    });
+    return out.result;
+}
+export function registerCalculateTool(server, config) {
+    server.registerTool("calculate_profit", {
+        title: "Calculate profit",
+        description: "Compute the full per-unit cost stack, gross/net margin, and monthly P&L for an Amazon FBA/FBM or TikTok Shop product. Free: no API token required.",
+        inputSchema: calcInputShape,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => toToolResult(() => runCalculate(config, args)));
+}

package/dist/tools/scenarios.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { apiRequest, ProfitleeError } from "../client.js";
+import { toToolResult } from "../result.js";
+import { calcInputShape } from "../schemas.js";
+const idShape = { id: z.string().min(1).describe("Scenario id.") };
+export async function listScenarios(config) {
+    return apiRequest(config, { method: "GET", path: "/api/v1/scenarios", auth: true });
+}
+export async function getScenario(config, args) {
+    return apiRequest(config, { method: "GET", path: `/api/v1/scenarios/${encodeURIComponent(args.id)}`, auth: true });
+}
+export async function saveScenario(config, args) {
+    return apiRequest(config, {
+        method: "POST",
+        path: "/api/v1/scenarios",
+        auth: true,
+        body: { name: args.name, inputs: args.inputs },
+    });
+}
+export async function updateScenario(config, args) {
+    if (args.inputs !== undefined) {
+        const body = { inputs: args.inputs };
+        if (args.name !== undefined)
+            body.name = args.name;
+        return apiRequest(config, { method: "PUT", path: `/api/v1/scenarios/${encodeURIComponent(args.id)}`, auth: true, body });
+    }
+    if (args.name !== undefined) {
+        return apiRequest(config, {
+            method: "PATCH",
+            path: `/api/v1/scenarios/${encodeURIComponent(args.id)}`,
+            auth: true,
+            body: { name: args.name },
+        });
+    }
+    throw new ProfitleeError("Provide name or inputs to update.");
+}
+export async function deleteScenario(config, args) {
+    return apiRequest(config, { method: "DELETE", path: `/api/v1/scenarios/${encodeURIComponent(args.id)}`, auth: true });
+}
+export function registerScenarioTools(server, config) {
+    server.registerTool("list_scenarios", {
+        title: "List saved scenarios",
+        description: "List the caller's saved Profitlee scenarios. Requires a Pro API token.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async () => toToolResult(() => listScenarios(config)));
+    server.registerTool("get_scenario", {
+        title: "Get a scenario",
+        description: "Fetch one saved scenario (inputs + outputs) by id. Requires a Pro API token.",
+        inputSchema: idShape,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => toToolResult(() => getScenario(config, args)));
+    server.registerTool("save_scenario", {
+        title: "Save a scenario",
+        description: "Save a named scenario from calculator inputs. Outputs are computed server-side. Requires a Pro API token.",
+        inputSchema: {
+            name: z.string().min(1).max(120).describe("Scenario name."),
+            inputs: z.object(calcInputShape).describe("Calculator inputs, same shape as calculate_profit."),
+        },
+        annotations: { openWorldHint: true },
+    }, async (args) => toToolResult(() => saveScenario(config, args)));
+    server.registerTool("update_scenario", {
+        title: "Update a scenario",
+        description: "Update a saved scenario: pass inputs to replace and recompute, and/or name to rename. Requires a Pro API token.",
+        inputSchema: {
+            ...idShape,
+            name: z.string().min(1).max(120).optional().describe("New name (optional)."),
+            inputs: z.object(calcInputShape).optional().describe("Replacement calculator inputs (optional)."),
+        },
+        annotations: { openWorldHint: true },
+    }, async (args) => toToolResult(() => updateScenario(config, args)));
+    server.registerTool("delete_scenario", {
+        title: "Delete a scenario",
+        description: "Delete a saved scenario by id. Requires a Pro API token.",
+        inputSchema: idShape,
+        annotations: { destructiveHint: true, openWorldHint: true },
+    }, async (args) => toToolResult(() => deleteScenario(config, args)));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "profitlee-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Profitlee ecommerce profit calculator (Amazon FBA/FBM + TikTok Shop).",
+  "license": "MIT",
+  "author": "AronLEE <aronleedev@gmail.com>",
+  "homepage": "https://github.com/AronLEEdev/profitlee-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AronLEEdev/profitlee-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AronLEEdev/profitlee-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "amazon",
+    "fba",
+    "fbm",
+    "tiktok-shop",
+    "profit-calculator",
+    "margin",
+    "ecommerce",
+    "seller",
+    "profitlee"
+  ],
+  "mcpName": "io.github.aronleedev/profitlee-mcp",
+  "type": "module",
+  "bin": { "profitlee-mcp": "dist/index.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}