@anotarakape/mcp-server 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# ☕ TaraKape 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.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows developers and AI assistants (Claude Desktop, Cursor, Copilot, etc.) to securely query and discover coffee shops from the **TaraKape** database across Metro Manila and the Philippines.
+
+---
+
+## 🏛️ Architecture
+
+```
+Developers / AI Assistants (Cursor, Claude Desktop)
+                         │ (MCP Protocol - stdio)
+                         ▼
+             [ @tarakape/mcp-server ]
+                         │ (HTTPS with API Key)
+                         ▼
+            [ AWS API Gateway (REST) ]
+               ├── API Key Validation & Usage Plans (Quotas/Throttling)
+               └── CloudWatch Monitoring
+                         │
+                         ▼
+             [ AWS Lambda Data Gateway ]
+               └── Fast In-Memory Geo & Tag Queries
+                         │
+                         ▼
+              [ TaraKape Cafe Database ]
+```
+
+---
+
+## 🛠️ Tools Provided to AI Agents
+
+| Tool | Description | Key Inputs |
+| :--- | :--- | :--- |
+| `search_cafes` | Search cafes by keywords, address, or amenities | `query`, `hasWifi`, `hasOutlets`, `isPetFriendly`, `vibe`, `limit` |
+| `find_nearby_cafes` | Find cafes nearest to GPS coordinates | `latitude`, `longitude`, `radiusKm`, `limit` |
+| `get_cafe_details` | Retrieve complete details, hours, photos for a cafe | `idOrSlug` |
+| `list_vibe_tags` | List all valid atmosphere and mood tags | *(none)* |
+
+---
+
+## 🚀 Quick Setup for Developers
+
+### In Claude Desktop (`claude_desktop_config.json`)
+
+Add the following to your configuration file:
+
+- **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_URL": "https://mcp.tarakape.cc",
+        "TARAKAPE_API_KEY": "YOUR_DEVELOPER_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### In Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "tarakape": {
+      "command": "npx",
+      "args": ["-y", "@anotarakape/mcp-server"],
+      "env": {
+        "TARAKAPE_API_URL": "https://mcp.tarakape.cc",
+        "TARAKAPE_API_KEY": "YOUR_DEVELOPER_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## ☁️ Deploying the AWS Gateway
+
+### 1. Deploy the Lambda Gateway
+1. Zip the files inside `lambda/`:
+   ```bash
+   cd lambda
+   zip lambda.zip index.js package.json
+   ```
+2. In **AWS Console** → **Lambda** (e.g. Region `ap-southeast-1` Singapore or `us-east-1`):
+   - Function name: `tarakape-mcp-gateway`
+   - Runtime: **Node.js 20.x**
+   - Upload `lambda.zip` and click **Deploy**.
+
+### 2. Put AWS API Gateway in Front
+1. Go to **AWS API Gateway** → **Create API** → **REST API**.
+2. Create resource `{proxy+}` with method `ANY` (or specific `POST /search`, `POST /nearby`, etc.).
+3. Choose **Lambda Function** integration and select `tarakape-mcp-gateway`.
+4. Enable **API Key Required** on methods.
+5. Create a **Usage Plan**:
+   - Throttle: 10 requests/second, Burst: 20
+   - Quota: 10,000 requests per month
+6. Generate an **API Key** for your external developers and link it to the Usage Plan.
+7. Deploy the API to a stage (e.g. `prod`).
+8. Copy the **Invoke URL** and provide it to developers.

package/dist/index.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Base URL for TaraKape API Gateway (defaults to https://mcp.tarakape.cc)
+const API_URL = process.env.TARAKAPE_API_URL || "https://mcp.tarakape.cc";
+const API_KEY = process.env.TARAKAPE_API_KEY || "";
+const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": "TaraKape-MCP-Server/1.0.0",
+};
+if (API_KEY) {
+    headers["x-api-key"] = API_KEY;
+}
+// Helper to make API requests to AWS API Gateway / TaraKape Backend
+async function callGateway(path, method = "GET", body) {
+    let url = API_URL.replace(/\/+$/, "");
+    if (path && path !== "/") {
+        url += path.startsWith("/") ? path : `/${path}`;
+    }
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Gateway returned HTTP ${response.status}: ${errorText}`);
+    }
+    return response.json();
+}
+// Initialize MCP Server
+const server = new McpServer({
+    name: "tarakape",
+    version: "1.0.0",
+});
+const isActionGateway = !API_URL.endsWith("/cafes") ||
+    API_URL.includes("execute-api") ||
+    API_URL.includes("lambda-url") ||
+    API_URL.includes("mcp.tarakape.cc") ||
+    API_URL.includes("gateway") ||
+    API_URL.includes("localhost");
+// Tool 1: Search Cafes
+server.tool("search_cafes", "Search cafes across Metro Manila and the Philippines with optional filters for Wi-Fi, power outlets, pet friendliness, and aesthetic vibe.", {
+    query: z.string().optional().describe("Search keywords matching cafe name, city, or address"),
+    hasWifi: z.boolean().optional().describe("Filter only cafes with confirmed Wi-Fi"),
+    hasOutlets: z.boolean().optional().describe("Filter only cafes with power outlets for laptops"),
+    isPetFriendly: z.boolean().optional().describe("Filter only pet-friendly cafes"),
+    vibe: z.string().optional().describe("Filter by vibe tag (e.g. 'aesthetic', 'work-friendly', 'cozy', 'minimalist')"),
+    limit: z.number().optional().describe("Maximum number of cafes to return (default: 20)"),
+}, async ({ query, hasWifi, hasOutlets, isPetFriendly, vibe, limit }) => {
+    try {
+        let data;
+        if (isActionGateway) {
+            data = await callGateway("/", "POST", {
+                action: "search",
+                query,
+                hasWifi,
+                hasOutlets,
+                isPetFriendly,
+                vibe,
+                limit: limit || 20,
+            });
+        }
+        else {
+            const allCafes = await callGateway("/cafes", "GET");
+            let filtered = allCafes;
+            if (query) {
+                const q = query.toLowerCase();
+                filtered = filtered.filter((c) => (c.name && c.name.toLowerCase().includes(q)) ||
+                    (c.address && c.address.toLowerCase().includes(q)));
+            }
+            if (hasWifi === true)
+                filtered = filtered.filter((c) => c.wifi);
+            if (hasOutlets === true)
+                filtered = filtered.filter((c) => c.outlets);
+            if (isPetFriendly === true)
+                filtered = filtered.filter((c) => c.pet_friendly);
+            if (vibe) {
+                const v = vibe.toLowerCase();
+                filtered = filtered.filter((c) => Array.isArray(c.vibe_tags) && c.vibe_tags.some((t) => t.toLowerCase().includes(v)));
+            }
+            const maxResults = limit || 20;
+            data = {
+                success: true,
+                count: Math.min(filtered.length, maxResults),
+                totalMatches: filtered.length,
+                cafes: filtered.slice(0, maxResults),
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error searching cafes: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool 2: Find Nearby Cafes
+server.tool("find_nearby_cafes", "Find coffee shops nearest to a specific latitude and longitude coordinate within a given radius in kilometers.", {
+    latitude: z.number().describe("User latitude (e.g. 14.5547)"),
+    longitude: z.number().describe("User longitude (e.g. 121.0244)"),
+    radiusKm: z.number().optional().describe("Search radius in kilometers (default: 5.0)"),
+    limit: z.number().optional().describe("Maximum number of results to return (default: 15)"),
+}, async ({ latitude, longitude, radiusKm = 5.0, limit = 15 }) => {
+    try {
+        let data;
+        if (isActionGateway) {
+            data = await callGateway("/", "POST", {
+                action: "nearby",
+                latitude,
+                longitude,
+                radiusKm,
+                limit,
+            });
+        }
+        else {
+            const allCafes = await callGateway("/cafes", "GET");
+            // Haversine formula
+            const calculateDist = (lat1, lon1, lat2, lon2) => {
+                const R = 6371;
+                const dLat = ((lat2 - lat1) * Math.PI) / 180;
+                const dLon = ((lon2 - lon1) * Math.PI) / 180;
+                const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+                    Math.cos((lat1 * Math.PI) / 180) *
+                        Math.cos((lat2 * Math.PI) / 180) *
+                        Math.sin(dLon / 2) *
+                        Math.sin(dLon / 2);
+                const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+                return Math.round(R * c * 100) / 100;
+            };
+            const nearby = allCafes
+                .filter((c) => c.latitude && c.longitude)
+                .map((c) => ({ ...c, distanceKm: calculateDist(latitude, longitude, c.latitude, c.longitude) }))
+                .filter((c) => c.distanceKm <= radiusKm)
+                .sort((a, b) => a.distanceKm - b.distanceKm)
+                .slice(0, limit);
+            data = {
+                success: true,
+                center: { latitude, longitude },
+                radiusKm,
+                count: nearby.length,
+                cafes: nearby,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error finding nearby cafes: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool 3: Get Cafe Details
+server.tool("get_cafe_details", "Retrieve comprehensive details for a single cafe using its unique ID or URL slug.", {
+    idOrSlug: z.string().describe("The unique cafe ID (UUID) or URL slug (e.g. 'percent-arabica-manila-bgc-roastery')"),
+}, async ({ idOrSlug }) => {
+    try {
+        let data;
+        if (isActionGateway) {
+            data = await callGateway("/", "POST", {
+                action: "get_cafe",
+                idOrSlug,
+            });
+        }
+        else {
+            const allCafes = await callGateway("/cafes", "GET");
+            const cafe = allCafes.find((c) => c.id === idOrSlug || (c.slug && c.slug.toLowerCase() === idOrSlug.toLowerCase()));
+            if (!cafe) {
+                throw new Error(`Cafe with ID or slug '${idOrSlug}' was not found.`);
+            }
+            data = { success: true, cafe };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error retrieving cafe: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool 4: List Vibe Tags
+server.tool("list_vibe_tags", "List all available mood, ambiance, and aesthetic tags that can be used to filter cafes.", {}, async () => {
+    try {
+        let data;
+        if (isActionGateway) {
+            data = await callGateway("/", "POST", {
+                action: "vibes",
+            });
+        }
+        else {
+            const allCafes = await callGateway("/cafes", "GET");
+            const set = new Set();
+            allCafes.forEach((c) => {
+                if (Array.isArray(c.vibe_tags)) {
+                    c.vibe_tags.forEach((v) => set.add(v));
+                }
+            });
+            data = { success: true, vibes: Array.from(set).sort() };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching vibe tags: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server using stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("☕ TaraKape MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error starting TaraKape MCP server:", error);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@anotarakape/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) Server for TaraKape Coffee Shops Directory",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-server": "./dist/index.js",
+    "tarakape-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.5.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "keywords": ["mcp", "model-context-protocol", "tarakape", "coffee", "manila", "cafes"],
+  "author": "TaraKape",
+  "license": "MIT"
+}