@anotarakape/mcp-server 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +119 -61
  2. package/dist/index.js +21784 -233
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,49 +1,64 @@
1
- # ☕ TaraKape MCP Server
1
+ # ☕ TaraKape MCP Server (`@anotarakape/mcp-server`)
2
2
 
3
- 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.
3
+ The official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **[TaraKape](https://tarakape.cc)** — the definitive coffee shop discovery directory in the Philippines.
4
+
5
+ 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.
6
+
7
+ [![npm version](https://img.shields.io/npm/v/@anotarakape/mcp-server.svg)](https://www.npmjs.com/package/@anotarakape/mcp-server)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
9
 
5
10
  ---
6
11
 
7
- ## 🏛️ Architecture
12
+ ## 🔑 Getting an API Key
8
13
 
9
- ```
10
- Developers / AI Assistants (Cursor, Claude Desktop)
11
- │ (MCP Protocol - stdio)
12
- ▼
13
- [ @tarakape/mcp-server ]
14
- │ (HTTPS with API Key)
15
- ▼
16
- [ AWS API Gateway (REST) ]
17
- ├── API Key Validation & Usage Plans (Quotas/Throttling)
18
- └── CloudWatch Monitoring
19
- │
20
- ▼
21
- [ AWS Lambda Data Gateway ]
22
- └── Fast In-Memory Geo & Tag Queries
23
- │
24
- ▼
25
- [ TaraKape Cafe Database ]
26
- ```
14
+ To query live cafe data, you will need a free TaraKape Developer API Key:
15
+
16
+ 1. Visit the [TaraKape Developer Portal](https://tarakape.cc/developer).
17
+ 2. Sign up or log in and navigate to the **API Keys** tab.
18
+ 3. Generate your developer key (starts with `tk_live_`).
27
19
 
28
20
  ---
29
21
 
30
- ## 🛠️ Tools Provided to AI Agents
22
+ ## 🚀 Quickstart
31
23
 
32
- | Tool | Description | Key Inputs |
33
- | :--- | :--- | :--- |
34
- | `search_cafes` | Search cafes by keywords, address, or amenities | `query`, `hasWifi`, `hasOutlets`, `isPetFriendly`, `vibe`, `limit` |
35
- | `find_nearby_cafes` | Find cafes nearest to GPS coordinates | `latitude`, `longitude`, `radiusKm`, `limit` |
36
- | `get_cafe_details` | Retrieve complete details, hours, photos for a cafe | `idOrSlug` |
37
- | `list_vibe_tags` | List all valid atmosphere and mood tags | *(none)* |
24
+ Run via `npx` with zero installation required on any operating system:
38
25
 
39
- ---
26
+ ### 1. Kiro IDE
27
+ Add to your project's `.kiro/settings/mcp.json` or globally in `~/.kiro/settings/mcp.json`:
40
28
 
41
- ## 🚀 Quick Setup for Developers
29
+ ```json
30
+ {
31
+ "mcpServers": {
32
+ "tarakape": {
33
+ "command": "npx",
34
+ "args": ["-y", "@anotarakape/mcp-server"],
35
+ "env": {
36
+ "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
37
+ }
38
+ }
39
+ }
40
+ }
41
+ ```
42
42
 
43
- ### In Claude Desktop (`claude_desktop_config.json`)
43
+ ### 2. Cursor
44
+ Add to your project's `.cursor/mcp.json`:
44
45
 
45
- Add the following to your configuration file:
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "tarakape": {
50
+ "command": "npx",
51
+ "args": ["-y", "@anotarakape/mcp-server"],
52
+ "env": {
53
+ "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
54
+ }
55
+ }
56
+ }
57
+ }
58
+ ```
46
59
 
60
+ ### 3. Claude Desktop
61
+ Add to your `claude_desktop_config.json`:
47
62
  - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
48
63
  - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
49
64
 
@@ -54,15 +69,15 @@ Add the following to your configuration file:
54
69
  "command": "npx",
55
70
  "args": ["-y", "@anotarakape/mcp-server"],
56
71
  "env": {
57
- "TARAKAPE_API_URL": "https://mcp.tarakape.cc",
58
- "TARAKAPE_API_KEY": "YOUR_DEVELOPER_API_KEY"
72
+ "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
59
73
  }
60
74
  }
61
75
  }
62
76
  }
63
77
  ```
64
78
 
65
- ### In Cursor (`.cursor/mcp.json`)
79
+ ### 4. Windsurf
80
+ Add to `~/.codeium/windsurf/mcp_config.json`:
66
81
 
67
82
  ```json
68
83
  {
@@ -71,8 +86,7 @@ Add the following to your configuration file:
71
86
  "command": "npx",
72
87
  "args": ["-y", "@anotarakape/mcp-server"],
73
88
  "env": {
74
- "TARAKAPE_API_URL": "https://mcp.tarakape.cc",
75
- "TARAKAPE_API_KEY": "YOUR_DEVELOPER_API_KEY"
89
+ "TARAKAPE_API_KEY": "YOUR_API_KEY_HERE"
76
90
  }
77
91
  }
78
92
  }
@@ -81,27 +95,71 @@ Add the following to your configuration file:
81
95
 
82
96
  ---
83
97
 
84
- ## ☁️ Deploying the AWS Gateway
85
-
86
- ### 1. Deploy the Lambda Gateway
87
- 1. Zip the files inside `lambda/`:
88
- ```bash
89
- cd lambda
90
- zip lambda.zip index.js package.json
91
- ```
92
- 2. In **AWS Console** → **Lambda** (e.g. Region `ap-southeast-1` Singapore or `us-east-1`):
93
- - Function name: `tarakape-mcp-gateway`
94
- - Runtime: **Node.js 20.x**
95
- - Upload `lambda.zip` and click **Deploy**.
96
-
97
- ### 2. Put AWS API Gateway in Front
98
- 1. Go to **AWS API Gateway** → **Create API** → **REST API**.
99
- 2. Create resource `{proxy+}` with method `ANY` (or specific `POST /search`, `POST /nearby`, etc.).
100
- 3. Choose **Lambda Function** integration and select `tarakape-mcp-gateway`.
101
- 4. Enable **API Key Required** on methods.
102
- 5. Create a **Usage Plan**:
103
- - Throttle: 10 requests/second, Burst: 20
104
- - Quota: 10,000 requests per month
105
- 6. Generate an **API Key** for your external developers and link it to the Usage Plan.
106
- 7. Deploy the API to a stage (e.g. `prod`).
107
- 8. Copy the **Invoke URL** and provide it to developers.
98
+ ## 🛠️ Tools Reference
99
+
100
+ | Tool | Description | Inputs |
101
+ | :--- | :--- | :--- |
102
+ | `search_cafes` | Search coffee shops by name, address, amenities, and vibe | `query`, `hasWifi`, `hasOutlets`, `isPetFriendly`, `vibe`, `limit` |
103
+ | `find_nearby_cafes` | Locate cafes nearest to GPS coordinates (Haversine distance) | `latitude`, `longitude`, `radiusKm`, `limit` |
104
+ | `get_cafe_details` | Retrieve full profile, verified hours, and photos by UUID or slug | `idOrSlug` |
105
+ | `list_vibe_tags` | List all valid atmosphere and ambiance tags | *(none)* |
106
+
107
+ ### Tool: `search_cafes`
108
+ Find cafes matching specific keywords and requirements.
109
+ ```json
110
+ {
111
+ "query": "BGC",
112
+ "hasWifi": true,
113
+ "hasOutlets": true,
114
+ "vibe": "work",
115
+ "limit": 10
116
+ }
117
+ ```
118
+
119
+ ### Tool: `find_nearby_cafes`
120
+ Search cafes around a specific geographic coordinate.
121
+ ```json
122
+ {
123
+ "latitude": 14.5547,
124
+ "longitude": 121.0244,
125
+ "radiusKm": 3.0,
126
+ "limit": 10
127
+ }
128
+ ```
129
+
130
+ ### Tool: `get_cafe_details`
131
+ Retrieve detailed info for a single cafe.
132
+ ```json
133
+ {
134
+ "idOrSlug": "percent-arabica-manila-bgc-roastery"
135
+ }
136
+ ```
137
+
138
+ ### Tool: `list_vibe_tags`
139
+ Returns available vibe tags such as `aesthetic`, `work`, `study`, `cozy`, `chill`, `artsy`, `date`, `minimalist`.
140
+
141
+ ---
142
+
143
+ ## 💡 Example Prompts to Ask Your AI
144
+
145
+ Once connected, you can ask your AI assistant questions in natural language:
146
+
147
+ - *"Find study-friendly cafes in Quezon City with confirmed Wi-Fi and power outlets for laptops."*
148
+ - *"What are aesthetic, quiet coffee shops near Makati CBD for a business catch-up?"*
149
+ - *"Find pet-friendly cafes within 3 km of 14.5520, 121.0477 with outdoor seating."*
150
+ - *"Get the complete opening hours and photos for % Arabica Manila BGC Roastery."*
151
+
152
+ ---
153
+
154
+ ## ⚙️ Environment Variables
155
+
156
+ | Variable | Required | Default | Description |
157
+ | :--- | :--- | :--- | :--- |
158
+ | `TARAKAPE_API_KEY` | **Yes** | `""` | Developer API key obtained from [tarakape.cc/developer](https://tarakape.cc/developer). |
159
+ | `TARAKAPE_API_URL` | No | `https://mcp.tarakape.cc` | Custom API gateway endpoint if self-hosting. |
160
+
161
+ ---
162
+
163
+ ## 📄 License
164
+
165
+ MIT © [TaraKape](https://tarakape.cc)