@cryptoquant_official/mcp 0.0.5 → 0.0.7

package/README.md

@@ -1,20 +1,35 @@
 # @cryptoquant_official/mcp
 
-CryptoQuant MCP Server for on-chain analytics in Claude and AI coding agents.
+CryptoQuant on-chain analytics for Claude and AI applications.
 
-## Installation
+## Integration Modes
 
-### Claude Code / Claude Desktop
+| Mode | Use Case | Streaming | Setup |
+|------|----------|-----------|-------|
+| [**MCP**](#mode-1-mcp-claude-desktopcode) | Claude Desktop, Claude Code, Cursor | - | Config file |
+| [**AI SDK**](#mode-2-ai-sdk-nextjs) | Next.js web apps | ✅ | npm package |
+| [**HTTP**](#mode-3-http-chat-proxy) | Any backend / non-Node.js | ❌ | Standalone server |
 
-Add to your MCP configuration:
+**Get your API key**: [cryptoquant.com/settings/api](https://cryptoquant.com/settings/api)
+
+---
+
+## Mode 1: MCP (Claude Desktop/Code)
+
+For Claude Desktop, Claude Code, Cursor, and other MCP-compatible apps.
 
-**Claude Code** (`~/.claude/mcp.json` or project `.mcp.json`):
+### Setup
+
+**Claude Code** (`~/.claude/mcp.json` or `.mcp.json`):
 ```json
 {
   "mcpServers": {
     "cryptoquant": {
       "command": "npx",
-      "args": ["-y", "@cryptoquant_official/mcp"]
+      "args": ["-y", "@cryptoquant_official/mcp"],
+      "env": {
+        "CRYPTOQUANT_API_KEY": "your-api-key"
+      }
     }
   }
 }
@@ -26,51 +41,302 @@ Add to your MCP configuration:
   "mcpServers": {
     "cryptoquant": {
       "command": "npx",
-      "args": ["-y", "@cryptoquant_official/mcp"]
+      "args": ["-y", "@cryptoquant_official/mcp"],
+      "env": {
+        "CRYPTOQUANT_API_KEY": "your-api-key"
+      }
     }
   }
 }
 ```
 
-Then restart your app.
+Restart your app after configuration.
+
+### Usage
+
+```
+User: "Is Bitcoin overvalued?"
+
+Claude: Let me check the MVRV ratio...
+→ Calls query_data({ endpoint: "/v1/btc/market-data/mvrv" })
+→ Returns analysis with current valuation status
+```
+
+---
 
-### Other MCP-Compatible Apps (Cursor, etc.)
+## Mode 2: AI SDK (Next.js)
+
+For Next.js web apps with streaming responses via Vercel AI SDK.
+
+### Installation
+
+```bash
+npm install @cryptoquant_official/mcp ai @ai-sdk/react @ai-sdk/anthropic
+```
+
+### Environment Variables
+
+```env
+# .env.local
+ANTHROPIC_API_KEY=sk-ant-...
+CRYPTOQUANT_API_KEY=cq-...
+```
 
-Add the same configuration to your app's MCP settings file.
+> `@ai-sdk/anthropic` automatically reads `ANTHROPIC_API_KEY`.
 
-## Authentication
+### API Route
 
-Configure your API key using one of these methods:
+```typescript
+// app/api/chat/route.ts
+import { streamText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { createCryptoQuantTools } from "@cryptoquant_official/mcp/ai-sdk";
 
-### Option 1: Environment Variable (Recommended)
+export const maxDuration = 60;
 
-Add `CRYPTOQUANT_API_KEY` to your MCP config:
+export async function POST(req: Request) {
+  const { messages } = await req.json();
 
+  const result = streamText({
+    model: anthropic("claude-sonnet-4-20250514"),
+    messages,
+    tools: createCryptoQuantTools({
+      cryptoquantApiKey: process.env.CRYPTOQUANT_API_KEY!,
+    }),
+    maxSteps: 5,
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+### Client Component
+
+```tsx
+"use client";
+import { useChat } from "@ai-sdk/react";
+
+export function CryptoChat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{m.content}</div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### API Reference
+
+```typescript
+// Option 1: With explicit API key
+import { createCryptoQuantTools } from "@cryptoquant_official/mcp/ai-sdk";
+const tools = createCryptoQuantTools({ cryptoquantApiKey: "cq-..." });
+
+// Option 2: Using CRYPTOQUANT_API_KEY env var
+import { cryptoQuantTools } from "@cryptoquant_official/mcp/ai-sdk";
+streamText({ tools: cryptoQuantTools, ... });
+```
+
+See [examples/nextjs-ai-sdk/](examples/nextjs-ai-sdk/) for complete example.
+
+---
+
+## Mode 3: HTTP (Chat Proxy)
+
+Standalone HTTP server for any backend or non-Node.js environments.
+
+### Start Server
+
+```bash
+MCP_TRANSPORT=http npx @cryptoquant_official/mcp
+# Server runs at http://localhost:3100
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/chat` | POST | Chat with Claude + automatic tool execution |
+| `/tools/schema` | GET | Get Claude API tool definitions |
+| `/health` | GET | Server health check |
+| `/mcp` | POST/GET/DELETE | Streamable HTTP MCP protocol |
+
+### POST /chat
+
+```bash
+curl -X POST http://localhost:3100/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Analyze Bitcoin MVRV",
+    "claude_api_key": "sk-ant-...",
+    "cryptoquant_api_key": "cq-..."
+  }'
+```
+
+**Request:**
 ```json
 {
-  "mcpServers": {
-    "cryptoquant": {
-      "command": "npx",
-      "args": ["-y", "@cryptoquant_official/mcp"],
-      "env": {
-        "CRYPTOQUANT_API_KEY": "your-api-key"
-      }
-    }
+  "message": "Is Bitcoin overvalued?",
+  "claude_api_key": "sk-ant-...",
+  "cryptoquant_api_key": "cq-...",
+  "conversation_id": "optional-session-id",
+  "model": "claude-sonnet-4-20250514"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "response": "Based on the current MVRV of 2.1...",
+  "tool_calls": [
+    { "name": "initialize", "result": { "success": true } },
+    { "name": "query_data", "result": { "data": [...] } }
+  ],
+  "conversation_id": "abc-123",
+  "usage": { "input_tokens": 150, "output_tokens": 300 }
+}
+```
+
+### Next.js with HTTP Mode
+
+```typescript
+// app/api/chat/route.ts
+export async function POST(request: Request) {
+  const { message, conversation_id } = await request.json();
+
+  const response = await fetch("http://localhost:3100/chat", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      message,
+      claude_api_key: process.env.CLAUDE_API_KEY,
+      cryptoquant_api_key: process.env.CRYPTOQUANT_API_KEY,
+      conversation_id,
+    }),
+  });
+
+  return Response.json(await response.json());
+}
+```
+
+See [examples/nextjs/](examples/nextjs/) for complete example.
+
+---
+
+## Custom Cache Storage
+
+The MCP server caches API discovery data to reduce startup time. By default:
+- **CLI/Local**: File storage (`~/.cryptoquant/discovery-cache.json`)
+- **Web Server**: No caching (requires Redis configuration)
+
+### Redis Storage for Web Servers
+
+For production web servers or serverless environments, configure Redis storage:
+
+```typescript
+// app/lib/cryptoquant-cache.ts
+import { createClient } from "redis";
+import { setRedisStorage, type CacheStorage } from "@cryptoquant_official/mcp";
+
+const redis = createClient({ url: process.env.REDIS_URL });
+
+export async function configureRedisCache() {
+  if (!redis.isOpen) {
+    await redis.connect();
   }
+
+  const redisStorage: CacheStorage = {
+    type: "redis",
+
+    async read(apiUrl, apiKeyPrefix) {
+      const key = `cryptoquant:cache:${apiUrl}:${apiKeyPrefix}`;
+      const data = await redis.get(key);
+      return data ? JSON.parse(data) : null;
+    },
+
+    async write(apiUrl, cache) {
+      const key = `cryptoquant:cache:${apiUrl}:${cache.metadata.api_key_prefix}`;
+      const ttl = 7 * 24 * 60 * 60; // 7 days
+      await redis.setEx(key, ttl, JSON.stringify(cache));
+    },
+
+    async invalidate(apiUrl, apiKeyPrefix) {
+      if (apiKeyPrefix) {
+        await redis.del(`cryptoquant:cache:${apiUrl}:${apiKeyPrefix}`);
+      } else {
+        const keys = await redis.keys(`cryptoquant:cache:${apiUrl}:*`);
+        if (keys.length > 0) await redis.del(keys);
+      }
+    },
+
+    async clearAll() {
+      const keys = await redis.keys("cryptoquant:cache:*");
+      if (keys.length > 0) await redis.del(keys);
+    },
+
+    getPath() {
+      return "[redis]";
+    },
+  };
+
+  setRedisStorage(redisStorage);
 }
 ```
 
-### Option 2: Direct Parameter
+```typescript
+// app/api/chat/route.ts
+import { configureRedisCache } from "@/lib/cryptoquant-cache";
 
-Call `initialize()` with your API key:
+// Configure once at startup
+await configureRedisCache();
 
+export async function POST(req: Request) {
+  // ... your chat handler
+}
 ```
-initialize(api_key='your-api-key')
+
+### CacheStorage Interface
+
+Implement this interface for custom storage backends:
+
+```typescript
+interface CacheStorage {
+  /** Storage type identifier */
+  readonly type: "file" | "redis" | "auto";
+
+  /** Read cache data, returns null if not found */
+  read(apiUrl: string, apiKeyPrefix?: string): Promise<DiscoveryCacheSchema | null> | DiscoveryCacheSchema | null;
+
+  /** Write cache data */
+  write(apiUrl: string, cache: DiscoveryCacheSchema): Promise<void> | void;
+
+  /** Delete cache for specific API URL */
+  invalidate(apiUrl: string, apiKeyPrefix?: string): Promise<void> | void;
+
+  /** Clear all caches */
+  clearAll(): Promise<void> | void;
+
+  /** Get storage path for display */
+  getPath(apiUrl: string): string;
+}
 ```
 
-**Get your API key**: [cryptoquant.com/settings/api](https://cryptoquant.com/settings/api)
+See [examples/redis-cache/](examples/redis-cache/) for complete implementation.
+
+---
 
-## Available Tools
+## Reference
+
+### Available Tools
 
 | Tool | Description |
 |------|-------------|
@@ -79,54 +345,34 @@ initialize(api_key='your-api-key')
 | `get_endpoint_info` | Get endpoint parameter details |
 | `query_data` | Query raw on-chain data |
 | `describe_metric` | Get metric descriptions and thresholds |
-| `list_assets` | List supported assets (BTC, ETH, etc.) |
+| `list_assets` | List supported assets |
 | `reset_session` | Clear session / switch accounts |
 
-## Supported Assets
+### Supported Assets
 
 BTC, ETH, ALT, Stablecoin, ERC20, TRX, XRP
 
-## Example Usage
-
-```
-User: "Is Bitcoin overvalued?"
-
-Claude: Let me check the MVRV ratio...
-→ Calls query_data({ endpoint: "/v1/btc/market-data/mvrv" })
-→ Returns analysis with current valuation status
-```
-
-## Environment Variables
+### Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CRYPTOQUANT_API_KEY` | API key for authentication | (none) |
-| `DEBUG` | Enable debug logging (`true` or `1`) | (disabled) |
-
-Example with debug logging:
-```json
-{
-  "mcpServers": {
-    "cryptoquant": {
-      "command": "npx",
-      "args": ["-y", "@cryptoquant_official/mcp"],
-      "env": {
-        "CRYPTOQUANT_API_KEY": "your-api-key",
-        "DEBUG": "true"
-      }
-    }
-  }
-}
-```
+| `CRYPTOQUANT_API_KEY` | CryptoQuant API key | - |
+| `ANTHROPIC_API_KEY` | Anthropic API key (AI SDK mode) | - |
+| `MCP_TRANSPORT` | Transport mode (`stdio` / `http`) | `stdio` |
+| `MCP_HTTP_PORT` | HTTP server port | `3100` |
+| `MCP_HTTP_HOST` | HTTP server host | `0.0.0.0` |
+| `MCP_CORS_ORIGINS` | CORS allowed origins | `*` |
+| `DEBUG` | Enable debug logging | - |
 
-## Requirements
+### Requirements
 
 - Node.js 18+
 - CryptoQuant API key
+- Anthropic API key (for AI SDK / HTTP mode)
 
 ## Links
 
-- [Full Documentation](https://github.com/CryptoQuantOfficial/cryptoquant-skills)
+- [GitHub](https://github.com/CryptoQuantOfficial/cryptoquant-skills)
 - [CryptoQuant](https://cryptoquant.com)
 - [API Docs](https://docs.cryptoquant.com)
 

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"}