mcp-opendata

# MCP Tool: New Taipei City Transportation Bureau OpenData Query This is an MCP (Multi-Cloud Platform) tool for querying OpenData from the New Taipei City Transportation Bureau. This tool allows users to directly query New Taipei City's transportation-related OpenData applications in Claude and get responses. ## Features - Integrates New Taipei City Transportation Bureau OpenData API - Provides a simple command-line interface - Supports various transportation data queries (e.g., bus routes, stop information, real-time traffic conditions, etc.) - Data filtering and sorting options - Error handling and friendly prompts - MCP service integration ## Installation ### Using uv (Recommended) ```bash # Install uv (if not already installed) curl -LsSf https://astral.sh/uv/install.sh | sh # Create a virtual environment uv venv # Activate the virtual environment source .venv/bin/activate # Linux/macOS # Or .venv\Scripts\activate # Windows # Install dependencies uv pip install -e . # Install development dependencies (optional) uv pip install -e ".[dev]" ``` ### Using Traditional pip ```bash # Create a virtual environment python -m venv .venv # Activate the virtual environment source .venv/bin/activate # Linux/macOS # Or .venv\Scripts\activate # Windows # Install dependencies pip install -e . ``` ### Install using MCP ```bash mcp install ntpc_opendata_tool/server.py --name "新北市交通 OpenData 查詢" --with requests --with python-dotenv --with uvicorn --with typer --with pandas ``` ## Usage ### Command-Line Tool #### Bus Query ```bash # View all command instructions ntpc-opendata --help # View bus-related commands ntpc-opendata bus --help # Query bus routes ntpc-opendata bus routes 307 # Query bus stops ntpc-opendata bus stops 307 # Query bus arrival time ntpc-opendata bus arrival 307 --stop "捷運板橋站" # Query all stops ntpc-opendata bus all-stops # Search for buses by specific stop ntpc-opendata bus search-by-stop "捷運板橋站" # Query real-time bus location ntpc-opendata bus real-time 307 # Query bus operator information ntpc-opendata bus operators # Query bus transfer discounts ntpc-opendata bus transfer-discounts # Query route information ntpc-opendata bus route-info --type "快速公車" 307 ``` #### Bike Query ```bash # View bike-related commands ntpc-opendata bike --help # Query YouBike stations ntpc-opendata bike youbike --area "板橋區" # Query stations with available bikes ntpc-opendata bike available-bikes --min-bikes 5 # Query nearby YouBike stations ntpc-opendata bike nearby-youbike 25.0132 121.4670 --radius 500 # Query bike racks ntpc-opendata bike bike-racks --area "板橋區" --near-mrt # Query bike lanes ntpc-opendata bike bike-lanes ``` #### Parking Query ```bash # View parking-related commands ntpc-opendata parking --help # Query parking lot list ntpc-opendata parking list --area "板橋區" # Query parking lot details ntpc-opendata parking info P-TY-0001 # Query parking lots with available spaces ntpc-opendata parking available --min-spaces 5 --area "板橋區" # Query parking fee rates ntpc-opendata parking fee-rates # Query nearby parking lots ntpc-opendata parking nearby 25.0132 121.4670 --radius 500 # Query real-time status ntpc-opendata parking status ``` #### Traffic Condition Query ```bash # View traffic condition-related commands ntpc-opendata traffic --help # Query real-time traffic conditions ntpc-opendata traffic status --area "板橋區" # Query road construction information ntpc-opendata traffic construction --area "板橋區" # Query traffic cameras ntpc-opendata traffic cameras --area "板橋區" # Query traffic incidents ntpc-opendata traffic incidents --area "板橋區" --type "事故" ``` #### Other Traffic Service Query ```bash # View other traffic service-related commands ntpc-opendata misc-traffic --help # Query taxi services ntpc-opendata misc-traffic taxi-services # Search taxi services ntpc-opendata misc-traffic search-taxi "大都會" # Query towing storage ntpc-opendata misc-traffic towing-storage # Query the nearest towing storage ntpc-opendata misc-traffic nearest-towing 25.0132 121.4670 # Query traffic impact assessment ntpc-opendata misc-traffic impact-assessment ``` ### Using as an MCP Service In Claude, you can directly call this MCP service. Here are some practical query examples: #### Bus Query Examples ``` # Query specific route I want to query the route information for the New Taipei City 307 bus. When will the 307 bus arrive at the MRT Banqiao Station? What are the first and last bus times for the 307 bus? # Query bus by stop What bus routes are available at MRT Banqiao Station? What are the bus arrival times at MRT Banqiao Station? What bus routes go to Taipei from MRT Banqiao Station? # Query route type What express bus routes are available in Banqiao District? What blue line bus routes are available in New Taipei City? # Query operator information What bus operators are there in New Taipei City? Which bus routes have transfer discounts? ``` #### Bike Query Examples ``` # Query YouBike stations What YouBike stations are there in Banqiao District? Is there a YouBike available near MRT Banqiao Station? Which YouBike stations still have bikes available? # Query bike facilities Where are the bike lanes in Banqiao District? Are there bike racks near the MRT station? What is the total length of the bike lanes in Banqiao District? ``` #### Parking Query Examples ``` # Query parking information Which parking lots in Banqiao District still have spaces available? What are the parking fees near MRT Banqiao Station? Is there motorcycle parking near Banqiao Station? # Query special parking needs Which women and children parking spaces are available in Banqiao District? Where are the disabled parking spaces in Banqiao District? Which road sections can be parked on during typhoons? ``` #### Traffic Condition Query Examples ``` # Query real-time traffic conditions What is the current traffic situation in Banqiao District? Is there traffic on Wenhua Road now? What is the traffic situation from Banqiao to Taipei? # Query traffic facilities What traffic cameras are there in Banqiao District? Where are the ETag devices in Banqiao District? What height limit facilities are there in Banqiao District? # Query construction information Which roads in Banqiao District are currently under construction? Is there any construction on Wenhua Road recently? What major projects are there in New Taipei City recently? ``` #### Other Traffic Service Query Examples ``` # Query taxi services What legal taxi companies are there in Banqiao District? Please find the phone number for Metropolitan Taxi. Is there a taxi service nearby? # Query towing information Where is the towing storage in Banqiao District? My car was towed, where do I go to pick it up? Where is the nearest towing storage? # Query traffic assessment What major construction projects in Banqiao District will affect traffic? What are the results of the traffic impact assessment for the Xinban Special District? ``` ## API Module Resources This tool provides multiple API modules that can be used directly in your Python programs: ### Bus Information (BusAPI) ```python from ntpc_opendata_tool.api.bus import BusAPI bus_api = BusAPI() # Query bus routes routes = bus_api.get_routes(route_name="307") # Query bus stops stops = bus_api.get_stops(route_name="307") # Query estimated bus arrival time estimated_times = bus_api.get_estimated_time(route_name="307", stop_name="捷運板橋站") # Query all stops all_stops = bus_api.get_all_stops() # Search by stop name stop_search = bus_api.search_by_stop(stop_name="捷運板橋站") # Query real-time bus location real_time = bus_api.get_real_time_by_route(route_name="307") # Query bus operator information operators = bus_api.get_bus_operators() # Query bus transfer discounts discounts = bus_api.get_bus_transfer_discounts() # Query route information route_info = bus_api.get_route_info(route_type="快速公車", route_name="307") ``` ### Bike Information (BikeAPI) ```python from ntpc_opendata_tool.api.bike import BikeAPI bike_api = BikeAPI() # Query YouBike stations youbike_stations = bike_api.get_youbike_stations(area="板橋區") # Query available YouBike available_bikes = bike_api.get_available_youbikes(min_bikes=5) # Query nearby YouBike stations nearby_youbike = bike_api.find_nearby_youbike(lat=25.0132, lon=121.4670, radius=500) # Query bike racks bike_racks = bike_api.get_bike_racks(area="板橋區", near_mrt=True) # Query bike lanes bike_lanes = bike_api.get_bike_lanes() ``` ### Parking Information (ParkingAPI) ```python from ntpc_opendata_tool.api.parking import ParkingAPI parking_api = ParkingAPI() # Query parking lots parking_lots = parking_api.get_parking_lots(area="板橋區") # Query specific type of parking lots type_parking = parking_api.get_parking_lots_by_type(lot_type="路邊停車") # Query parking lot details parking_detail = parking_api.get_parking_lot_detail(parking_id="P-TY-0001") # Query parking lots with available spaces available_parking = parking_api.get_available_parking_lots(min_spaces=5, area="板橋區") # Query roadside parking spaces roadside_parking = parking_api.get_roadside_parking_spaces(area="板橋區") # Query nearby parking lots nearby_parking = parking_api.get_nearby_parking_lots(lat=25.0132, lon=121.4670, radius=500) # Query motorcycle parking motorcycle_parking = parking_api.get_motorcycle_parking(area="板橋區") # Query women and children parking spaces women_children_parking = parking_api.get_women_children_parking(area="板橋區") # Query disabled parking spaces disabled_parking = parking_api.get_disabled_parking(area="板橋區") # Query road sections where parking is allowed during typhoons typhoon_parking = parking_api.get_typhoon_parking() # Query roadside parking management information roadside_management = parking_api.get_roadside_parking_management() ``` ### Traffic Information (TrafficAPI) ```python from ntpc_opendata_tool.api.traffic import TrafficAPI traffic_api = TrafficAPI() # Query traffic cameras cameras = traffic_api.get_traffic_cameras(district="板橋區") # Query ETag locations etag_locations = traffic_api.get_etag_locations(district="板橋區") # Query height limit information height_limits = traffic_api.get_height_limit_info(area="板橋區", road="文化路") # Query traffic impact assessment impact_assessments = traffic_api.get_traffic_impact_assessment() # Query nearby traffic cameras nearby_cameras = traffic_api.get_nearby_traffic_cameras(lat=25.0132, lon=121.4670, radius=1000) ``` ### Other Traffic Information (MiscTrafficAPI) ```python from ntpc_opendata_tool.api.misc_traffic import MiscTrafficAPI misc_api = MiscTrafficAPI() # Query taxi services taxi_services = misc_api.get_taxi_services() # Query towing storage information towing_storage = misc_api.get_towing_storage_info() # Query traffic impact assessment impact_assessment = misc_api.get_traffic_impact_assessment() # Query the nearest towing storage nearest_towing = misc_api.find_nearest_towing_storage(lat=25.0132, lon=121.4670) # Search taxi services taxi_search = misc_api.search_taxi_service(keyword="大都會") ``` ### Base API Client (OpenDataClient) ```python from ntpc_opendata_tool.api.client import OpenDataClient client = OpenDataClient() # Query directly using resource ID response = client.get_by_resource_id("382000000A-000187-001") # Custom GET request custom_response = client.get("/endpoint", params={"key": "value"}) # Custom POST request post_response = client.post("/endpoint", data={"key": "value"}) ``` ## Development ### Environment Setup ```bash # Install development dependencies pip install -e ".[dev]" # Run tests pytest ``` ### Directory Structure ``` ntpc_opendata_tool/ ├── ntpc_opendata_tool/ │ ├── __init__.py │ ├── api/ # API related modules │ ├── cli/ # Command-line interface │ ├── models/ # Data model definitions │ ├── utils/ # Utility functions │ └── server.py # MCP service main entry point ├── pyproject.toml # Project settings ├── README.md # Project description └── .env.example # Example environment variables ``` ## License This project is licensed under the MIT License.