@apogeoapi/mcp 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 +112 -106
  2. package/package.json +3 -4
  3. package/smithery.yaml +21 -0
package/README.md CHANGED
@@ -1,106 +1,112 @@
1
- # @apogeoapi/mcp
2
-
3
- MCP (Model Context Protocol) server for [ApogeoAPI](https://app.apogeoapi.com) — geographic data, live exchange rates, and IP geolocation for Claude Desktop, Cursor, and any MCP-compatible AI assistant.
4
-
5
- ## What it does
6
-
7
- This server exposes ApogeoAPI's REST endpoints as tools that AI assistants can call directly. Ask Claude "What is the current USD rate for Argentina?" or "Geolocate IP 8.8.8.8" and it will call the right tool automatically.
8
-
9
- ## Available tools
10
-
11
- | Tool | Description | Plan required |
12
- |------|-------------|---------------|
13
- | `get_country` | Full country data by ISO2/ISO3 code — name, capital, region, population, currency, live USD rate, timezones, phone code | Free |
14
- | `list_countries` | Paginated list of all 250+ countries | Free |
15
- | `search_countries` | Search countries by partial name | Free |
16
- | `get_states` | All states/provinces for a country | Basic+ |
17
- | `get_cities` | All cities for a state by numeric state ID | Basic+ |
18
- | `get_currency_rate` | Live USD exchange rate for a country's currency (updated every 4 hours) | Basic+ |
19
- | `geolocate_ip` | Country, region, city, coordinates, timezone, and EU membership for any IPv4/IPv6 | Basic+ |
20
- | `global_search` | Search across countries, states, and cities in one query | Free |
21
-
22
- ## Installation
23
-
24
- ### Claude Desktop
25
-
26
- Add the following to your `claude_desktop_config.json`:
27
-
28
- - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
29
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
30
-
31
- ```json
32
- {
33
- "mcpServers": {
34
- "apogeoapi": {
35
- "command": "npx",
36
- "args": ["-y", "@apogeoapi/mcp"],
37
- "env": {
38
- "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
39
- }
40
- }
41
- }
42
- }
43
- ```
44
-
45
- Restart Claude Desktop after saving the file. The ApogeoAPI tools will appear in Claude's tool list.
46
-
47
- ### Cursor
48
-
49
- Add the same block under `mcpServers` in Cursor's MCP configuration file (`~/.cursor/mcp.json`).
50
-
51
- ### Manual build
52
-
53
- ```bash
54
- git clone https://github.com/your-org/apogeoapi-mcp
55
- cd apogeoapi-mcp
56
- npm install
57
- npm run build
58
- ```
59
-
60
- Then reference the built file directly:
61
-
62
- ```json
63
- {
64
- "mcpServers": {
65
- "apogeoapi": {
66
- "command": "node",
67
- "args": ["/absolute/path/to/mcp-server/dist/index.js"],
68
- "env": {
69
- "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
70
- }
71
- }
72
- }
73
- }
74
- ```
75
-
76
- ## Getting an API key
77
-
78
- 1. Create a free account at [app.apogeoapi.com](https://app.apogeoapi.com)
79
- 2. Go to **API Keys** and generate a new key
80
- 3. Paste the key into the `APOGEOAPI_KEY` environment variable above
81
-
82
- No credit card required for the Free plan (1,000 req/month).
83
-
84
- ## Plan requirements
85
-
86
- | Feature | Free | Basic ($19/mo) | Starter ($29/mo) | Professional ($79/mo) |
87
- |---------|------|----------------|-------------------|-----------------------|
88
- | Countries (list, search, get) | Yes | Yes | Yes | Yes |
89
- | Global search | Yes | Yes | Yes | Yes |
90
- | States & cities | No | Yes | Yes | Yes |
91
- | Live currency rates | No | Yes | Yes | Yes |
92
- | IP geolocation | No | Yes | Yes | Yes |
93
- | Monthly requests | 1,000 | 15,000 | 100,000 | 500,000 |
94
-
95
- Upgrade at [app.apogeoapi.com/dashboard/billing](https://app.apogeoapi.com/dashboard/billing).
96
-
97
- ## Environment variables
98
-
99
- | Variable | Required | Description |
100
- |----------|----------|-------------|
101
- | `APOGEOAPI_KEY` | Yes | Your API key from the dashboard |
102
- | `APOGEOAPI_BASE_URL` | No | Override the API base URL (default: `https://api.apogeoapi.com`) |
103
-
104
- ## License
105
-
106
- MIT
1
+ # @apogeoapi/mcp
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@apogeoapi/mcp)](https://www.npmjs.com/package/@apogeoapi/mcp)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
6
+
7
+ Geographic data MCP server for [ApogeoAPI](https://apogeoapi.com) — 250 countries, states, cities, live currency rates, and IP geolocation. Works with Claude Desktop, Cursor, and any MCP-compatible client.
8
+
9
+ No SDK required. Install with `npx`, configure once, done.
10
+
11
+ ---
12
+
13
+ ## What your agent can do
14
+
15
+ - **Country profiles** — ISO codes, capital, currency, timezones, population, GDP, flag, translations in 18 languages, postal code regex
16
+ - **States & provinces** — ISO 3166-2 codes, coordinates, timezone per state
17
+ - **Cities** — 150,000+ cities with coordinates
18
+ - **IP geolocation** — IPv4/IPv6 → country, region, city, coordinates, timezone, EU membership
19
+ - **Live currency rates** — USD exchange rates for 161 currencies, refreshed every 4 hours
20
+ - **Global search** — search across countries, states, and cities in one call
21
+
22
+ ---
23
+
24
+ ## Quickstart
25
+
26
+ ### Claude Desktop
27
+
28
+ Add to `claude_desktop_config.json`:
29
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
30
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
31
+
32
+ ```json
33
+ {
34
+ "mcpServers": {
35
+ "apogeoapi": {
36
+ "command": "npx",
37
+ "args": ["-y", "@apogeoapi/mcp"],
38
+ "env": {
39
+ "APOGEOAPI_KEY": "your-api-key"
40
+ }
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ Restart Claude Desktop. The ApogeoAPI tools will appear automatically.
47
+
48
+ ### Cursor
49
+
50
+ Add the same block to `~/.cursor/mcp.json` under `mcpServers`.
51
+
52
+ ### Get an API key
53
+
54
+ 1. Create a free account at [apogeoapi.com](https://apogeoapi.com) — no credit card required
55
+ 2. Go to **API Keys** and generate a key
56
+ 3. Paste it as `APOGEOAPI_KEY`
57
+
58
+ ---
59
+
60
+ ## Example
61
+
62
+ **You ask Claude:**
63
+ > What timezone does Japan use and what does a Japanese postal code look like?
64
+
65
+ **Claude calls** `get_country({ code: "JP" })` and responds:
66
+
67
+ > Japan uses a single timezone: **JST (Japan Standard Time), UTC+09:00**. Japanese postal codes follow the format `NNN-NNNN` — three digits, a hyphen, then four digits. Example: `100-0001`.
68
+
69
+ The full response includes: capital, currency (JPY / ¥), GDP, population, flag URL, 47 states, translations in 18 languages (ja, zh-CN, ar, de, es, fr, ru...), and more.
70
+
71
+ ---
72
+
73
+ ## Available tools
74
+
75
+ | Tool | Description | Plan |
76
+ |------|-------------|------|
77
+ | `get_country` | Full country profile: currency, timezones, translations (18 languages), GDP, population, postal regex, flag | Free |
78
+ | `list_countries` | All 250 countries, paginated — basic / standard / full detail | Free |
79
+ | `search_countries` | Search by partial name, paginated | Free |
80
+ | `get_states` | States/provinces with ISO 3166-2 codes, timezone, coordinates | Free |
81
+ | `get_cities` | Cities within a state (150,000+ total) | Basic |
82
+ | `geolocate_ip` | IPv4/IPv6 → country, region, city, coords, timezone, EU membership | Basic |
83
+ | `get_currency_rate` | Live exchange rate vs USD, refreshed every 4 hours | Basic |
84
+ | `global_search` | Unified search across countries, states, and cities | Basic |
85
+
86
+ ---
87
+
88
+ ## Plans
89
+
90
+ | Plan | Price | Requests/month | Unlocks |
91
+ |------|-------|---------------|---------|
92
+ | Free | $0 | 1,000 | get_country, list_countries, search_countries, get_states |
93
+ | Basic | $19/mo | 15,000 | + cities, IP geo, currency rates, global search |
94
+ | Starter | $29/mo | 100,000 | + webhooks |
95
+ | Professional | $79/mo | 500,000 | + priority support, 5 team members, 99.5% SLA |
96
+
97
+ Manage plans at [app.apogeoapi.com/dashboard/billing](https://app.apogeoapi.com/dashboard/billing).
98
+
99
+ ---
100
+
101
+ ## Environment variables
102
+
103
+ | Variable | Required | Description |
104
+ |----------|----------|-------------|
105
+ | `APOGEOAPI_KEY` | Yes | API key from the dashboard |
106
+ | `APOGEOAPI_BASE_URL` | No | Override base URL (default: `https://api.apogeoapi.com`) |
107
+
108
+ ---
109
+
110
+ ## License
111
+
112
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@apogeoapi/mcp",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "MCP server for ApogeoAPI — geographic data, live exchange rates & IP geolocation",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -28,13 +28,12 @@
28
28
  "@types/node": "^20.0.0",
29
29
  "tsx": "^4.0.0"
30
30
  },
31
- "files": ["dist"],
31
+ "files": ["dist", "smithery.yaml"],
32
32
  "keywords": ["mcp", "geolocation", "geography", "currency", "ip-geo", "apogeoapi"],
33
33
  "license": "MIT",
34
34
  "repository": {
35
35
  "type": "git",
36
- "url": "https://github.com/Ezleal/apo-geo-api.git",
37
- "directory": "mcp-server"
36
+ "url": "https://github.com/APOGEOAPI/apogeoapi-mcp.git"
38
37
  },
39
38
  "homepage": "https://apogeoapi.com"
40
39
  }
package/smithery.yaml ADDED
@@ -0,0 +1,21 @@
1
+ # Smithery configuration for ApogeoAPI MCP Server
2
+ # https://smithery.ai/docs/build/publish
3
+
4
+ startCommand:
5
+ type: stdio
6
+ configSchema:
7
+ type: object
8
+ required:
9
+ - apiKey
10
+ properties:
11
+ apiKey:
12
+ type: string
13
+ description: "Your ApogeoAPI key. Get one free at apogeoapi.com"
14
+ commandFunction: |-
15
+ (config) => ({
16
+ command: "npx",
17
+ args: ["-y", "@apogeoapi/mcp"],
18
+ env: {
19
+ APOGEOAPI_KEY: config.apiKey
20
+ }
21
+ })