@definitive-fi/mcp 1.0.0

package/README.md

@@ -0,0 +1,33 @@
+# @definitive-fi/mcp
+
+MCP server for the [Definitive](https://definitive.fi) on-chain trading platform.
+
+## Quick Start
+
+Add the following to your MCP client configuration (e.g., Claude Desktop, Claude Code, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "definitive": {
+      "command": "npx",
+      "args": ["-y", "@definitive-fi/mcp@latest"],
+      "env": {
+        "DEFINITIVE_API_KEY": "dpka_...",
+        "DEFINITIVE_API_SECRET": "dpks_...",
+        "DEFINITIVE_API_KEY_TYPE": "portfolio"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `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_PORTFOLIO_ID` | No | Portfolio ID (required for organization keys when targeting a specific portfolio) |

package/dist/server.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+
+import crypto from "node:crypto";
+var PublicAuthHelpers = {
+  generateHMAC(key, message) {
+    return crypto.createHmac("sha256", key).update(message).digest("hex");
+  },
+  preparePrehash({
+    method,
+    timestamp,
+    path,
+    queryParams,
+    headers,
+    body
+  }) {
+    const filtered = Object.entries(headers).filter(([key]) => key.toLowerCase().startsWith("x-definitive-"));
+    const sortedHeaders = filtered.sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}:${JSON.stringify(value)}`).join(",");
+    if (filtered.length > 3) {
+      throw new Error("Headers are too long - are you adding a new header?");
+    }
+    const queryParamsString = new URLSearchParams(queryParams).toString();
+    const bodyString = body ?? "";
+    return `${method}:${path}?${queryParamsString}:${timestamp}:${sortedHeaders}${bodyString}`;
+  },
+  clientSignMessage(apiSecret, message) {
+    const secret = apiSecret.replace("dpks_", "");
+    return PublicAuthHelpers.generateHMAC(secret, message);
+  }
+};
+
+
+function createClient(baseUrl, apiKey, apiSecret) {
+  return {
+    async request(method, path, queryParams, body) {
+      const timestamp = Date.now().toString();
+      const headers = {
+        "x-definitive-api-key": apiKey,
+        "x-definitive-timestamp": timestamp
+      };
+      const bodyString = body !== undefined ? JSON.stringify(body) : undefined;
+      const prehash = PublicAuthHelpers.preparePrehash({
+        method,
+        path,
+        timestamp,
+        headers,
+        queryParams,
+        body: bodyString
+      });
+      const signature = PublicAuthHelpers.clientSignMessage(apiSecret, prehash);
+      const queryString = queryParams ? new URLSearchParams(queryParams).toString() : "";
+      const url = queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
+      const fetchHeaders = {
+        ...headers,
+        "x-definitive-signature": signature
+      };
+      if (bodyString) {
+        fetchHeaders["Content-Type"] = "application/json";
+      }
+      const response = await fetch(url, {
+        method,
+        headers: fetchHeaders,
+        body: bodyString
+      });
+      let json;
+      try {
+        json = await response.json();
+      } catch {
+        return {
+          error: true,
+          status_code: response.status,
+          message: `Non-JSON response: ${response.statusText}`
+        };
+      }
+      if (!response.ok) {
+        return {
+          error: true,
+          status_code: response.status,
+          message: typeof json === "object" && json !== null && "message" in json ? String(json.message) : response.statusText
+        };
+      }
+      return json;
+    }
+  };
+}
+
+
+function resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId) {
+  if (keyType === "portfolio") {
+    return `/v2/portfolio/${suffix}`;
+  }
+  const id = portfolioId ?? defaultPortfolioId;
+  if (!id) {
+    throw new Error("portfolio_id is required for organization keys when DEFINITIVE_PORTFOLIO_ID is not set");
+  }
+  return `/v2/organization/portfolios/${id}/${suffix}`;
+}
+
+
+import { z } from "zod";
+var zUUID = z.string().uuid();
+var portfolioIdParam = zUUID.optional().describe("Portfolio UUID (required for organization keys without a default)");
+var ChainEnum = z.enum([
+  "arbitrum",
+  "avalanche",
+  "base",
+  "blast",
+  "bsc",
+  "ethereum",
+  "optimism",
+  "polygon",
+  "solana",
+  "hyperevm",
+  "plasma",
+  "monad"
+]);
+var jsonResult = (result) => ({
+  content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+});
+function registerReadTools(server, client, keyType, defaultPortfolioId) {
+  const resolve = (suffix, portfolioId) => resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId);
+  server.tool("list_positions", "List current token holdings in the portfolio with balances, USD values, and P&L.", {
+    limit: z.number().min(1).max(100).default(20).describe("Max positions to return (1-100)"),
+    cursor: z.string().optional().describe("Pagination cursor from previous response's nextCursor field"),
+    include_dust_balances: z.boolean().default(false).describe("Include positions worth less than $1"),
+    portfolio_id: portfolioIdParam
+  }, async ({ limit, cursor, include_dust_balances, portfolio_id }) => {
+    const path = resolve("positions", portfolio_id);
+    const params = { limit: String(limit) };
+    if (cursor)
+      params.cursor = cursor;
+    if (include_dust_balances)
+      params.includeDustBalances = "true";
+    const result = await client.request("GET", path, params);
+    return jsonResult(result);
+  });
+  server.tool("get_portfolio", "Get portfolio details including vaults, addresses, chains, and signers.", {
+    portfolio_id: portfolioIdParam
+  }, async ({ portfolio_id }) => {
+    const path = resolve("", portfolio_id);
+    const result = await client.request("GET", path.replace(/\/$/, ""));
+    return jsonResult(result);
+  });
+  server.tool("list_transfers", "List historical transfers (deposits, withdrawals, swaps, bridge transactions) for the portfolio.", {
+    limit: z.number().min(1).max(100).default(20).describe("Max transfers to return (1-100)"),
+    cursor: z.string().optional().describe("Pagination cursor from previous response's nextCursor field"),
+    action_types: z.array(z.enum([
+      "VAULT_ACTION_DEPOSIT",
+      "VAULT_ACTION_WITHDRAW",
+      "VAULT_ACTION_BRIDGE_SEND",
+      "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)"),
+    portfolio_id: portfolioIdParam
+  }, async ({
+    limit,
+    cursor,
+    action_types,
+    start_timestamp,
+    end_timestamp,
+    portfolio_id
+  }) => {
+    const path = resolve("transfers", portfolio_id);
+    const params = { limit: String(limit) };
+    if (cursor)
+      params.cursor = cursor;
+    if (action_types?.length)
+      params.actionTypes = action_types.join(",");
+    if (start_timestamp)
+      params.startTimestamp = start_timestamp;
+    if (end_timestamp)
+      params.endTimestamp = end_timestamp;
+    const result = await client.request("GET", path, params);
+    return jsonResult(result);
+  });
+  server.tool("get_deposit_address", "Get a deposit address for a specific blockchain. Creates a vault if one doesn't exist for that chain.", {
+    chain: ChainEnum.describe("Blockchain network name"),
+    wallet_address: z.string().min(1).describe("User's wallet address on this chain — ask the user if not provided"),
+    portfolio_id: portfolioIdParam
+  }, async ({ chain, wallet_address, portfolio_id }) => {
+    const path = resolve(`address/${chain}`, portfolio_id);
+    const params = { walletAddress: wallet_address };
+    const result = await client.request("GET", path, params);
+    return jsonResult(result);
+  });
+  server.tool("list_orders", "List trade orders with optional status filtering. Returns order details including fill status and pricing.", {
+    limit: z.number().min(1).max(100).default(20).describe("Max orders to return (1-100)"),
+    cursor: z.string().optional().describe("Pagination cursor from previous response's nextCursor field"),
+    status: z.enum([
+      "ORDER_STATUS_PENDING",
+      "ORDER_STATUS_ACCEPTED",
+      "ORDER_STATUS_PARTIALLY_FILLED",
+      "ORDER_STATUS_FILLED",
+      "ORDER_STATUS_CANCELLED"
+    ]).optional().describe("Filter orders by status"),
+    portfolio_id: portfolioIdParam
+  }, async ({ limit, cursor, status, portfolio_id }) => {
+    const path = resolve("orders", portfolio_id);
+    const params = { limit: String(limit) };
+    if (cursor)
+      params.cursor = cursor;
+    if (status)
+      params.filters = JSON.stringify({ status });
+    const result = await client.request("GET", path, params);
+    return jsonResult(result);
+  });
+  server.tool("get_order_details", "Get detailed information about a specific order including individual fill history.", {
+    order_id: zUUID.describe("The order UUID to look up"),
+    portfolio_id: portfolioIdParam
+  }, async ({ order_id, portfolio_id }) => {
+    const path = resolve(`orders/${order_id}`, portfolio_id);
+    const result = await client.request("GET", path);
+    return jsonResult(result);
+  });
+  if (keyType !== "organization")
+    return;
+  server.tool("list_portfolios", "List all portfolios in the organization. Organization API keys only.", {
+    limit: z.number().min(1).max(100).default(10).describe("Max portfolios to return (1-100)"),
+    cursor: z.string().optional().describe("Pagination cursor from previous response's nextCursor field")
+  }, async ({ limit, cursor }) => {
+    const params = { limit: String(limit) };
+    if (cursor)
+      params.cursor = cursor;
+    const result = await client.request("GET", "/v2/organization", params);
+    return jsonResult(result);
+  });
+  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)")
+  }, async ({ portfolio_id, start_timestamp, end_timestamp }) => {
+    const params = {};
+    if (start_timestamp)
+      params.startTimestamp = start_timestamp;
+    if (end_timestamp)
+      params.endTimestamp = end_timestamp;
+    const result = await client.request("GET", `/v2/organization/portfolios/${portfolio_id}/fees`, params);
+    return jsonResult(result);
+  });
+}
+
+
+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 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"
+});
+registerReadTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
+var transport = new StdioServerTransport;
+await server.connect(transport);

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@definitive-fi/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Definitive on-chain trading platform",
+  "type": "module",
+  "bin": "dist/server.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.0"
+  }
+}