@kasarlabs/ekubo-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kasar Labs
+
+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,54 @@
+# Snak - Ekubo MCP
+
+The Ekubo MCP provides tools for interacting with Ekubo Protocol, the next-generation AMM (Automated Market Maker) on Starknet that revolutionizes DeFi with ultra-concentrated liquidity and singleton architecture.
+
+## About Ekubo Protocol
+
+Ekubo is Starknet's leading AMM, commanding 60% of the total AMM TVL and the majority of trading volume on the network. Built by former Uniswap Labs engineers, it features:
+
+- **Singleton Architecture**: All pools consolidated into a single Cairo smart contract for 99% cheaper pool creation
+- **Ultra-Concentrated Liquidity**: Up to 100x more capital efficient positions with precision down to 1/100th of a basis point
+- **Extensions System**: Custom pool logic deployment without governance approval
+- **Till Pattern**: Gas-optimized deferred token transfers
+
+## Features
+
+This MCP adds the following tools:
+
+### Read Operations
+
+- **get_pool_info**: Get comprehensive information about an Ekubo pool including current price, liquidity, and fee data.
+- **get_token_price**: Get the price of a token via Ekubo pools by querying the pool price directly from the Core contract.
+- **get_pool_liquidity**: Get the total liquidity available in an Ekubo pool at the current tick.
+- **get_pool_fees_per_liquidity**: Get the cumulative fees per unit of liquidity for an Ekubo pool (both token0 and token1).
+
+### Write Operations
+
+- **swap**: Swap tokens on Ekubo DEX. Supports both exact input and exact output swaps with configurable slippage tolerance.
+- **create_position**: Create a new liquidity position (NFT) in an Ekubo pool within a specified price range (concentrated liquidity).
+- **add_liquidity**: Add liquidity to an existing Ekubo pool position without minting a new NFT.
+- **withdraw_liquidity**: Withdraw liquidity from an Ekubo pool position. Can withdraw full position, partial position, or only collect fees.
+- **transfer_position**: Transfer an Ekubo NFT position to another address.
+
+## Usage
+
+The Ekubo MCP is used by Claude Code and compatible MCP clients. Configure it in your MCP settings to enable Ekubo Protocol functionality.
+
+## Example
+
+When asking the agent to perform Ekubo-related tasks, it will use the appropriate tool from this MCP:
+
+```
+"Get info about the ETH/USDC pool on Ekubo"  // Uses get_pool_info
+"What's the price of STRK on Ekubo?"  // Uses get_token_price
+"How much liquidity is in the ETH/USDC pool?"  // Uses get_pool_liquidity
+"Swap 0.1 ETH for USDC on Ekubo"  // Uses swap
+"Create a liquidity position for ETH/USDC"  // Uses create_position
+"Add liquidity to my existing position"  // Uses add_liquidity
+"Withdraw liquidity from my position"  // Uses withdraw_liquidity
+"Transfer my position NFT to another address"  // Uses transfer_position
+```
+
+## Development
+
+To extend this MCP, add new tools in the `src/tools` directory and register them in the `registerTools` function in `src/tools/index.ts`.

package/bin/ekubo-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../build/index.js');

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const RegisterToolInServer: () => Promise<void>;

package/build/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import dotenv from 'dotenv';
+import { registerToolsWithServer, getOnchainRead, getOnchainWrite, } from '@kasarlabs/ask-starknet-core';
+import { poolKeySchema, getTokenPriceSchema, swapTokensSchema, addLiquiditySchema, withdrawLiquiditySchema, transferPositionSchema, createPositionSchema, } from './schemas/index.js';
+import { getPoolInfo } from './tools/read/getPoolInfo.js';
+import { getTokenPrice } from './tools/read/getTokenPrice.js';
+import { getPoolLiquidity } from './tools/read/getPoolLiquidity.js';
+import { getPoolFeesPerLiquidity } from './tools/read/getPoolFeesPerLiquidity.js';
+import { swap } from './tools/write/swap.js';
+import { createPosition } from './tools/write/createPosition.js';
+import { addLiquidity } from './tools/write/addLiquidity.js';
+import { withdrawLiquidity } from './tools/write/withdrawLiquidity.js';
+import { transferPosition } from './tools/write/transferPosition.js';
+dotenv.config();
+const server = new McpServer({
+    name: 'ekubo-mcp',
+    version: '0.0.1',
+});
+const registerTools = (EkuboToolRegistry) => {
+    EkuboToolRegistry.push({
+        name: 'get_pool_info',
+        description: 'Get comprehensive information about an Ekubo pool including current price, liquidity, and fee data.',
+        schema: poolKeySchema,
+        execute: async (params) => {
+            const onchainRead = getOnchainRead();
+            return await getPoolInfo(onchainRead, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'get_token_price',
+        description: 'Get the price of a token via Ekubo pools by querying the pool price directly from the Core contract.',
+        schema: getTokenPriceSchema,
+        execute: async (params) => {
+            const onchainRead = getOnchainRead();
+            return await getTokenPrice(onchainRead, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'get_pool_liquidity',
+        description: 'Get the total liquidity available in an Ekubo pool at the current tick.',
+        schema: poolKeySchema,
+        execute: async (params) => {
+            const onchainRead = getOnchainRead();
+            return await getPoolLiquidity(onchainRead, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'get_pool_fees_per_liquidity',
+        description: 'Get the cumulative fees per unit of liquidity for an Ekubo pool (both token0 and token1).',
+        schema: poolKeySchema,
+        execute: async (params) => {
+            const onchainRead = getOnchainRead();
+            return await getPoolFeesPerLiquidity(onchainRead, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'swap',
+        description: 'Swap tokens on Ekubo DEX. Supports both exact input (specify input amount) and exact output (specify desired output amount) swaps with configurable slippage tolerance.',
+        schema: swapTokensSchema,
+        execute: async (params) => {
+            const onchainWrite = getOnchainWrite();
+            return await swap(onchainWrite, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'create_position',
+        description: 'Create a new liquidity position (NFT) in an Ekubo pool within a specified price range (concentrated liquidity). Mints a new NFT position.',
+        schema: createPositionSchema,
+        execute: async (params) => {
+            const onchainWrite = getOnchainWrite();
+            return await createPosition(onchainWrite, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'add_liquidity',
+        description: 'Add liquidity to an existing Ekubo pool position without minting a new NFT. Deposits tokens into the last position.',
+        schema: addLiquiditySchema,
+        execute: async (params) => {
+            const onchainWrite = getOnchainWrite();
+            return await addLiquidity(onchainWrite, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'withdraw_liquidity',
+        description: 'Withdraw liquidity from an Ekubo pool position. Can withdraw full position, partial position, or only collect fees.',
+        schema: withdrawLiquiditySchema,
+        execute: async (params) => {
+            const onchainWrite = getOnchainWrite();
+            return await withdrawLiquidity(onchainWrite, params);
+        },
+    });
+    EkuboToolRegistry.push({
+        name: 'transfer_position',
+        description: 'Transfer an Ekubo NFT position to another address. The position NFT represents ownership of the liquidity position.',
+        schema: transferPositionSchema,
+        execute: async (params) => {
+            const onchainWrite = getOnchainWrite();
+            return await transferPosition(onchainWrite, params);
+        },
+    });
+};
+export const RegisterToolInServer = async () => {
+    const tools = [];
+    registerTools(tools);
+    await registerToolsWithServer(server, tools);
+};
+async function main() {
+    const transport = new StdioServerTransport();
+    await RegisterToolInServer();
+    await server.connect(transport);
+    console.error('Starknet Ekubo MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/interfaces/index.d.ts

@@ -0,0 +1,21 @@
+import { Account, RpcProvider } from 'starknet';
+export interface EnvParams {
+    provider: RpcProvider;
+    account: Account;
+}
+export interface CompletePoolInfo {
+    price: bigint;
+    liquidity: bigint;
+    fees_per_liquidity: {
+        fee_growth_global_0: bigint;
+        fee_growth_global_1: bigint;
+    };
+    current_tick: number;
+}
+export interface envRead {
+    provider: RpcProvider;
+}
+export interface envWrite {
+    provider: RpcProvider;
+    account: Account;
+}

package/build/interfaces/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/build/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":""}

package/build/lib/constants/abis/core.d.ts

@@ -0,0 +1,92 @@
+export declare const CORE_ABI: ({
+    type: string;
+    name: string;
+    interface_name: string;
+    members?: undefined;
+    variants?: undefined;
+    items?: undefined;
+    inputs?: undefined;
+    kind?: undefined;
+} | {
+    type: string;
+    name: string;
+    members: {
+        name: string;
+        type: string;
+    }[];
+    interface_name?: undefined;
+    variants?: undefined;
+    items?: undefined;
+    inputs?: undefined;
+    kind?: undefined;
+} | {
+    type: string;
+    name: string;
+    variants: {
+        name: string;
+        type: string;
+    }[];
+    interface_name?: undefined;
+    members?: undefined;
+    items?: undefined;
+    inputs?: undefined;
+    kind?: undefined;
+} | {
+    type: string;
+    name: string;
+    items: {
+        type: string;
+        name: string;
+        inputs: {
+            name: string;
+            type: string;
+        }[];
+        outputs: {
+            type: string;
+        }[];
+        state_mutability: string;
+    }[];
+    interface_name?: undefined;
+    members?: undefined;
+    variants?: undefined;
+    inputs?: undefined;
+    kind?: undefined;
+} | {
+    type: string;
+    name: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    interface_name?: undefined;
+    members?: undefined;
+    variants?: undefined;
+    items?: undefined;
+    kind?: undefined;
+} | {
+    type: string;
+    name: string;
+    kind: string;
+    members: {
+        name: string;
+        type: string;
+        kind: string;
+    }[];
+    interface_name?: undefined;
+    variants?: undefined;
+    items?: undefined;
+    inputs?: undefined;
+} | {
+    type: string;
+    name: string;
+    kind: string;
+    variants: {
+        name: string;
+        type: string;
+        kind: string;
+    }[];
+    interface_name?: undefined;
+    members?: undefined;
+    items?: undefined;
+    inputs?: undefined;
+})[];