@anotarakape/mcp-server 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# ☕ TaraKape MCP Server (`@anotarakape/mcp-server`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **[TaraKape](https://tarakape.cc)** — the definitive coffee shop discovery directory in the Philippines.
+
+Connect AI assistants (Claude Desktop, Cursor, Kiro, Windsurf) directly to live data for **5,200+ curated cafes** across Metro Manila and the Philippines with real-time amenity filters (Wi-Fi, power outlets, pet-friendliness), ambiance tags, operating hours, coordinates, and high-res photos.
+
+[![npm version](https://img.shields.io/npm/v/@anotarakape/mcp-server.svg)](https://www.npmjs.com/package/@anotarakape/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🔑 Getting an API Key
+
+To query live cafe data, you will need a free TaraKape Developer API Key:
+
+1. Visit the [TaraKape Developer Portal](https://tarakape.cc/developer).
+2. Sign up or log in and navigate to the **API Keys** tab.
+3. Generate your developer key (starts with `tk_live_`).
+
+---
+
+## 🚀 Quickstart
+
+Run via `npx` with zero installation required on any operating system:
+
+### 1. Kiro IDE
+Add to your project's `.kiro/settings/mcp.json` or globally in `~/.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tarakape": {
+      "command": "npx",
+      "args": ["-y", "@anotarakape/mcp-server"],
+      "env": {
+        "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### 2. Cursor
+Add to your project's `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tarakape": {
+      "command": "npx",
+      "args": ["-y", "@anotarakape/mcp-server"],
+      "env": {
+        "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### 3. Claude Desktop
+Add to your `claude_desktop_config.json`:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "tarakape": {
+      "command": "npx",
+      "args": ["-y", "@anotarakape/mcp-server"],
+      "env": {
+        "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### 4. Windsurf
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tarakape": {
+      "command": "npx",
+      "args": ["-y", "@anotarakape/mcp-server"],
+      "env": {
+        "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Tools Reference
+
+| Tool | Description | Inputs |
+| :--- | :--- | :--- |
+| `search_cafes` | Search coffee shops by name, address, amenities, and vibe | `query`, `hasWifi`, `hasOutlets`, `isPetFriendly`, `vibe`, `limit` |
+| `find_nearby_cafes` | Locate cafes nearest to GPS coordinates (Haversine distance) | `latitude`, `longitude`, `radiusKm`, `limit` |
+| `get_cafe_details` | Retrieve full profile, verified hours, and photos by UUID or slug | `idOrSlug` |
+| `list_vibe_tags` | List all valid atmosphere and ambiance tags | *(none)* |
+
+### Tool: `search_cafes`
+Find cafes matching specific keywords and requirements.
+```json
+{
+  "query": "BGC",
+  "hasWifi": true,
+  "hasOutlets": true,
+  "vibe": "work",
+  "limit": 10
+}
+```
+
+### Tool: `find_nearby_cafes`
+Search cafes around a specific geographic coordinate.
+```json
+{
+  "latitude": 14.5547,
+  "longitude": 121.0244,
+  "radiusKm": 3.0,
+  "limit": 10
+}
+```
+
+### Tool: `get_cafe_details`
+Retrieve detailed info for a single cafe.
+```json
+{
+  "idOrSlug": "percent-arabica-manila-bgc-roastery"
+}
+```
+
+### Tool: `list_vibe_tags`
+Returns available vibe tags such as `aesthetic`, `work`, `study`, `cozy`, `chill`, `artsy`, `date`, `minimalist`.
+
+---
+
+## 💡 Example Prompts to Ask Your AI
+
+Once connected, you can ask your AI assistant questions in natural language:
+
+- *"Find study-friendly cafes in Quezon City with confirmed Wi-Fi and power outlets for laptops."*
+- *"What are aesthetic, quiet coffee shops near Makati CBD for a business catch-up?"*
+- *"Find pet-friendly cafes within 3 km of 14.5520, 121.0477 with outdoor seating."*
+- *"Get the complete opening hours and photos for % Arabica Manila BGC Roastery."*
+
+---
+
+## ⚙️ Environment Variables
+
+| Variable | Required | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `TARAKAPE_API_KEY` | **Yes** | `""` | Developer API key obtained from [tarakape.cc/developer](https://tarakape.cc/developer). |
+| `TARAKAPE_API_URL` | No | `https://mcp.tarakape.cc` | Custom API gateway endpoint if self-hosting. |
+
+---
+
+## 📄 License
+
+MIT © [TaraKape](https://tarakape.cc)