modernity-mcp 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# modernity-mcp
+
+MCP (Model Context Protocol) server for [Modernity](https://modernity.live) — connect live data to Cursor and Claude.
+
+## Prerequisites
+
+- **Node.js** 18 or newer
+- **API key** from [modernity.live](https://modernity.live) (get one free, no credit card)
+
+## Quick Start
+
+```bash
+# Verify your key works
+npx -y modernity-mcp --key=YOUR_API_KEY --test
+```
+
+If you see `Success! API is online and your key is valid.`, you're ready to connect.
+
+## Connect to Cursor
+
+1. Open **Cursor Settings** (Cmd+Shift+J or Ctrl+Shift+J)
+2. Go to **Features** → **MCP**
+3. Click **+ Add New MCP Server**
+4. Fill in:
+   - **Name:** Modernity
+   - **Type:** stdio
+   - **Command:** `npx`
+   - **Args:** `-y modernity-mcp --key=YOUR_API_KEY`
+5. Set **MODERNITY_API_KEY** in env, or pass `--key=YOUR_API_KEY` in Args
+6. Save. The dot turns green when connected.
+
+## Connect to Claude Desktop
+
+1. Open your Claude config file:
+   - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+2. Add to the `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "modernity": {
+      "command": "npx",
+      "args": ["-y", "modernity-mcp"],
+      "env": {
+        "MODERNITY_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop. Look for the plug icon.
+
+## Authentication
+
+Provide your API key in one of two ways:
+
+- **Environment variable:** `MODERNITY_API_KEY=your_key`
+- **CLI argument:** `--key=your_key`
+
+The server exits immediately with an error if no key is provided.
+
+## Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `get_recent_data` | Fetch recent messages from the live stream. Optional: `limit`, `source`, `category` |
+| `query_topic` | Search for a topic across all sources. Required: `topic`. Optional: `timeframe`, `limit`, `format` |
+| `multi_schema_query` | Query across Vespa schemas (doc, ticker, news, geo_alert). Required: `query`. Optional: `schemas`, `timeframe`, `limit` |
+| `analyze_topic` | AI-powered topic analysis with recommendations. Required: `topic` |
+| `get_sources` | List all available data sources and categories |
+| `get_stream_stats` | Get live stream health and statistics |
+| `get_key_info` | Check API key tier, usage, and rate limits |
+| `check_health` | Verify the API is online |
+| `get_pricing` | Get all pricing tiers and features |
+
+## Resources
+
+- `modernity://health` — API health status
+- `modernity://sources` — Available sources and categories
+- `modernity://pricing` — Pricing tiers
+
+## Example Prompts
+
+- "Check the stream status"
+- "Get the last 20 data points"
+- "Query for Bitcoin developments"
+- "What's my API key usage?"
+- "List all data sources"
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| "MODERNITY_API_KEY... is required" | Add the key via env or `--key=` |
+| "Your API key is invalid" | Regenerate at [modernity.live/dashboard](https://modernity.live/dashboard) |
+| "Rate limit exceeded" | Wait before retrying; check tier limits |
+| "Tool not found" | Restart Cursor/Claude after config changes |
+| Connection fails | Run `npx -y modernity-mcp --key=YOUR_KEY --test` to isolate the issue |
+
+## Publish to npm
+
+```bash
+cd mcp
+npm login
+npm publish --access public
+```

package/dist/api-client.d.ts

@@ -0,0 +1,2 @@
+import axios from "axios";
+export declare function createApiClient(apiBase: string, apiKey: string): axios.AxiosInstance;

package/dist/api-client.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiClient = createApiClient;
+const axios_1 = __importDefault(require("axios"));
+function createApiClient(apiBase, apiKey) {
+    const client = axios_1.default.create({
+        baseURL: apiBase,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+    });
+    client.interceptors.response.use((res) => res, (err) => {
+        if (err.response?.status === 401) {
+            throw new Error("Your API key is invalid. Please check your config.");
+        }
+        if (err.response?.status === 403) {
+            throw new Error("Access denied. Your API key may not have permission for this operation.");
+        }
+        if (err.response?.status === 429) {
+            const retryAfter = err.response?.data?.retry_after_seconds;
+            const msg = retryAfter
+                ? `Rate limit exceeded. Retry in ${Math.ceil(retryAfter)} seconds.`
+                : "Rate limit exceeded. Please wait before retrying.";
+            throw new Error(msg);
+        }
+        const detail = err.response?.data?.detail;
+        throw new Error(detail || err.message || "API request failed.");
+    });
+    return client;
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export declare function getConfig(): {
+    apiBase: string;
+    apiKey: string;
+};
+export declare function shouldRunTest(): boolean;

package/dist/config.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+exports.shouldRunTest = shouldRunTest;
+const API_BASE = "https://api.modernity.live";
+function getApiKey() {
+    const envKey = process.env.MODERNITY_API_KEY;
+    const argKey = process.argv.find((arg) => arg.startsWith("--key="))?.split("=")[1];
+    const key = envKey || argKey?.trim();
+    if (!key) {
+        console.error("Error: MODERNITY_API_KEY environment variable or --key= argument is required.");
+        process.exit(1);
+    }
+    return key;
+}
+function getConfig() {
+    return {
+        apiBase: API_BASE,
+        apiKey: getApiKey(),
+    };
+}
+function shouldRunTest() {
+    return process.argv.includes("--test");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const config_js_1 = require("./config.js");
+const api_client_js_1 = require("./api-client.js");
+const tools_js_1 = require("./tools.js");
+const resources_js_1 = require("./resources.js");
+async function runTest() {
+    const { apiBase, apiKey } = (0, config_js_1.getConfig)();
+    const client = (0, api_client_js_1.createApiClient)(apiBase, apiKey);
+    try {
+        await client.get("/health");
+        await client.get("/v1/keys/info");
+        console.log("Success! API is online and your key is valid.");
+        process.exit(0);
+    }
+    catch (err) {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+async function runServer() {
+    const { apiBase, apiKey } = (0, config_js_1.getConfig)();
+    const client = (0, api_client_js_1.createApiClient)(apiBase, apiKey);
+    const server = new index_js_1.Server({
+        name: "modernity-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: (0, tools_js_1.getToolDefinitions)(),
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const result = await (0, tools_js_1.handleToolCall)(client, name, args ?? {});
+        return {
+            content: [{ type: "text", text: result.text }],
+            isError: result.isError,
+        };
+    });
+    server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+        resources: resources_js_1.RESOURCES,
+    }));
+    server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        const content = await (0, resources_js_1.readResource)(client, uri);
+        return {
+            contents: [content],
+        };
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Server running on stdio");
+}
+async function main() {
+    if ((0, config_js_1.shouldRunTest)()) {
+        await runTest();
+        return;
+    }
+    await runServer();
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,12 @@
+import type { AxiosInstance } from "axios";
+export declare const RESOURCES: {
+    uri: string;
+    name: string;
+    mimeType: string;
+    description: string;
+}[];
+export declare function readResource(client: AxiosInstance, uri: string): Promise<{
+    uri: string;
+    mimeType: string;
+    text: string;
+}>;

package/dist/resources.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCES = void 0;
+exports.readResource = readResource;
+exports.RESOURCES = [
+    {
+        uri: "modernity://health",
+        name: "API Health Status",
+        mimeType: "application/json",
+        description: "Current health and status of the Modernity API",
+    },
+    {
+        uri: "modernity://sources",
+        name: "Available Sources",
+        mimeType: "application/json",
+        description: "List of all data sources and categories",
+    },
+    {
+        uri: "modernity://pricing",
+        name: "Pricing Tiers",
+        mimeType: "application/json",
+        description: "Pricing tiers and feature comparison",
+    },
+];
+async function readResource(client, uri) {
+    let path;
+    switch (uri) {
+        case "modernity://health":
+            path = "/health";
+            break;
+        case "modernity://sources":
+            path = "/v1/sources";
+            break;
+        case "modernity://pricing":
+            path = "/v1/pricing";
+            break;
+        default:
+            throw new Error(`Resource not found: ${uri}`);
+    }
+    const res = await client.get(path);
+    return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(res.data, null, 2),
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,14 @@
+import type { AxiosInstance } from "axios";
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+    };
+}
+export declare function getToolDefinitions(): ToolDef[];
+export declare function handleToolCall(client: AxiosInstance, name: string, args: Record<string, unknown>): Promise<{
+    text: string;
+    isError?: boolean;
+}>;

package/dist/tools.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToolDefinitions = getToolDefinitions;
+exports.handleToolCall = handleToolCall;
+function getToolDefinitions() {
+    return [
+        {
+            name: "get_recent_data",
+            description: "Fetch recent messages from the live stream buffer. Optionally filter by source or category.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Number of messages to return (default 100, max 1000)",
+                    },
+                    source: {
+                        type: "string",
+                        description: "Optional source filter (e.g. bluesky, coingecko, usgs)",
+                    },
+                    category: {
+                        type: "string",
+                        description: "Optional category filter (finance, crypto, social)",
+                    },
+                },
+            },
+        },
+        {
+            name: "query_topic",
+            description: "Search for a topic across all data sources with configurable timeframe and limit.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    topic: {
+                        type: "string",
+                        description: "Natural language topic or query to search for",
+                    },
+                    timeframe: {
+                        type: "string",
+                        description: "Data freshness: 60s, 5m, 10m, 20m, 1h, 24h (default 60s)",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max results to return (default 10, max 100)",
+                    },
+                    format: {
+                        type: "string",
+                        description: "Output format: json or markdown (default json)",
+                    },
+                },
+            },
+        },
+        {
+            name: "multi_schema_query",
+            description: "Query across multiple Vespa schemas (doc, ticker, news, geo_alert) with a single query string.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Natural language query",
+                    },
+                    schemas: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional schemas to query: doc, ticker, news, geo_alert",
+                    },
+                    timeframe: {
+                        type: "string",
+                        description: "Data freshness: 60s, 5m, 10m, 20m, 1h, 24h (default 10m)",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max results per schema (default 10, max 100)",
+                    },
+                },
+            },
+        },
+        {
+            name: "analyze_topic",
+            description: "Use AI to analyze a topic and get query recommendations, relevant sources, and search terms.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    topic: {
+                        type: "string",
+                        description: "Topic to analyze",
+                    },
+                },
+            },
+        },
+        {
+            name: "get_sources",
+            description: "List all available data sources and categories.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "get_stream_stats",
+            description: "Get live stream health and statistics (status, hub stats).",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "get_key_info",
+            description: "Check your API key tier, usage, rate limits, and remaining quotas.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "check_health",
+            description: "Verify the Modernity API is online and healthy.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "get_pricing",
+            description: "Get all pricing tiers and features.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+    ];
+}
+async function handleToolCall(client, name, args) {
+    try {
+        switch (name) {
+            case "get_recent_data": {
+                const limit = args.limit ?? 100;
+                const source = args.source;
+                const category = args.category;
+                const params = { limit };
+                if (source)
+                    params.source = source;
+                if (category)
+                    params.category = category;
+                const res = await client.get("/v1/recent", { params });
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "query_topic": {
+                const topic = args.topic;
+                if (!topic)
+                    throw new Error("topic is required");
+                const res = await client.post("/v1/query", {
+                    topic,
+                    timeframe: args.timeframe ?? "60s",
+                    limit: args.limit ?? 10,
+                    format: args.format ?? "json",
+                });
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "multi_schema_query": {
+                const query = args.query;
+                if (!query)
+                    throw new Error("query is required");
+                const res = await client.post("/v1/query/multi", {
+                    query,
+                    schemas: args.schemas,
+                    timeframe: args.timeframe ?? "10m",
+                    limit: args.limit ?? 10,
+                });
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "analyze_topic": {
+                const topic = args.topic;
+                if (!topic)
+                    throw new Error("topic is required");
+                const res = await client.post("/v1/analyze", { topic });
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "get_sources": {
+                const res = await client.get("/v1/sources");
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "get_stream_stats": {
+                const res = await client.get("/v1/live/stats");
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "get_key_info": {
+                const res = await client.get("/v1/keys/info");
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "check_health": {
+                const res = await client.get("/health");
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            case "get_pricing": {
+                const res = await client.get("/v1/pricing");
+                return { text: JSON.stringify(res.data, null, 2) };
+            }
+            default:
+                throw new Error(`Tool not found: ${name}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { text: msg, isError: true };
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "modernity-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Modernity — live data streaming for Cursor and Claude",
+  "main": "dist/index.js",
+  "bin": {
+    "modernity-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modernity",
+    "cursor",
+    "claude",
+    "live-data",
+    "streaming"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}