{
  "markdown": "# Hebline MCP Server\n\n**Your agents overpay for every API call. We fix that.**\n\nHebline routes every API call — including LLM calls — to the best service at the right price. Free when it's enough. Paid when it matters. It knows the difference.\n\nEvery other router earns a margin on your paid calls. Routing you to free alternatives kills their revenue. **No margin on your API calls. Ever.**\n\n## Why Hebline?\n\nYour agents are bleeding money. One task triggers 5–10 paid API calls across different providers. No transparency, no cost control. Hebline fixes that:\n\n- **Route free first** — Most calls don't need the best model. Hebline learns precisely when it matters — and keeps learning as the market changes.\n- **No margin. Honest routing.** — We don't earn when you pay more. So we're the only router built to actually save you money.\n- **Provider Abstraction** — Your agent says *what* it needs (\"geocode this address\"), not *which service* to use. Swap providers without changing agent code.\n- **Cost Transparency** — Every call is logged with service used, latency, and cost. Know exactly what your agents spend.\n- **Learns from usage** — Hebbian learning strengthens what works, weakens what doesn't. Your broker gets smarter every day.\n- **BYOK (Bring Your Own Key)** — Paid services use your API keys via environment variables. No key? The service is automatically excluded from routing.\n- **GDPR compliant** — Only anonymized metadata logged. No API call content stored. Self-hosted option for zero data leaving your network.\n- **Open Source** — Core MCP server is MIT licensed. Community-driven adapter system.\n\n## How It Works\n\n```\nYour AI Agent ←→ Hebline MCP Server ←→ Best API (Nominatim, DeepL, Google Maps, ...)\n                        │\n                   Smart Routing\n                   Cost Logging\n                   Provider Scoring\n```\n\nYour agent connects to Hebline as an MCP server. Instead of calling APIs directly, it uses Hebline's tools — `execute`, `compare`, or `categories`. Hebline scores all available services, picks the best one, makes the call, and returns the result with full metadata.\n\n## Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `execute` | Route to the best service and make the API call. Returns result + metadata (service, cost, latency). |\n| `compare` | Show all available services for a capability with scores. See what's available before committing. |\n| `categories` | List all supported capabilities and their services. |\n\n## Quick Start\n\n### Add to Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hebline\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@hebline.ai/mcp-server\", \"hebline-mcp\"]\n    }\n  }\n}\n```\n\n### Add to Claude Code\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hebline\": {\n      \"command\": \"hebline-mcp\"\n    }\n  }\n}\n```\n\n### Add to Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hebline\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@hebline.ai/mcp-server\", \"hebline-mcp\"]\n    }\n  }\n}\n```\n\n### Add to Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hebline\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@hebline.ai/mcp-server\", \"hebline-mcp\"]\n    }\n  }\n}\n```\n\n### Add to VS Code (Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"hebline\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@hebline.ai/mcp-server\", \"hebline-mcp\"]\n    }\n  }\n}\n```\n\n### Install globally\n\n```bash\nnpm install -g @hebline.ai/mcp-server\n```\n\n### With paid services (optional)\n\nSet environment variables for any paid providers you want to use:\n\n```env\nGOOGLE_MAPS_API_KEY=your-key-here\nDEEPL_API_KEY=your-key-here\nLIBRETRANSLATE_API_KEY=your-key-here\n```\n\nNo keys? No problem — Hebline routes to free alternatives automatically.\n\n## Supported Services\n\n| Category | Free | Paid (BYOK) |\n|----------|------|-------------|\n| **LLMs** | Groq (Llama 3.3 70B), Google Gemini Flash | OpenAI GPT-4o-mini (`OPENAI_API_KEY`) |\n| Geocoding | Nominatim (OpenStreetMap) | Google Maps (`GOOGLE_MAPS_API_KEY`) |\n| Translation | MyMemory | DeepL (`DEEPL_API_KEY`), LibreTranslate (`LIBRETRANSLATE_API_KEY`) |\n| Web Scraping | Fetch Scraper | Firecrawl (`FIRECRAWL_API_KEY`) |\n| Currency | ExchangeRate-API | Fixer.io (`FIXER_API_KEY`) |\n| OCR | OCR.space | Google Vision (`GOOGLE_VISION_API_KEY`) |\n| Weather | Open-Meteo | OpenWeatherMap (`OPENWEATHERMAP_API_KEY`) |\n| Web Search | DuckDuckGo | Brave Search (`BRAVE_API_KEY`) |\n| News | HackerNews | NewsAPI.org (`NEWSAPI_KEY`) |\n\n**9 categories, 20 services.** Free services work instantly — no API key needed. LLMs route through the Hebline proxy when no local key is set (50 free calls/day).\n\n## Example\n\nAn agent asks: *\"Geocode the Brandenburg Gate in Berlin\"*\n\nHebline receives:\n```json\n{\n  \"capability\": \"geocoding\",\n  \"input\": { \"query\": \"Brandenburger Tor, Berlin\" },\n  \"constraint\": \"free\"\n}\n```\n\nHebline responds:\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"lat\": 52.5163,\n    \"lon\": 13.3777,\n    \"displayName\": \"Brandenburger Tor, Pariser Platz, Berlin, 10117, Deutschland\"\n  },\n  \"meta\": {\n    \"service\": \"Nominatim (OpenStreetMap)\",\n    \"costUsd\": 0,\n    \"latencyMs\": 258,\n    \"score\": 0.702,\n    \"free\": true\n  }\n}\n```\n\nThe agent got coordinates, knows it was free, and Hebline logged the call for future analysis.\n\n## Architecture\n\n```\nmcp-server/\n├── src/\n│   ├── index.ts              # MCP server entry point (stdio transport)\n│   ├── types.ts              # Shared TypeScript types\n│   ├── registry.ts           # Service definitions (capabilities, costs, scores)\n│   ├── router.ts             # Weighted scoring engine (Hopfield-ready)\n│   ├── logger.ts             # Append-only JSONL call log (~/.hebline/calls.jsonl)\n│   ├── adapters/             # One adapter per service\n│   │   ├── nominatim.ts      # Free geocoding\n│   │   ├── google-maps.ts    # Paid geocoding (BYOK)\n│   │   ├── mymemory.ts       # Free translation\n│   │   ├── libretranslate.ts # Paid translation (BYOK)\n│   │   └── deepl.ts          # Paid translation (BYOK)\n│   └── tools/                # MCP tool definitions\n│       ├── execute.ts        # Route + call best service\n│       ├── compare.ts        # Score all services\n│       └── categories.ts     # List capabilities\n```\n\n## Call Logging\n\nEvery API call is logged to `~/.hebline/calls.jsonl`:\n\n```json\n{\"timestamp\":\"2026-03-29T09:36:37Z\",\"capability\":\"geocoding\",\"serviceId\":\"nominatim\",\"latencyMs\":212,\"success\":true,\"costUsd\":0}\n```\n\nNo content is logged — only metadata. This data will power Hebbian Learning in future versions.\n\n## Roadmap\n\n- [x] Core MCP server with stdio transport\n- [x] Weighted scoring router\n- [x] Geocoding adapters (Nominatim, Google Maps)\n- [x] Translation adapters (MyMemory, LibreTranslate, DeepL)\n- [x] BYOK key management\n- [x] Append-only call logging\n- [x] CI/CD with GitHub Actions\n- [ ] Hebbian Learning — router learns from call history\n- [ ] Hopfield network scoring (replaces weighted scoring)\n- [ ] More categories (web scraping, currency, OCR, email)\n- [ ] Community adapter system\n- [ ] SSE transport for remote deployments\n- [ ] Web dashboard for cost analytics\n- [ ] Budget alerts and spending limits\n- [ ] Multi-agent cost attribution\n\n## Contributing\n\nContributions are welcome! Adding a new adapter is straightforward — implement the `ServiceAdapter` interface and register it.\n\n```bash\ngit clone https://github.com/hebline/mcp-server.git\ncd mcp-server\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\n[MIT](LICENSE)\n\n---\n\nBuilt by [Hebline](https://hebline.ai) — Route free first. Only pay when necessary.\n",
  "bytes": 7709,
  "sha": "004c497804138db5362542f52d069521c7f0cc4bf48c13869a787344d7ad1b28",
  "repo_slug": "hebline/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hebline_mcp_server_7d263228/readme"
}