mcp-shipxy-api 0.1.0__tar.gz

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 (14) hide show
  1. mcp_shipxy_api-0.1.0/PKG-INFO +217 -0
  2. mcp_shipxy_api-0.1.0/README.md +193 -0
  3. mcp_shipxy_api-0.1.0/cli.py +305 -0
  4. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/PKG-INFO +217 -0
  5. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/SOURCES.txt +12 -0
  6. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/dependency_links.txt +1 -0
  7. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/entry_points.txt +3 -0
  8. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/requires.txt +4 -0
  9. mcp_shipxy_api-0.1.0/mcp_shipxy_api.egg-info/top_level.txt +4 -0
  10. mcp_shipxy_api-0.1.0/pyproject.toml +42 -0
  11. mcp_shipxy_api-0.1.0/server.py +439 -0
  12. mcp_shipxy_api-0.1.0/setup.cfg +4 -0
  13. mcp_shipxy_api-0.1.0/ship_service.py +1429 -0
  14. mcp_shipxy_api-0.1.0/tool_registry.py +334 -0
mcp_shipxy_api-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,217 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-shipxy-api
3
+ Version: 0.1.0
4
+ Summary: Shipxy MCP server and CLI for maritime vessel, port, route, weather, and tide APIs.
5
+ Author: garrettXu
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/garrettXu/mcp-shipxy-api
8
+ Project-URL: Repository, https://github.com/garrettXu/mcp-shipxy-api
9
+ Project-URL: Issues, https://github.com/garrettXu/mcp-shipxy-api/issues
10
+ Keywords: shipxy,mcp,maritime,vessel,shipping,cli
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Internet
17
+ Classifier: Topic :: Scientific/Engineering :: GIS
18
+ Requires-Python: >=3.12
19
+ Description-Content-Type: text/markdown
20
+ Requires-Dist: httpx>=0.28.1
21
+ Requires-Dist: mcp[cli]>=1.11.0
22
+ Requires-Dist: python-dotenv>=1.0.0
23
+ Requires-Dist: requests>=2.31.0
24
+
25
+ # shipxy-api-mcp
26
+
27
+ <!-- mcp-name: io.github.garrettxu/mcp-shipxy-api -->
28
+
29
+ **Shipxy MCP Server** is a fully MCP-compliant, open-source Location-Based Service (LBS) solution for maritime scenarios, providing a comprehensive suite of ship and port APIs and tools for developers and AI agents. It enables seamless integration of real-time vessel data, route planning, weather, tides, and more into your applications.
30
+
31
+ ## 🚀 Introduction
32
+
33
+ **Shipxy MCP Server** empowers your applications, LLMs, and agents with advanced maritime data and geospatial intelligence, including:
34
+
35
+ - **Ship Information & Tracking:** Real-time vessel position, static info, fleet, and area queries.
36
+ - **Port & Berth Data:** Global port search, berth/anchor/ETA queries, port call records.
37
+ - **Route Planning:** Point-to-point and port-to-port route planning.
38
+ - **Weather & Tides:** Marine weather, typhoon, and tide station data.
39
+ - **Rich Maritime APIs:** Ship registry, particulars, approach events, and more.
40
+
41
+ All APIs follow the MCP protocol and can be called from any MCP-compliant client, LLM, or agent platform.
42
+
43
+ ## 🛠️ Key Features
44
+
45
+ - **Full MCP Protocol Support:** Seamless integration with any MCP-compliant agent, LLM, or platform.
46
+ - **Comprehensive Maritime Data:** Ships, ports, routes, weather, tides, and more.
47
+ - **Real-Time & Historical Data:** Live vessel tracking, voyage history, and event records.
48
+ - **Open Source & Extensible:** MIT licensed, easy to customize and extend.
49
+
50
+ ## ⚡ Quick Start
51
+
52
+ ### 1. Get Your API Key
53
+
54
+ Register and create a server-side API Key at [Shipxy Open Platform](https://api.shipxy.com/v3/console/overview).
55
+ **Note:** The API key is required for all requests.
56
+
57
+ ### 2. Installation
58
+
59
+ Install from PyPI after release:
60
+
61
+ ```bash
62
+ pipx install mcp-shipxy-api
63
+ ```
64
+
65
+ Or install into an existing virtual environment:
66
+
67
+ ```bash
68
+ pip install mcp-shipxy-api
69
+ ```
70
+
71
+ For local source development:
72
+
73
+ ```bash
74
+ pip install -r requirements.txt
75
+ ```
76
+
77
+
78
+ ### 3. Configuration
79
+
80
+ Create a `.env` file in your project root:
81
+
82
+ ```
83
+ SHIPXY_API_KEY=your_api_key_here
84
+ ```
85
+
86
+ ### 4. Start the Server
87
+
88
+ Recommended: Use an `mcp.json` configuration file for easy integration with MCP CLI and agent platforms. Example:
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "shipxy-api-mcp": {
94
+ "command": "python",
95
+ "args": ["/path/to/your/server.py"],
96
+ "env": {
97
+ "SHIPXY_API_KEY": "your_api_key_here"
98
+ }
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ## CLI Usage
105
+
106
+ This project also provides a cross-platform CLI. Business commands stay flat and map directly to MCP tool names, with underscores converted to dashes:
107
+
108
+ ```bash
109
+ python -m venv .venv
110
+ source .venv/bin/activate
111
+ pip install -e .
112
+
113
+ shipxy auth status
114
+ shipxy tools
115
+ shipxy schema search-ship
116
+ shipxy search-ship COSCO --max 5
117
+ shipxy get-single-ship 413211000
118
+ shipxy search-port Shanghai
119
+ shipxy plan-route-by-port CNSHA SGSIN
120
+ shipxy get-weather-by-point --lng 123.58414 --lat 27.37979
121
+ ```
122
+
123
+ Windows PowerShell activation:
124
+
125
+ ```powershell
126
+ .\.venv\Scripts\Activate.ps1
127
+ ```
128
+
129
+ The CLI defaults to JSON output for LLM and agent calls. For human-readable output:
130
+
131
+ ```bash
132
+ shipxy search-ship COSCO --max 5 --format table
133
+ shipxy search-ship COSCO --max 5 --format pretty
134
+ shipxy search-ship COSCO --max 5 --format ndjson
135
+ ```
136
+
137
+ You can also start the MCP server through the CLI:
138
+
139
+ ```bash
140
+ shipxy mcp start
141
+ shipxy mcp start --transport sse --host 127.0.0.1 --port 8000
142
+ ```
143
+
144
+ Agent and MCP clients should configure the API key through the `SHIPXY_API_KEY` environment variable:
145
+
146
+ ```json
147
+ {
148
+ "mcpServers": {
149
+ "shipxy": {
150
+ "command": "shipxy",
151
+ "args": ["mcp", "start"],
152
+ "env": {
153
+ "SHIPXY_API_KEY": "your_api_key_here"
154
+ }
155
+ }
156
+ }
157
+ }
158
+ ```
159
+
160
+ ## 🧩 Supported APIs
161
+
162
+ | Tool Name | Description |
163
+ |--------------------------|------------------------------------------------------------------|
164
+ | search_ship | Fuzzy search for ships by MMSI, IMO, name, or call sign |
165
+ | get_single_ship | Query real-time info for a single ship by MMSI |
166
+ | get_many_ship | Query real-time info for multiple ships by MMSI list |
167
+ | get_fleet_ship | Query all ships in a fleet |
168
+ | get_surrounding_ship | Query ships within 10nm of a given ship |
169
+ | get_area_ship | Query ships in a specified area |
170
+ | get_ship_registry | Query ship registry/country info |
171
+ | search_ship_particular | Query ship particulars by MMSI/IMO/call sign/name |
172
+ | search_port | Fuzzy search for ports by name or code |
173
+ | get_berth_ships | Query ships currently berthed at a port |
174
+ | get_anchor_ships | Query ships at anchor at a port |
175
+ | get_eta_ships | Query ships with ETA to a port |
176
+ | get_ship_track | Query historical track points for a ship |
177
+ | search_ship_approach | Query ship-to-ship approach events |
178
+ | get_port_of_call_by_ship | Query port call records for a ship |
179
+ | get_port_of_call_by_port | Query port call records for a port |
180
+ | plan_route_by_point | Plan route between two coordinates |
181
+ | plan_route_by_port | Plan route between two ports |
182
+ | get_single_eta_precise | Get ETA and voyage info for a ship |
183
+ | get_weather_by_point | Query marine weather by coordinates |
184
+ | get_weather | Query marine weather by area |
185
+ | get_all_typhoon | List recent typhoons |
186
+ | get_single_typhoon | Query details for a specific typhoon |
187
+ | get_tides | List tide stations |
188
+ | get_tide_data | Query tide data for a station |
189
+
190
+ ## 🌍 Application Scenarios
191
+
192
+ - **Maritime Logistics & Fleet Management**
193
+ - **Vessel Tracking & Monitoring**
194
+ - **Port Operations & ETA Prediction**
195
+ - **Smart Shipping & Route Optimization**
196
+ - **Marine Weather & Safety Applications**
197
+
198
+ ## 📦 Project Structure
199
+
200
+ ```
201
+ .
202
+ ├── server.py # MCP server entry point
203
+ ├── ship_service.py # Shipxy API integration and business logic
204
+ ├── requirements.txt # Python dependencies
205
+ ├── pyproject.toml # Project metadata
206
+ └── README.md # This file
207
+ ```
208
+
209
+ ## 📄 License
210
+
211
+ MIT © shipxy-api-mcp contributors
212
+
213
+ ## 📞 Contact
214
+
215
+ For more information or business inquiries, please contact:
216
+
217
+ **Phone:** 400-010-8558 / 010-8286 8599
mcp_shipxy_api-0.1.0/README.md ADDED
@@ -0,0 +1,193 @@
1
+ # shipxy-api-mcp
2
+
3
+ <!-- mcp-name: io.github.garrettxu/mcp-shipxy-api -->
4
+
5
+ **Shipxy MCP Server** is a fully MCP-compliant, open-source Location-Based Service (LBS) solution for maritime scenarios, providing a comprehensive suite of ship and port APIs and tools for developers and AI agents. It enables seamless integration of real-time vessel data, route planning, weather, tides, and more into your applications.
6
+
7
+ ## 🚀 Introduction
8
+
9
+ **Shipxy MCP Server** empowers your applications, LLMs, and agents with advanced maritime data and geospatial intelligence, including:
10
+
11
+ - **Ship Information & Tracking:** Real-time vessel position, static info, fleet, and area queries.
12
+ - **Port & Berth Data:** Global port search, berth/anchor/ETA queries, port call records.
13
+ - **Route Planning:** Point-to-point and port-to-port route planning.
14
+ - **Weather & Tides:** Marine weather, typhoon, and tide station data.
15
+ - **Rich Maritime APIs:** Ship registry, particulars, approach events, and more.
16
+
17
+ All APIs follow the MCP protocol and can be called from any MCP-compliant client, LLM, or agent platform.
18
+
19
+ ## 🛠️ Key Features
20
+
21
+ - **Full MCP Protocol Support:** Seamless integration with any MCP-compliant agent, LLM, or platform.
22
+ - **Comprehensive Maritime Data:** Ships, ports, routes, weather, tides, and more.
23
+ - **Real-Time & Historical Data:** Live vessel tracking, voyage history, and event records.
24
+ - **Open Source & Extensible:** MIT licensed, easy to customize and extend.
25
+
26
+ ## ⚡ Quick Start
27
+
28
+ ### 1. Get Your API Key
29
+
30
+ Register and create a server-side API Key at [Shipxy Open Platform](https://api.shipxy.com/v3/console/overview).
31
+ **Note:** The API key is required for all requests.
32
+
33
+ ### 2. Installation
34
+
35
+ Install from PyPI after release:
36
+
37
+ ```bash
38
+ pipx install mcp-shipxy-api
39
+ ```
40
+
41
+ Or install into an existing virtual environment:
42
+
43
+ ```bash
44
+ pip install mcp-shipxy-api
45
+ ```
46
+
47
+ For local source development:
48
+
49
+ ```bash
50
+ pip install -r requirements.txt
51
+ ```
52
+
53
+
54
+ ### 3. Configuration
55
+
56
+ Create a `.env` file in your project root:
57
+
58
+ ```
59
+ SHIPXY_API_KEY=your_api_key_here
60
+ ```
61
+
62
+ ### 4. Start the Server
63
+
64
+ Recommended: Use an `mcp.json` configuration file for easy integration with MCP CLI and agent platforms. Example:
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "shipxy-api-mcp": {
70
+ "command": "python",
71
+ "args": ["/path/to/your/server.py"],
72
+ "env": {
73
+ "SHIPXY_API_KEY": "your_api_key_here"
74
+ }
75
+ }
76
+ }
77
+ }
78
+ ```
79
+
80
+ ## CLI Usage
81
+
82
+ This project also provides a cross-platform CLI. Business commands stay flat and map directly to MCP tool names, with underscores converted to dashes:
83
+
84
+ ```bash
85
+ python -m venv .venv
86
+ source .venv/bin/activate
87
+ pip install -e .
88
+
89
+ shipxy auth status
90
+ shipxy tools
91
+ shipxy schema search-ship
92
+ shipxy search-ship COSCO --max 5
93
+ shipxy get-single-ship 413211000
94
+ shipxy search-port Shanghai
95
+ shipxy plan-route-by-port CNSHA SGSIN
96
+ shipxy get-weather-by-point --lng 123.58414 --lat 27.37979
97
+ ```
98
+
99
+ Windows PowerShell activation:
100
+
101
+ ```powershell
102
+ .\.venv\Scripts\Activate.ps1
103
+ ```
104
+
105
+ The CLI defaults to JSON output for LLM and agent calls. For human-readable output:
106
+
107
+ ```bash
108
+ shipxy search-ship COSCO --max 5 --format table
109
+ shipxy search-ship COSCO --max 5 --format pretty
110
+ shipxy search-ship COSCO --max 5 --format ndjson
111
+ ```
112
+
113
+ You can also start the MCP server through the CLI:
114
+
115
+ ```bash
116
+ shipxy mcp start
117
+ shipxy mcp start --transport sse --host 127.0.0.1 --port 8000
118
+ ```
119
+
120
+ Agent and MCP clients should configure the API key through the `SHIPXY_API_KEY` environment variable:
121
+
122
+ ```json
123
+ {
124
+ "mcpServers": {
125
+ "shipxy": {
126
+ "command": "shipxy",
127
+ "args": ["mcp", "start"],
128
+ "env": {
129
+ "SHIPXY_API_KEY": "your_api_key_here"
130
+ }
131
+ }
132
+ }
133
+ }
134
+ ```
135
+
136
+ ## 🧩 Supported APIs
137
+
138
+ | Tool Name | Description |
139
+ |--------------------------|------------------------------------------------------------------|
140
+ | search_ship | Fuzzy search for ships by MMSI, IMO, name, or call sign |
141
+ | get_single_ship | Query real-time info for a single ship by MMSI |
142
+ | get_many_ship | Query real-time info for multiple ships by MMSI list |
143
+ | get_fleet_ship | Query all ships in a fleet |
144
+ | get_surrounding_ship | Query ships within 10nm of a given ship |
145
+ | get_area_ship | Query ships in a specified area |
146
+ | get_ship_registry | Query ship registry/country info |
147
+ | search_ship_particular | Query ship particulars by MMSI/IMO/call sign/name |
148
+ | search_port | Fuzzy search for ports by name or code |
149
+ | get_berth_ships | Query ships currently berthed at a port |
150
+ | get_anchor_ships | Query ships at anchor at a port |
151
+ | get_eta_ships | Query ships with ETA to a port |
152
+ | get_ship_track | Query historical track points for a ship |
153
+ | search_ship_approach | Query ship-to-ship approach events |
154
+ | get_port_of_call_by_ship | Query port call records for a ship |
155
+ | get_port_of_call_by_port | Query port call records for a port |
156
+ | plan_route_by_point | Plan route between two coordinates |
157
+ | plan_route_by_port | Plan route between two ports |
158
+ | get_single_eta_precise | Get ETA and voyage info for a ship |
159
+ | get_weather_by_point | Query marine weather by coordinates |
160
+ | get_weather | Query marine weather by area |
161
+ | get_all_typhoon | List recent typhoons |
162
+ | get_single_typhoon | Query details for a specific typhoon |
163
+ | get_tides | List tide stations |
164
+ | get_tide_data | Query tide data for a station |
165
+
166
+ ## 🌍 Application Scenarios
167
+
168
+ - **Maritime Logistics & Fleet Management**
169
+ - **Vessel Tracking & Monitoring**
170
+ - **Port Operations & ETA Prediction**
171
+ - **Smart Shipping & Route Optimization**
172
+ - **Marine Weather & Safety Applications**
173
+
174
+ ## 📦 Project Structure
175
+
176
+ ```
177
+ .
178
+ ├── server.py # MCP server entry point
179
+ ├── ship_service.py # Shipxy API integration and business logic
180
+ ├── requirements.txt # Python dependencies
181
+ ├── pyproject.toml # Project metadata
182
+ └── README.md # This file
183
+ ```
184
+
185
+ ## 📄 License
186
+
187
+ MIT © shipxy-api-mcp contributors
188
+
189
+ ## 📞 Contact
190
+
191
+ For more information or business inquiries, please contact:
192
+
193
+ **Phone:** 400-010-8558 / 010-8286 8599