{"id":31626477,"url":"https://github.com/danilobatson/lunarcrush-mcp-sdk","last_synced_at":"2026-04-28T21:34:57.304Z","repository":{"id":314208352,"uuid":"1054586618","full_name":"danilobatson/lunarcrush-mcp-sdk","owner":"danilobatson","description":"Lightweight SDK for connecting LLMs to LunarCrush social crypto data via Model Context Protocol (MCP)","archived":false,"fork":false,"pushed_at":"2025-09-11T04:39:40.000Z","size":16,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T19:53:10.627Z","etag":null,"topics":["ai","artificial-intelligence","bitcoin","blockchain","crypto","crypto-api","cryptocurrency","llm","lunarcrush","mcp","model-context-protocol","nodejs","sentiment-analysis","social-data","trading","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@jamaalbuilds/lunarcrush-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danilobatson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T04:03:07.000Z","updated_at":"2025-09-11T04:44:02.000Z","dependencies_parsed_at":"2025-09-11T07:48:26.911Z","dependency_job_id":"e24c1dec-49fa-4a58-a5d1-4cf1c9462ccd","html_url":"https://github.com/danilobatson/lunarcrush-mcp-sdk","commit_stats":null,"previous_names":["danilobatson/lunarcrush-mcp-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/danilobatson/lunarcrush-mcp-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilobatson%2Flunarcrush-mcp-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilobatson%2Flunarcrush-mcp-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilobatson%2Flunarcrush-mcp-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilobatson%2Flunarcrush-mcp-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danilobatson","download_url":"https://codeload.github.com/danilobatson/lunarcrush-mcp-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilobatson%2Flunarcrush-mcp-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32400868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","bitcoin","blockchain","crypto","crypto-api","cryptocurrency","llm","lunarcrush","mcp","model-context-protocol","nodejs","sentiment-analysis","social-data","trading","typescript"],"created_at":"2025-10-06T19:52:34.074Z","updated_at":"2026-04-28T21:34:57.298Z","avatar_url":"https://github.com/danilobatson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌙 LunarCrush MCP SDK\n\n[![npm version](https://badge.fury.io/js/%40jamaalbuilds%2Flunarcrush-mcp.svg)](https://badge.fury.io/js/%40jamaalbuilds%2Flunarcrush-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nLightweight, LLM-agnostic SDK for connecting any LLM to LunarCrush social crypto data via Model Context Protocol (MCP).\n\n## 🚀 Features\n\n- **Zero Configuration** - Just your API key and you're ready\n- **100% Dynamic** - Auto-discovers tools, future-proof against changes\n- **LLM Agnostic** - Raw schemas, you format for your LLM choice\n- **Lightweight** - Minimal dependencies, zero maintenance needed\n- **TypeScript Ready** - Full type safety and IntelliSense support\n\n## 📦 Installation\n\n```bash\nnpm install @jamaalbuilds/lunarcrush-mcp @modelcontextprotocol/sdk\n```\n\n## 🔑 Quick Start\n\n```typescript\nimport LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';\n\n// 1. Connect (one time setup)\nconst mcp = new LunarCrushMCP('your-api-key');\nawait mcp.connect();\n\n// 2. Get tools for your LLM\nconst tools = mcp.getToolsWithDetails();\n// Raw schemas - you format for your LLM\n\n// 3. LLM calls tools through SDK\nconst result = await mcp.callTool('Topic', { topic: 'bitcoin' });\n\n// 4. Clean up when done\nawait mcp.disconnect();\n```\n\n## 🤖 LLM Integration Examples\n\n### OpenAI Function Calling\n\n```typescript\nimport OpenAI from 'openai';\nimport LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';\n\nconst openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });\nconst mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);\nawait mcp.connect();\n\n// Format tools for OpenAI (you control the formatting)\nconst tools = mcp.getToolsWithDetails();\nconst functions = tools.map(tool =\u003e ({\n  name: tool.name,\n  description: tool.description,\n  parameters: tool.schema\n}));\n\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'What is Bitcoin trending at?' }],\n  functions,\n  function_call: 'auto'\n});\n\n// Execute function call\nif (response.choices[0].message.function_call) {\n  const { name, arguments: args } = response.choices[0].message.function_call;\n  const result = await mcp.executeFunction(name, args);\n  console.log('Bitcoin data:', result);\n}\n```\n\n### Anthropic Tool Use\n\n```typescript\nimport Anthropic from '@anthropic-ai/sdk';\nimport LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';\n\nconst anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });\nconst mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);\nawait mcp.connect();\n\n// Format tools for Anthropic (you control the formatting)\nconst toolsData = mcp.getToolsWithDetails();\nconst tools = toolsData.map(tool =\u003e ({\n  name: tool.name,\n  description: tool.description,\n  input_schema: tool.schema\n}));\n\nconst response = await anthropic.messages.create({\n  model: 'claude-3-sonnet-20240229',\n  max_tokens: 1000,\n  messages: [{ role: 'user', content: 'Analyze Bitcoin social sentiment' }],\n  tools\n});\n\n// Execute tool calls\nfor (const content of response.content) {\n  if (content.type === 'tool_use') {\n    const result = await mcp.callTool(content.name, content.input);\n    console.log('Analysis result:', result);\n  }\n}\n```\n\n### Google Gemini Integration\n\n```typescript\nimport { GoogleGenerativeAI } from '@google/generative-ai';\nimport LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';\n\nconst genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);\nconst mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);\nawait mcp.connect();\n\n// Get detailed tool information for better LLM understanding\nconst toolsData = mcp.getToolsWithDetails();\n\nconst prompt = `You are a crypto analyst with access to LunarCrush tools.\n\nAVAILABLE TOOLS:\n${toolsData.map(tool =\u003e {\n  const { name, description, parameterInfo } = tool;\n  return `${name}: ${description}\n  Required parameters: ${parameterInfo.required.join(', ') || 'none'}\n  Optional parameters: ${parameterInfo.optional.join(', ') || 'none'}\n  Parameter types: ${JSON.stringify(parameterInfo.types)}\n  Enum values: ${JSON.stringify(parameterInfo.enums)}`;\n}).join('\\n\\n')}\n\nTask: Analyze Bitcoin's current performance and social sentiment.\nChoose appropriate tools with EXACT parameter formatting.\n\nCRITICAL:\n- Use arrays for array parameters: [\"item1\", \"item2\"]\n- Use exact enum values from the options provided\n- Follow parameter types precisely\n\nRespond with JSON:\n{\n  \"selected_tools\": [\n    {\n      \"name\": \"exact_tool_name\",\n      \"arguments\": {exact_arguments_with_proper_types},\n      \"reasoning\": \"why you chose this tool\"\n    }\n  ]\n}`;\n\nconst model = genAI.getGenerativeModel({ model: 'gemini-2.0-flash-lite' });\nconst result = await model.generateContent(prompt);\n\n// Parse and execute chosen tools\nconst response = JSON.parse(result.response.text());\nfor (const choice of response.selected_tools) {\n  const toolResult = await mcp.callTool(choice.name, choice.arguments);\n  console.log(`${choice.name} result:`, toolResult);\n}\n```\n\n## 📋 Available Methods\n\n### Connection Management\n```typescript\nconst mcp = new LunarCrushMCP(apiKey);\nawait mcp.connect();              // Connect to MCP server\nawait mcp.disconnect();           // Clean disconnect\nconst status = mcp.getStatus();   // Get connection status\n```\n\n### Tool Discovery\n```typescript\nconst tools = mcp.getTools();              // Get basic tools with schemas\nconst detailedTools = mcp.getToolsWithDetails();  // Get enhanced tool info for LLMs\nconst tool = mcp.getTool('Topic');         // Get specific tool schema\nawait mcp.refreshTools();                  // Refresh tool list (if MCP updates)\n```\n\n### Tool Execution\n```typescript\n// Single tool call\nconst result = await mcp.callTool('Topic', { topic: 'bitcoin' });\n\n// Execute LLM function call\nconst result = await mcp.executeFunction(name, args);\n\n// Batch multiple tool calls\nconst results = await mcp.callTools([\n  { name: 'Topic', args: { topic: 'bitcoin' } },\n  { name: 'Cryptocurrencies', args: { sort: 'galaxy_score', limit: 10 } }\n]);\n```\n\n## 🛠 Available Tools\n\nThe SDK dynamically discovers all available tools from the LunarCrush MCP server. Common tools include:\n\n- **Topic** - Get detailed crypto/stock data and social metrics\n- **Cryptocurrencies** - List and sort cryptocurrencies by various metrics\n- **Topic_Time_Series** - Historical data and trends\n- **Topic_Posts** - Recent social posts and engagement\n- **Search** - Search across all topics and social data\n- **Creator** - Social media creator analysis\n- **And more...** (auto-discovered)\n\n## 📝 Enhanced Tool Information\n\nThe `getToolsWithDetails()` method provides LLM-friendly tool information:\n\n```typescript\nconst toolsData = mcp.getToolsWithDetails();\nconsole.log(toolsData[0]);\n/*\n{\n  name: \"Topic_Time_Series\",\n  description: \"Get historical time series metrics...\",\n  schema: {\n    type: \"object\",\n    properties: { ... },\n    required: [\"topic\"]\n  },\n  parameterInfo: {\n    required: [\"topic\"],\n    optional: [\"metrics\", \"interval\"],\n    types: {\n      topic: \"string\",\n      metrics: \"array\",\n      interval: \"enum\"\n    },\n    enums: {\n      interval: [\"1d\", \"1w\", \"1m\", \"3m\", \"6m\", \"1y\", \"all\"]\n    }\n  }\n}\n*/\n```\n\nThis enhanced information helps LLMs understand:\n- Which parameters are required vs optional\n- Exact parameter types (string, array, enum, etc.)\n- Valid enum values for better accuracy\n\n## 🔒 Error Handling\n\nThe SDK passes through all MCP server errors with detailed validation messages:\n\n```typescript\ntry {\n  const result = await mcp.callTool('Topic_Time_Series', {\n    topic: 'bitcoin',\n    metrics: 'price,volume',  // ❌ Should be array: ['price', 'volume']\n    interval: 'day'           // ❌ Should be '1d', not 'day'\n  });\n} catch (error) {\n  console.error('MCP validation error:', error.message);\n  // Error shows exactly what's wrong with parameters\n}\n```\n\n## 📝 TypeScript Support\n\nFull TypeScript support with proper types:\n\n```typescript\nimport LunarCrushMCP, { MCPTool, MCPToolResult } from '@jamaalbuilds/lunarcrush-mcp';\n\nconst mcp: LunarCrushMCP = new LunarCrushMCP(apiKey);\nconst tools: MCPTool[] = mcp.getTools();\nconst result: MCPToolResult = await mcp.callTool('Topic', { topic: 'bitcoin' });\n```\n\n## 🎯 Design Philosophy\n\nThis SDK is intentionally minimal and LLM-agnostic:\n\n- **No LLM-specific formatting** - You control how to format schemas for your LLM\n- **No maintenance burden** - SDK just passes through what MCP provides\n- **Future-proof** - Works with any current or future LLM provider\n- **Zero assumptions** - Doesn't assume we know how LLMs will evolve\n\n## 🚀 Get Started\n\n1. **Get LunarCrush API Key**: [lunarcrush.com/developers/api](https://lunarcrush.com/developers/api)\n2. **Install the SDK**: `npm install @jamaalbuilds/lunarcrush-mcp`\n3. **Format tools for your LLM**: Use examples above for your LLM provider\n4. **Start analyzing**: Your LLM now has access to real-time crypto social data!\n\n## 📖 Documentation\n\n- [LunarCrush API Docs](https://lunarcrush.com/developers/api)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n\n## 💬 Support\n\n- [GitHub Issues](https://github.com/danilobatson/lunarcrush-mcp-sdk/issues)\n- [Portfolio](https://danilobatson.github.io/)\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Built by [Danilo Jamaal](https://danilobatson.github.io/) for the LunarCrush community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilobatson%2Flunarcrush-mcp-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanilobatson%2Flunarcrush-mcp-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilobatson%2Flunarcrush-mcp-sdk/lists"}