@definitive-fi/mcp 1.0.0 → 1.1.0

package/README.md

@@ -22,6 +22,10 @@ Add the following to your MCP client configuration (e.g., Claude Desktop, Claude
 }
 ```
 
+## Documentation & API Keys
+
+New to Definitive? Visit the [Definitive API documentation](https://ddp.definitive.fi/overview) to get started and obtain your API keys.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -29,5 +33,5 @@ Add the following to your MCP client configuration (e.g., Claude Desktop, Claude
 | `DEFINITIVE_API_KEY` | Yes | Your Definitive API key |
 | `DEFINITIVE_API_SECRET` | Yes | Your Definitive API secret |
 | `DEFINITIVE_API_KEY_TYPE` | Yes | Key type: `"portfolio"` or `"organization"` |
-| `DEFINITIVE_BASE_URL` | No | API base URL (defaults to production) |
+| `DEFINITIVE_BASE_URL` | No | API base URL |
 | `DEFINITIVE_PORTFOLIO_ID` | No | Portfolio ID (required for organization keys when targeting a specific portfolio) |

package/dist/server.js

@@ -154,8 +154,8 @@ function registerReadTools(server, client, keyType, defaultPortfolioId) {
       "VAULT_ACTION_BRIDGE_RECEIVE",
       "VAULT_ACTION_SWAP"
     ])).optional().describe("Filter by transfer action types"),
-    start_timestamp: z.string().optional().describe("Start of time range (ISO 8601 string)"),
-    end_timestamp: z.string().optional().describe("End of time range (ISO 8601 string)"),
+    start_timestamp: z.string().datetime().optional().describe("Start of time range (ISO 8601 string, e.g. 2025-01-01T00:00:00Z)"),
+    end_timestamp: z.string().datetime().optional().describe("End of time range (ISO 8601 string, e.g. 2025-01-01T00:00:00Z)"),
     portfolio_id: portfolioIdParam
   }, async ({
     limit,
@@ -231,8 +231,8 @@ function registerReadTools(server, client, keyType, defaultPortfolioId) {
   });
   server.tool("get_fees", "Get fee summary for a portfolio over a time period. Organization API keys only.", {
     portfolio_id: zUUID.describe("Portfolio UUID to get fees for"),
-    start_timestamp: z.string().optional().describe("Start of time range (ISO 8601 string)"),
-    end_timestamp: z.string().optional().describe("End of time range (ISO 8601 string)")
+    start_timestamp: z.string().datetime().optional().describe("Start of time range (ISO 8601 string, e.g. 2025-01-01T00:00:00Z)"),
+    end_timestamp: z.string().datetime().optional().describe("End of time range (ISO 8601 string, e.g. 2025-01-01T00:00:00Z)")
   }, async ({ portfolio_id, start_timestamp, end_timestamp }) => {
     const params = {};
     if (start_timestamp)
@@ -246,20 +246,351 @@ function registerReadTools(server, client, keyType, defaultPortfolioId) {
 
 
 import { z as z2 } from "zod";
-var McpEnvSchema = z2.object({
-  DEFINITIVE_API_KEY: z2.string().startsWith("dpka_"),
-  DEFINITIVE_API_SECRET: z2.string().startsWith("dpks_"),
-  DEFINITIVE_BASE_URL: z2.string().url().default("https://ddp.definitive.fi"),
-  DEFINITIVE_API_KEY_TYPE: z2.enum(["portfolio", "organization"]),
-  DEFINITIVE_PORTFOLIO_ID: z2.string().optional()
+var zUUID2 = z2.string().uuid();
+var portfolioIdParam2 = zUUID2.optional().describe("Portfolio UUID (required for organization keys without a default)");
+var ChainEnum2 = z2.enum([
+  "arbitrum",
+  "avalanche",
+  "base",
+  "blast",
+  "bsc",
+  "ethereum",
+  "optimism",
+  "polygon",
+  "solana",
+  "hyperevm",
+  "plasma",
+  "monad"
+]);
+var OrderSideEnum = z2.enum(["buy", "sell"]);
+var OrderTypeEnum = z2.enum([
+  "market",
+  "limit",
+  "twap",
+  "stop",
+  "stop-loss",
+  "take-profit"
+]);
+var jsonResult2 = (result) => ({
+  content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+});
+function registerWriteTools(server, client, keyType, defaultPortfolioId) {
+  const resolve = (suffix, portfolioId) => resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId);
+  server.tool("get_trade_quote", "Get a price quote for a trade order. This is the DEFAULT tool for all trades — use this unless the user explicitly asks for a QuickTrade. Supports market, limit, TWAP, stop, stop-loss, and take-profit order types. This does not execute any trade. Use the returned quote ID with submit_trade to execute.", {
+    type: OrderTypeEnum.describe("Order type"),
+    chain: ChainEnum2.describe("Blockchain network name"),
+    target_asset: z2.string().min(1).describe("Target asset contract address"),
+    contra_asset: z2.string().min(1).describe("Contra (quote) asset contract address"),
+    qty: z2.string().min(1).describe("Order quantity as a decimal string"),
+    order_side: OrderSideEnum.describe("Buy or sell"),
+    limit_price: z2.string().optional().describe("Limit price (for limit orders)"),
+    limit_is_notional: z2.boolean().optional().describe("Whether limit price is in notional terms"),
+    trigger_price: z2.string().optional().describe("Trigger price (for stop/stop-loss/take-profit orders)"),
+    trigger_is_notional: z2.boolean().optional().describe("Whether trigger price is in notional terms"),
+    duration_seconds: z2.number().optional().describe("TWAP duration in seconds"),
+    target_twap_buckets: z2.number().optional().describe("Number of TWAP buckets"),
+    trigger_type: z2.enum(["upper", "lower"]).optional().describe("Trigger type for stop-buy orders only (upper or lower price bound)"),
+    slippage_tolerance: z2.string().optional().describe("Slippage tolerance as a decimal string (e.g. '1.0' for 1%)"),
+    max_price_impact: z2.string().optional().describe("Max price impact as a decimal string (e.g. '1.0' for 1%)"),
+    portfolio_id: portfolioIdParam2
+  }, { readOnlyHint: true }, async ({
+    type,
+    chain,
+    target_asset,
+    contra_asset,
+    qty,
+    order_side,
+    limit_price,
+    limit_is_notional,
+    trigger_price,
+    trigger_is_notional,
+    duration_seconds,
+    target_twap_buckets,
+    trigger_type,
+    slippage_tolerance,
+    max_price_impact,
+    portfolio_id
+  }) => {
+    const path = resolve("trade/quote", portfolio_id);
+    const body = {
+      type,
+      chain,
+      targetAsset: target_asset,
+      contraAsset: contra_asset,
+      qty,
+      orderSide: order_side
+    };
+    if (limit_price !== undefined) {
+      body.limit = {
+        price: limit_price,
+        isNotional: limit_is_notional ?? false
+      };
+    }
+    if (trigger_price !== undefined) {
+      body.trigger = {
+        price: trigger_price,
+        isNotional: trigger_is_notional ?? false
+      };
+    }
+    if (duration_seconds !== undefined)
+      body.durationSeconds = duration_seconds;
+    if (target_twap_buckets !== undefined)
+      body.targetTWAPBuckets = target_twap_buckets;
+    if (trigger_type !== undefined)
+      body.triggerType = trigger_type;
+    if (slippage_tolerance !== undefined)
+      body.slippageTolerance = slippage_tolerance;
+    if (max_price_impact !== undefined)
+      body.maxPriceImpact = max_price_impact;
+    const result = await client.request("POST", path, undefined, body);
+    return jsonResult2(result);
+  });
+  server.tool("get_quicktrade_quote", "Get a price quote for a QuickTrade market swap. Only use when the user explicitly requests a QuickTrade. This does not execute any trade. Review the quote before executing with the quicktrade tool.", {
+    target_asset: z2.string().min(1).describe("Target asset contract address"),
+    contra_asset: z2.string().min(1).describe("Contra (quote) asset contract address"),
+    chain: ChainEnum2.describe("Blockchain network name"),
+    qty: z2.string().min(1).describe("Order quantity as a decimal string"),
+    order_side: OrderSideEnum.describe("Buy or sell"),
+    portfolio_id: portfolioIdParam2
+  }, { readOnlyHint: true }, async ({ target_asset, contra_asset, chain, qty, order_side, portfolio_id }) => {
+    const path = resolve("quicktrade/quote", portfolio_id);
+    const body = {
+      type: "market",
+      chain,
+      targetAsset: target_asset,
+      contraAsset: contra_asset,
+      qty,
+      orderSide: order_side
+    };
+    const result = await client.request("POST", path, undefined, body);
+    return jsonResult2(result);
+  });
+  server.tool("bridge_quote", "Get a quote for a cross-chain bridge transfer. This does not move any funds. Review the routes and select a route_id before executing with bridge_submit.", {
+    from_asset_address: z2.string().min(1).describe("Source asset contract address"),
+    from_chain: ChainEnum2.describe("Source blockchain network"),
+    to_asset_address: z2.string().min(1).describe("Destination asset contract address"),
+    to_chain: ChainEnum2.describe("Destination blockchain network"),
+    from_amount: z2.string().min(1).describe("Amount to bridge as a decimal string"),
+    portfolio_id: portfolioIdParam2
+  }, { readOnlyHint: true }, async ({
+    from_asset_address,
+    from_chain,
+    to_asset_address,
+    to_chain,
+    from_amount,
+    portfolio_id
+  }) => {
+    const path = resolve("bridge/quote", portfolio_id);
+    const body = {
+      fromAssetAddress: from_asset_address,
+      fromChain: from_chain,
+      toAssetAddress: to_asset_address,
+      toChain: to_chain,
+      fromAmount: from_amount
+    };
+    const result = await client.request("POST", path, undefined, body);
+    return jsonResult2(result);
+  });
+  server.tool("cancel_trade", "Cancel a pending trade order. This prevents the order from executing.", {
+    order_id: zUUID2.describe("The order UUID to cancel"),
+    portfolio_id: portfolioIdParam2
+  }, {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true
+  }, async ({ order_id, portfolio_id }) => {
+    const path = resolve(`trade/${order_id}`, portfolio_id);
+    const result = await client.request("DELETE", path);
+    return jsonResult2(result);
+  });
+  server.tool("cancel_quicktrade", "Cancel a pending QuickTrade order. This prevents the order from executing.", {
+    order_id: zUUID2.describe("The order UUID to cancel"),
+    portfolio_id: portfolioIdParam2
+  }, {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true
+  }, async ({ order_id, portfolio_id }) => {
+    const path = resolve(`quicktrade/${order_id}`, portfolio_id);
+    const result = await client.request("DELETE", path);
+    return jsonResult2(result);
+  });
+  server.tool("submit_trade", "Submit a trade order using a quote from get_trade_quote. This is irreversible — all order types (market, limit, stop, TWAP) may execute immediately. Always show the user the quote details and get confirmation before calling this tool. Pass the same parameters you used for get_trade_quote plus the quote_id.", {
+    quote_id: zUUID2.describe("Quote UUID from get_trade_quote response (found in quote.quote.id)"),
+    type: OrderTypeEnum.describe("Order type"),
+    chain: ChainEnum2.describe("Blockchain network name"),
+    target_asset: z2.string().min(1).describe("Target asset contract address"),
+    contra_asset: z2.string().min(1).describe("Contra (quote) asset contract address"),
+    qty: z2.string().min(1).describe("Order quantity as a decimal string"),
+    order_side: OrderSideEnum.describe("Buy or sell"),
+    limit_price: z2.string().optional().describe("Limit price (for limit orders)"),
+    limit_is_notional: z2.boolean().optional().describe("Whether limit price is in notional terms"),
+    trigger_price: z2.string().optional().describe("Trigger price (for stop/stop-loss/take-profit orders)"),
+    trigger_is_notional: z2.boolean().optional().describe("Whether trigger price is in notional terms"),
+    duration_seconds: z2.number().optional().describe("TWAP duration in seconds"),
+    target_twap_buckets: z2.number().optional().describe("Number of TWAP buckets"),
+    trigger_type: z2.enum(["upper", "lower"]).optional().describe("Trigger type for stop-buy orders only"),
+    slippage_tolerance: z2.string().optional().describe("Slippage tolerance as a decimal string (e.g. '1.0' for 1%)"),
+    max_price_impact: z2.string().optional().describe("Max price impact as a decimal string (e.g. '1.0' for 1%)"),
+    portfolio_id: portfolioIdParam2
+  }, {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false
+  }, async ({
+    quote_id,
+    type,
+    chain,
+    target_asset,
+    contra_asset,
+    qty,
+    order_side,
+    limit_price,
+    limit_is_notional,
+    trigger_price,
+    trigger_is_notional,
+    duration_seconds,
+    target_twap_buckets,
+    trigger_type,
+    slippage_tolerance,
+    max_price_impact,
+    portfolio_id
+  }) => {
+    const path = resolve("trade", portfolio_id);
+    const externalOrderRequest = {
+      type,
+      chain,
+      targetAsset: target_asset,
+      contraAsset: contra_asset,
+      qty,
+      orderSide: order_side
+    };
+    if (limit_price !== undefined)
+      externalOrderRequest.limit = { price: limit_price, isNotional: limit_is_notional ?? false };
+    if (trigger_price !== undefined)
+      externalOrderRequest.trigger = { price: trigger_price, isNotional: trigger_is_notional ?? false };
+    if (duration_seconds !== undefined)
+      externalOrderRequest.durationSeconds = duration_seconds;
+    if (target_twap_buckets !== undefined)
+      externalOrderRequest.targetTWAPBuckets = target_twap_buckets;
+    if (trigger_type !== undefined)
+      externalOrderRequest.triggerType = trigger_type;
+    if (slippage_tolerance !== undefined)
+      externalOrderRequest.slippageTolerance = slippage_tolerance;
+    if (max_price_impact !== undefined)
+      externalOrderRequest.maxPriceImpact = max_price_impact;
+    const result = await client.request("POST", path, undefined, {
+      quoteId: quote_id,
+      externalOrderRequest
+    });
+    return jsonResult2(result);
+  });
+  server.tool("quicktrade", "Execute a QuickTrade market swap immediately. Only use when the user explicitly requests a QuickTrade. This is irreversible — funds move on-chain once submitted. Always call get_quicktrade_quote first and confirm the details with the user before executing.", {
+    target_asset: z2.string().min(1).describe("Target asset contract address"),
+    contra_asset: z2.string().min(1).describe("Contra (quote) asset contract address"),
+    chain: ChainEnum2.describe("Blockchain network name"),
+    qty: z2.string().min(1).describe("Order quantity as a decimal string"),
+    order_side: OrderSideEnum.describe("Buy or sell"),
+    slippage_tolerance: z2.string().optional().describe("Slippage tolerance as a decimal string (e.g. '0.01' for 1%)"),
+    display_asset_price: z2.string().optional().describe("Target asset notional price for display validation"),
+    seconds_to_expire: z2.number().int().positive().optional().describe("Order expiry time in seconds"),
+    portfolio_id: portfolioIdParam2
+  }, {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false
+  }, async ({
+    target_asset,
+    contra_asset,
+    chain,
+    qty,
+    order_side,
+    slippage_tolerance,
+    display_asset_price,
+    seconds_to_expire,
+    portfolio_id
+  }) => {
+    const path = resolve("quicktrade", portfolio_id);
+    const body = {
+      type: "market",
+      chain,
+      targetAsset: target_asset,
+      contraAsset: contra_asset,
+      qty,
+      orderSide: order_side
+    };
+    if (slippage_tolerance !== undefined)
+      body.slippageTolerance = slippage_tolerance;
+    if (display_asset_price !== undefined)
+      body.displayAssetPrice = display_asset_price;
+    if (seconds_to_expire !== undefined)
+      body.secondsToExpire = seconds_to_expire;
+    const result = await client.request("POST", path, undefined, body);
+    return jsonResult2(result);
+  });
+  server.tool("bridge_submit", "Execute a cross-chain bridge transfer. This is irreversible — funds are sent from the source chain to the destination chain. Always call bridge_quote first and confirm the details with the user before executing.", {
+    from_chain: ChainEnum2.describe("Source blockchain network"),
+    to_chain: ChainEnum2.describe("Destination blockchain network"),
+    from_asset_address: z2.string().min(1).describe("Source asset contract address"),
+    to_asset_address: z2.string().min(1).describe("Destination asset contract address"),
+    from_amount: z2.string().min(1).describe("Amount to bridge as a decimal string"),
+    route_id: z2.string().min(1).describe("Route ID from bridge_quote response"),
+    portfolio_id: portfolioIdParam2
+  }, {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false
+  }, async ({
+    from_chain,
+    to_chain,
+    from_asset_address,
+    to_asset_address,
+    from_amount,
+    route_id,
+    portfolio_id
+  }) => {
+    const path = resolve("bridge", portfolio_id);
+    const body = {
+      fromChain: from_chain,
+      toChain: to_chain,
+      fromAssetAddress: from_asset_address,
+      toAssetAddress: to_asset_address,
+      fromAmount: from_amount,
+      routeId: route_id
+    };
+    const result = await client.request("POST", path, undefined, body);
+    return jsonResult2(result);
+  });
+  if (keyType !== "organization")
+    return;
+  server.tool("create_portfolio", "Create a new portfolio in the organization. Organization API keys only.", {
+    portfolio_name: z2.string().min(1).describe("Name for the new portfolio")
+  }, {
+    readOnlyHint: false,
+    destructiveHint: false
+  }, async ({ portfolio_name }) => {
+    const result = await client.request("POST", "/v2/organization/create-portfolio", undefined, { portfolioName: portfolio_name });
+    return jsonResult2(result);
+  });
+}
+
+
+import { z as z3 } from "zod";
+var McpEnvSchema = z3.object({
+  DEFINITIVE_API_KEY: z3.string().startsWith("dpka_"),
+  DEFINITIVE_API_SECRET: z3.string().startsWith("dpks_"),
+  DEFINITIVE_BASE_URL: z3.string().url().default("https://ddp.definitive.fi"),
+  DEFINITIVE_API_KEY_TYPE: z3.enum(["portfolio", "organization"]),
+  DEFINITIVE_PORTFOLIO_ID: z3.string().optional()
 });
 var env = McpEnvSchema.parse(process.env);
 var client = createClient(env.DEFINITIVE_BASE_URL, env.DEFINITIVE_API_KEY, env.DEFINITIVE_API_SECRET);
 var server = new McpServer({
   name: "Definitive",
-  version: "1.0.0",
-  instructions: "MCP server for the Definitive on-chain trading platform. Provides unified tools for portfolio management, trading (market/limit/TWAP/stop orders), QuickTrade execution across 11 blockchains. Tools auto-route to the correct API based on the configured key type (portfolio or organization). For organization keys, pass portfolio_id to target a specific portfolio, or set DEFINITIVE_PORTFOLIO_ID as default. IMPORTANT: When specifying asset addresses for EVM native assets (ETH, MATIC, AVAX, BNB, HYPE, etc.), use the zero address: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
+  version: "1.1.0",
+  instructions: "MCP server for the Definitive on-chain trading platform. Provides unified tools for portfolio management, trading (market/limit/TWAP/stop orders), QuickTrade execution across multiple blockchains. Tools auto-route to the correct API based on the configured key type (portfolio or organization). For organization keys, pass portfolio_id to target a specific portfolio, or set DEFINITIVE_PORTFOLIO_ID as default. TRADING: Default to get_trade_quote + submit_trade for trades unless the user specifies QuickTrade."
 });
 registerReadTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
+registerWriteTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
 var transport = new StdioServerTransport;
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@definitive-fi/mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for the Definitive on-chain trading platform",
   "type": "module",
   "bin": "dist/server.js",
@@ -8,13 +8,15 @@
     "dist"
   ],
   "scripts": {
-    "build": "bun run build.ts"
-  },
-  "engines": {
-    "node": ">=18"
+    "build": "bun run build.ts",
+    "dev": "bun run --hot src/server.ts",
+    "start": "bun run src/server.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^3.25.0"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }