@cryptoquant_official/mcp 0.0.4 → 0.0.6-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CryptoQuant
+
+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

@@ -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,307 @@ 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
+# Using npx
+npx @cryptoquant_official/mcp/http
+
+# Or if installed locally
+node dist/http/index.js
+
+# 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,31 +350,53 @@ 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
+### Environment Variables
 
-```
-User: "Is Bitcoin overvalued?"
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CRYPTOQUANT_API_KEY` | CryptoQuant API key | - |
+| `ANTHROPIC_API_KEY` | Anthropic API key (AI SDK mode) | - |
+| `MCP_HTTP_PORT` | HTTP server port | `3100` |
+| `MCP_HTTP_HOST` | HTTP server host | `127.0.0.1` |
+| `MCP_CORS_ORIGINS` | CORS allowed origins (comma-separated) | `http://localhost:3000,http://localhost:5173` |
+| `MCP_ENABLE_LEGACY_SSE` | Enable legacy SSE transport | `false` |
+| `DEBUG` | Enable debug logging | - |
 
-Claude: Let me check the MVRV ratio...
-→ Calls query_data({ endpoint: "/v1/btc/market-data/mvrv" })
-→ Returns analysis with current valuation status
+### HTTP Security Configuration
+
+The HTTP server includes several security features enabled by default:
+
+| Feature | Description | Configuration |
+|---------|-------------|---------------|
+| **Local binding** | Server binds to localhost only | Set `MCP_HTTP_HOST=0.0.0.0` for external access |
+| **CORS restriction** | Only localhost origins allowed | Set `MCP_CORS_ORIGINS` for production domains |
+| **Rate limiting** | 100 req/15min (general), 30 req/15min (/chat) | Built-in, no configuration needed |
+| **Minimal health endpoint** | `/health` returns only `{ status: "ok" }` | No sensitive info exposed |
+
+**Production deployment example:**
+
+```bash
+export MCP_HTTP_HOST=0.0.0.0
+export MCP_CORS_ORIGINS=https://myapp.com,https://api.myapp.com
+npx @cryptoquant_official/mcp/http
 ```
 
-## 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/anthropic.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 type { ToolExecutionContext } from "./types.js";
+/**
+ * Tool names available in CryptoQuant
+ */
+export type CryptoQuantToolName = "initialize" | "discover_endpoints" | "query_data" | "describe_metric" | "market_summary" | "trading_signal" | "whale_activity";
+/**
+ * Anthropic Tool definition interface (matches @anthropic-ai/sdk types)
+ * Defined here to avoid requiring @anthropic-ai/sdk as a dependency
+ */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/**
+ * Cache TTL recommendations for each tool (in seconds)
+ * Consumers can use this to implement caching strategies
+ */
+export declare const toolCacheTTL: Record<CryptoQuantToolName, number>;
+/**
+ * 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 declare function createAnthropicTools(): AnthropicTool[];
+/**
+ * Type for the tool executor function
+ */
+export type ToolExecutorFn = (name: string, input: Record<string, unknown>) => Promise<unknown>;
+/**
+ * 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 declare function createToolExecutor(context: ToolExecutionContext): ToolExecutorFn;
+/**
+ * Get tool names as an array
+ * Useful for validation or iteration
+ */
+export declare function getToolNames(): CryptoQuantToolName[];
+/**
+ * Check if a string is a valid CryptoQuant tool name
+ */
+export declare function isValidToolName(name: string): name is CryptoQuantToolName;
+//# sourceMappingURL=anthropic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoBH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,oBAAoB,GACpB,YAAY,GACZ,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAQ5D,CAAC;AAuIF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,EAAE,CAgBtD;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,oBAAoB,GAC5B,cAAc,CA+BhB;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,mBAAmB,EAAE,CAUpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,mBAAmB,CAEzE"}