@cryptoquant_official/mcp 0.0.4 → 0.0.6-alpha

package/dist/ai-sdk/anthropic.js

@@ -0,0 +1,278 @@
+/**
+ * Anthropic SDK Integration for CryptoQuant Tools
+ *
+ * Provides CryptoQuant tools in native Anthropic SDK format for direct use
+ * with @anthropic-ai/sdk's client.messages.create().
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { createAnthropicTools, createToolExecutor } from '@cryptoquant_official/mcp/ai-sdk';
+ *
+ * const client = new Anthropic({ apiKey: process.env.CLAUDE_API_KEY });
+ * const toolDefinitions = createAnthropicTools();
+ * const executeTool = createToolExecutor({ cryptoquantApiKey: process.env.CRYPTOQUANT_API_KEY });
+ *
+ * const response = await client.messages.create({
+ *   model: 'claude-sonnet-4-20250514',
+ *   max_tokens: 4096,
+ *   tools: toolDefinitions,
+ *   messages: [{ role: 'user', content: 'What is MVRV?' }],
+ * });
+ *
+ * // Handle tool calls
+ * for (const block of response.content) {
+ *   if (block.type === 'tool_use') {
+ *     const result = await executeTool(block.name, block.input);
+ *     // ... use result
+ *   }
+ * }
+ * ```
+ */
+import { executeDescribeMetric, executeDiscoverEndpoints, executeInitialize, executeMarketSummary, executeQueryData, executeTradingSignal, executeWhaleActivity, } from "./execute.js";
+/**
+ * Cache TTL recommendations for each tool (in seconds)
+ * Consumers can use this to implement caching strategies
+ */
+export const toolCacheTTL = {
+    initialize: 3600, // 1 hour - session info
+    discover_endpoints: 86400, // 1 day - endpoint list rarely changes
+    describe_metric: 86400, // 1 day - static metric descriptions
+    query_data: 60, // 1 minute - real-time data
+    market_summary: 60, // 1 minute - real-time summary
+    trading_signal: 60, // 1 minute - real-time signal
+    whale_activity: 300, // 5 minutes - whale data
+};
+/**
+ * Raw JSON schemas for each tool
+ * Single source of truth - matches schemas.ts definitions
+ */
+const toolSchemas = {
+    initialize: {
+        type: "object",
+        properties: {
+            api_key: {
+                type: "string",
+                description: "CryptoQuant API key (optional if already provided in config)",
+            },
+        },
+        required: [],
+    },
+    discover_endpoints: {
+        type: "object",
+        properties: {
+            asset: {
+                type: "string",
+                enum: ["btc", "eth", "alt", "stablecoin", "erc20", "trx", "xrp"],
+                description: "Asset to filter by (e.g., btc, eth)",
+            },
+            category: {
+                type: "string",
+                description: "Category filter (e.g., market-data, exchange-flows, network-data)",
+            },
+            query: {
+                type: "string",
+                description: "Search term to filter endpoints by name or path",
+            },
+        },
+        required: [],
+    },
+    query_data: {
+        type: "object",
+        properties: {
+            endpoint: {
+                type: "string",
+                description: "API endpoint path (e.g., /v1/btc/market-data/mvrv)",
+            },
+            window: {
+                type: "string",
+                enum: ["hour", "day", "block"],
+                description: "Time window granularity",
+            },
+            limit: {
+                type: "number",
+                description: "Number of data points to return (default: 30, max: 1000)",
+            },
+            from: {
+                type: "string",
+                description: "Start date in ISO 8601 format (e.g., 2024-01-01)",
+            },
+            to: {
+                type: "string",
+                description: "End date in ISO 8601 format",
+            },
+        },
+        required: ["endpoint"],
+    },
+    describe_metric: {
+        type: "object",
+        properties: {
+            metric_id: {
+                type: "string",
+                description: "Metric ID to describe (e.g., mvrv, sopr, nupl, netflow)",
+            },
+        },
+        required: ["metric_id"],
+    },
+    market_summary: {
+        type: "object",
+        properties: {
+            asset: {
+                type: "string",
+                enum: ["btc", "eth"],
+                description: "Asset to analyze (default: btc)",
+            },
+        },
+        required: [],
+    },
+    trading_signal: {
+        type: "object",
+        properties: {
+            asset: {
+                type: "string",
+                enum: ["btc", "eth"],
+                description: "Asset to analyze (default: btc)",
+            },
+        },
+        required: [],
+    },
+    whale_activity: {
+        type: "object",
+        properties: {
+            asset: {
+                type: "string",
+                enum: ["btc", "eth"],
+                description: "Asset to analyze (default: btc)",
+            },
+            timeframe: {
+                type: "string",
+                enum: ["24h", "7d", "30d"],
+                description: "Timeframe for analysis (default: 24h)",
+            },
+        },
+        required: [],
+    },
+};
+/**
+ * Tool descriptions for each tool
+ */
+const toolDescriptions = {
+    initialize: "Initialize CryptoQuant session. Must be called before querying data.",
+    discover_endpoints: "Discover available API endpoints. Filter by asset (btc, eth, alt, stablecoin, erc20) and/or category (market-data, exchange-flows, network-data, etc.)",
+    query_data: "Query on-chain data from CryptoQuant API. Common endpoints: /v1/btc/market-data/mvrv (MVRV ratio), /v1/btc/market-indicator/sopr (SOPR), /v1/btc/exchange-flows/netflow (Exchange netflow)",
+    describe_metric: "Get explanation of a specific metric including thresholds and interpretation guidance. Use when user asks 'what is X?' about metrics like MVRV, SOPR, NUPL, etc.",
+    market_summary: "Get quick market status summary using key on-chain metrics (MVRV, SOPR, Netflow). Returns overall market sentiment with bullish/bearish signals.",
+    trading_signal: "Generate Buy/Sell/Hold trading signal with confidence score based on weighted on-chain metrics. Returns signal (STRONG BUY/BUY/HOLD/CAUTION/SELL) with detailed breakdown.",
+    whale_activity: "Monitor whale (large holder) activity including exchange flows and whale ratio. Identifies accumulation or distribution patterns by large players.",
+};
+/**
+ * Create CryptoQuant tool definitions in Anthropic SDK format
+ *
+ * Returns an array of tool definitions compatible with @anthropic-ai/sdk's
+ * client.messages.create() tools parameter.
+ *
+ * @returns Array of Anthropic-compatible tool definitions
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { createAnthropicTools } from '@cryptoquant_official/mcp/ai-sdk';
+ *
+ * const client = new Anthropic({ apiKey: process.env.CLAUDE_API_KEY });
+ *
+ * const response = await client.messages.create({
+ *   model: 'claude-sonnet-4-20250514',
+ *   max_tokens: 4096,
+ *   tools: createAnthropicTools(),
+ *   messages: [{ role: 'user', content: 'Analyze Bitcoin market' }],
+ * });
+ * ```
+ */
+export function createAnthropicTools() {
+    const toolNames = [
+        "initialize",
+        "discover_endpoints",
+        "query_data",
+        "describe_metric",
+        "market_summary",
+        "trading_signal",
+        "whale_activity",
+    ];
+    return toolNames.map((name) => ({
+        name,
+        description: toolDescriptions[name],
+        input_schema: toolSchemas[name],
+    }));
+}
+/**
+ * Create a tool executor function for handling tool calls
+ *
+ * Returns a function that executes CryptoQuant tools by name.
+ * Handles all type casting internally - consumers just pass the raw input.
+ *
+ * @param context - Execution context with API key
+ * @returns Async function that executes tools by name
+ *
+ * @example
+ * ```typescript
+ * import { createToolExecutor } from '@cryptoquant_official/mcp/ai-sdk';
+ *
+ * const executeTool = createToolExecutor({
+ *   cryptoquantApiKey: process.env.CRYPTOQUANT_API_KEY,
+ * });
+ *
+ * // In your agentic loop:
+ * for (const block of response.content) {
+ *   if (block.type === 'tool_use') {
+ *     const result = await executeTool(block.name, block.input);
+ *     toolResults.push({
+ *       type: 'tool_result',
+ *       tool_use_id: block.id,
+ *       content: JSON.stringify(result),
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export function createToolExecutor(context) {
+    const executors = {
+        initialize: (input) => executeInitialize(input, context),
+        discover_endpoints: (input) => executeDiscoverEndpoints(input),
+        query_data: (input) => executeQueryData(input, context),
+        describe_metric: (input) => executeDescribeMetric(input),
+        market_summary: (input) => executeMarketSummary(input, context),
+        trading_signal: (input) => executeTradingSignal(input, context),
+        whale_activity: (input) => executeWhaleActivity(input, context),
+    };
+    return async (name, input) => {
+        const executor = executors[name];
+        if (!executor) {
+            return { error: `Unknown tool: ${name}` };
+        }
+        return executor(input);
+    };
+}
+/**
+ * Get tool names as an array
+ * Useful for validation or iteration
+ */
+export function getToolNames() {
+    return [
+        "initialize",
+        "discover_endpoints",
+        "query_data",
+        "describe_metric",
+        "market_summary",
+        "trading_signal",
+        "whale_activity",
+    ];
+}
+/**
+ * Check if a string is a valid CryptoQuant tool name
+ */
+export function isValidToolName(name) {
+    return getToolNames().includes(name);
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/ai-sdk/anthropic.js.map

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

package/dist/ai-sdk/execute.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool execution logic for CryptoQuant tools
+ * Shared between AI SDK integration and chat-proxy
+ */
+import type { DescribeMetricParams, DiscoverEndpointsParams, InitializeParams, MarketSummaryParams, QueryDataParams, TradingSignalParams, WhaleActivityParams } from "./schemas.js";
+import type { DescribeResult, DiscoverResult, InitializeResult, MarketSummaryResult, QueryResult, TradingSignalResult, ToolExecutionContext, WhaleActivityResult } from "./types.js";
+/**
+ * Execute initialize tool
+ */
+export declare function executeInitialize(params: InitializeParams, context: ToolExecutionContext): Promise<InitializeResult>;
+/**
+ * Execute discover_endpoints tool
+ */
+export declare function executeDiscoverEndpoints(params: DiscoverEndpointsParams): Promise<DiscoverResult>;
+/**
+ * Execute query_data tool
+ */
+export declare function executeQueryData(params: QueryDataParams, _context: ToolExecutionContext): Promise<QueryResult>;
+/**
+ * Execute describe_metric tool
+ */
+export declare function executeDescribeMetric(params: DescribeMetricParams): Promise<DescribeResult>;
+/**
+ * Execute market_summary tool
+ */
+export declare function executeMarketSummary(params: MarketSummaryParams, _context: ToolExecutionContext): Promise<MarketSummaryResult>;
+/**
+ * Execute trading_signal tool
+ */
+export declare function executeTradingSignal(params: TradingSignalParams, _context: ToolExecutionContext): Promise<TradingSignalResult>;
+/**
+ * Execute whale_activity tool
+ */
+export declare function executeWhaleActivity(params: WhaleActivityParams, _context: ToolExecutionContext): Promise<WhaleActivityResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/ai-sdk/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/execute.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AASpB;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA8C3B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAoCzB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAqHtB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAgBzB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CA6F9B;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAuF9B;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CA8G9B"}