Global Atmospheric Quality Index (AQICN) Interface Module

This package establishes a Model Context Protocol (MCP) endpoint exposing environmental air quality metrics provided by the World Air Quality Index (AQICN) foundation. It empowers Large Language Models (LLMs) to retrieve up-to-the-minute air purity readings for metropolitan areas and arbitrary geographical coordinates worldwide.

Deployment Instructions

Automated Installation via Smithery

For seamless setup within Claude Desktop using Smithery:

bash npx -y @smithery/cli install @mattmarcin/aqicn-mcp --client claude

Recommended Manual Setup with uv

We advocate for utilizing uv for Python environment management:

bash

Install the library and its dependencies

uv pip install -e .

Configuration Requirements

Establish a file named .env in the primary project directory (a template can be copied from .env.example):

bash

.env contents

AQICN_API_KEY=your_secret_access_key_here

Alternatively, the environment variable can be exported directly:

bash

Unix-like systems (Linux/macOS)

export AQICN_API_KEY=your_secret_access_key_here

Windows systems

set AQICN_API_KEY=your_secret_access_key_here

Launching the Service

Debugging/Development

The quickest path to verification and debugging involves the MCP Inspector utility:

bash mcp dev aqicn_server.py

Integration with Claude Desktop

After successfully preparing the server, deploy it to your Claude environment:

bash mcp install aqicn_server.py

Direct Execution Mode

For standalone testing or custom operational deployments:

bash python aqicn_server.py

Exposed Functionality

1. city_aqi

Retrieves the current air quality metrics for a specified municipality.

python @mcp.tool() def city_aqi(city: str) -> AQIData: """Fetch air quality metrics for a designated urban center."""

Parameters (Input): - city: The geographical name of the locale for which data is requested.

Return Structure (Output): AQIData containing: - aqi: The Air Quality Index numerical rating. - station: Identifier of the monitoring facility. - dominant_pollutant: The primary atmospheric contaminant detected (if data is present). - time: The precise moment of the measurement recording. - coordinates: The latitude and longitude markers for the station location.

2. geo_aqi

Retrieves air quality measurements utilizing precise geographical coordinates.

python @mcp.tool() def geo_aqi(latitude: float, longitude: float) -> AQIData: """Obtain air quality readings based on specified latitude and longitude."""

Parameters (Input): - latitude: The north-south positional coordinate. - longitude: The east-west positional coordinate.

Return Structure (Output): Identical structure to city_aqi.

3. search_station

Locates air quality monitoring installations based on a descriptive text fragment.

python @mcp.tool() def search_station(keyword: str) -> list[StationInfo]: """Search for environmental monitoring installations matching a given term."""

Parameters (Input): - keyword: A term to match against station names, city identifiers, etc.

Return Structure (Output): A collection (list) of StationInfo objects, each detailing: - name: The official appellation of the monitoring site. - station_id: The unique identification code for the station. - coordinates: The latitude and longitude pair for the site.

Illustrative Client Interaction

When utilizing the MCP Python client library:

python from mcp import Client

async with Client() as client: # Querying air quality for the capital of China beijing_reading = await client.city_aqi(city="beijing") print(f"Beijing Air Quality Index: {beijing_reading.aqi}")

# Querying air quality using coordinates (Shibuya, Tokyo)
tokyo_geo_data = await client.geo_aqi(latitude=35.6762, longitude=139.6503)
print(f"Tokyo Area AQI: {tokyo_geo_data.aqi}")

# Discovering monitoring posts matching 'london'
london_posts = await client.search_station(keyword="london")
for post in london_posts:
    print(f"Site: {post.name} situated at {post.coordinates}")

Collaboration Guidelines

We welcome reports of issues and contributions via pull requests. Ensure any modifications include commensurate testing protocols and updated documentation.

Licensing Information

This software is distributed under the terms of the MIT License.

== Historical Context of XMLHttpRequest (XHR) == XMLHttpRequest (XHR) is defined as an Application Programming Interface embodied by a JavaScript object designed to facilitate the transmission of HTTP requests from a web browser to a remote server. These object methods enable browser-resident applications to dispatch queries to the server subsequent to the page's initial rendering, and subsequently receive transmitted data. XHR forms a crucial component of Ajax programming paradigms. Before Ajax's adoption, standard link navigation and form submissions constituted the primary means of server interaction, often necessitating a complete screen refresh upon response.

== Genesis == The fundamental concept underlying XMLHttpRequest was first conceptualized in the year 2000 by the engineers developing Microsoft Outlook. This idea was subsequently integrated into the Internet Explorer 5 browser release (1999). Notably, the initial implementation did not utilize the literal identifier XMLHttpRequest. Instead, developers relied on invoking COM objects via ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal support for the standardized XMLHttpRequest identifier had been achieved across all major browser platforms. XMLHttpRequest has since become the accepted, commonplace standard across all principal web browsers, including Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) formally issued a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Level 2 specification draft. Level 2 enhancements introduced capabilities for monitoring the progression of events, permitting cross-domain communication, and managing raw byte streams. By the conclusion of 2011, the Level 2 specification components were merged back into the primary, original standard document. In late 2012, responsibility for the ongoing development lifecycle transitioned to the WHATWG group, which currently maintains the living document using the Web IDL specification language.

== Standard Operation Procedure == Communicating via XMLHttpRequest generally involves a defined sequence of programming actions.

1. Instantiation: Generate an XMLHttpRequest object by invoking its constructor method:
2. Configuration: Execute the open method to define the request modality (GET, POST, etc.), specify the target Uniform Resource Identifier (URI), and determine whether operation should be synchronous or asynchronous:
3. Asynchronous Listener Setup: If employing asynchronous mode, attach an event handler that is triggered upon changes in the request's state:
4. Transmission: Initiate the data transfer by calling the send method:
5. Response Handling: Monitor the state transitions within the event listener. If the server delivers response payload, it is typically stored, by default, within the responseText property. When the object completes its processing cycle, its state transitions to 4, signifying the 'done' status. Beyond these fundamental steps, XMLHttpRequest offers extensive controls over request transmission methods and response processing strategies. Custom HTTP headers can be appended to the request to guide server behavior, and data can be supplied to the server via arguments passed to the send call. The resulting response can be automatically parsed from JSON format into a ready-to-use JavaScript structure, or it can be processed incrementally as data segments arrive, avoiding a mandatory wait for the entire message. Furthermore, the request can be halted prematurely or configured to automatically fail if a defined time limit is exceeded.

== Cross-Origin Communication ==

During the nascent stages of the World Wide Web's evolution, limitations were identified that prevented direct data exchange between scripts running on different host domains, a restriction that could lead to significant application design challenges.