This directory contains several utility scripts to help test, run, and interact with the Climatiq API and MCP server.
A comprehensive test client that connects to the MCP server and tests all tools, prompts, and resources.
Features:
- Starts the MCP server as a subprocess (if not already running)
- Tests all available tools with sample parameters
- Examines resources created during tool execution
- Tests the climate-impact-explanation prompt with calculation results
Usage:
python utils/test_client.pyDemonstrates how a Large Language Model (like Claude) could interact with the Climatiq MCP server.
Features:
ClimatiqAssistantclass that wraps the MCP client for easier integration with LLMs- Helper methods for all Climatiq tools with proper parameter handling
- Example conversation flows for different carbon calculation scenarios
- Methods to obtain and explain detailed climate impact information
Usage:
python utils/llm_example_client.pyA command-line interface tool for direct API access without the MCP protocol overhead.
Features:
- Direct API requests to Climatiq
- Simple interface for common emission calculations
- User-friendly results with detailed information about emission factors
- Option to view the full JSON API response
Usage:
# For electricity emissions
python utils/climatiq_cli.py electricity --energy 1000 --unit kWh --region US
# For travel emissions
python utils/climatiq_cli.py travel --mode car --distance 100 --unit km --region US
# For search
python utils/climatiq_cli.py search --query "grid mix" --region USA simple script to run the MCP server directly without installing the package.
Features:
- Adds the source directory to the Python path
- Runs the server's main function directly
- Useful for development and testing
Usage:
python utils/run_mcp_server.pyIf you're having issues with the MCP server, you can use these utilities to isolate the problem:
- Use
climatiq_cli.pyto verify direct API access - Use
test_client.pyto test the MCP server implementation - Use
llm_example_client.pyto test specific LLM interaction patterns
During development:
- Run the MCP server with
run_mcp_server.py - Test your changes with
test_client.py - Use
llm_example_client.pyto see how your changes affect LLM interactions
These utilities require the same dependencies as the main package:
aiohttpasync-timeoutpython-dotenvpydanticmodelcontextprotocol(for MCP-related utilities)
Most of these are installed automatically when you set up the environment using:
# Create a virtual environment
uv venv
# Activate the environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies with development extras
uv sync --dev --extras